支付回调:验签、订单核对与幂等交付
回调可能延迟或重复送达。你的服务端需要接收 JSON、验证签名、核对订单并可靠保存成功状态,再把结果送入可安全重试的业务交付流程。
文章目录
通知什么时候发到你的服务器
平台收到通道支付成功通知并更新代收订单后,会向订单的 notifyUrl 异步 POST,Content-Type 为 application/json。无订单通知地址时使用商户默认地址;你的下单仍应按要求传入 notifyUrl。
通知接口应允许公网访问,不依赖浏览器登录态。收到的是稳付pay统一格式,无需解析上游原始参数。浏览器成功页和用户截图都不能代替后端核验。
标准通知的15个字段
| 字段 | 含义与核对方式 |
|---|---|
bizType | 代收固定为 collect。 |
mchId | 必须匹配本地订单所属商户。 |
platformOrderNo | 平台订单号,与本地支付记录关联。 |
outTradeNo | 下单时填写的商户订单号。 |
merchantOrderNo | 兼容字段,与 outTradeNo 相同。 |
transactionId | 通道流水;通道未返回时使用平台订单号。 |
amount | 金额分,例如字符串 1000。 |
amountYuan | 金额元,保留两位小数,例如 10.00。 |
currencyCode | 币种,例如 CNY。 |
orderStatus | 订单状态,成功通知示例为字符串 1。 |
tradeState | 代收成功为 SUCCESS。 |
returnCode | 00 表示业务成功。 |
successTime | 成功时间,格式 yyyy-MM-dd HH:mm:ss。 |
notifyTime | 本次通知时间,格式同上。 |
sign | 业务签名,不参与自身签名。 |
通知示例中各字段均使用字符串。先保留收到的原值验签,尤其是 00 和 10.00;不要在验签前格式化、去零或强转数值。
先验签,再核对订单与支付结果
- 读取 JSON,保留字段原值,提取 Body 中的
sign。 - 优先取
CALLBACK_SECRET,未单独配置时取MD5_SECRET。 - 排除 sign 和空字段,按字段名 ASCII 升序拼接,追加
&key=密钥,计算小写 MD5 后比较。 - 验签通过后核对商户号、业务类型、商户订单号及平台订单号,定位真实本地订单。
- 核对金额分、币种和支付成功状态,再进入幂等处理。
不能只看 returnCode=00 或 orderStatus=1 就发货。验签、订单身份、金额、币种和成功状态应完整通过;不一致时停止交付并记录异常。
兼容头 X-Plat-Signature 的规则由技术人员另行确认。本页使用 Body 的标准业务签名,不是对整个 JSON 原文直接做 MD5。
import json
import os
from wenfupay_collect_sign import verify_collect_notification
try:
notice = json.loads(raw_request_body)
except (ValueError, UnicodeDecodeError):
return http_response(400, "INVALID_JSON")
if not isinstance(notice, dict):
return http_response(400, "INVALID_JSON_OBJECT")
verified = verify_collect_notification(
notice,
api_secret=os.environ["MD5_SECRET"],
callback_secret=os.environ.get("CALLBACK_SECRET"),
)
if not verified:
return http_response(400, "INVALID_SIGNATURE")
# Business-specific pseudocode: implement these durable operations.
with database_transaction():
order = lock_order(notice["outTradeNo"])
match_merchant_currency_and_amount_in_cents(order, notice)
require_documented_success_fields(notice)
record_payment_once(order, notice["platformOrderNo"])
enqueue_fulfillment_once(order)
# Only after successful durable acceptance:
return http_response(200, "OK", content_type="text/plain")业务处理函数为流程示意,需接入商户自己的订单与数据库。持久化失败、签名不符或金额不符时不能先回复成功;已可靠接收过的重复通知,核实后可直接返回 OK。
同一订单只记一次支付、交付一次
- 校验并定位订单验签、核对金额币种,找到同一商户支付记录。
- 事务内更新状态锁定订单或条件更新;已成功通知不重复记账。
- 保存唯一交付任务以订单唯一键记录发卡、充值或发货任务。
- 提交后再确认状态及任务可靠保存后返回 OK,交付可继续重试。
收到通知
验签失败:拒绝处理,不返回成功确认
商户、订单、金额或币种不符:记录异常,不交付
开启数据库事务
查询并锁定本地订单
若尚未成功:更新支付成功状态
确保交付任务存在,业务唯一键 = 本地订单ID
提交数据库事务
返回 HTTP 200,纯文本 OK
交付任务
若业务唯一键已完成交付:结束
否则安全交付一次并记录结果
临时失败:保留任务,按业务规则重试这是业务伪代码,并非可直接运行的事务。无法在同一事务完成商品交付时,应使用持久化任务和唯一交付记录,避免支付已成功、进程重启后却永远没有发货。
正确返回OK与处理重试
成功确认需同时满足 HTTP 200,响应 Body 包含 success、ok 或 OK。建议直接返回纯文本 OK,不用登录页、HTML 模板或框架默认 JSON 包装。
确认已处理的重复通知也返回 OK。数据库不可用、验签失败或业务校验未通过时,不能为了停止重试而先确认成功。
通知失败会异步重试,最多共通知 3 次,包含首次发送;前两次失败后分别约 60 秒和 300 秒重试。它不是无限重试,也不是首次之外再发送三次。
未收到通知时主动查单补偿
规范明确了支付成功后的通知,不应假定失败、关闭、失效也一定推送。对长时间待支付、下单超时或通知处理异常的订单,后端需要主动查单。
查单确认成功后进入与回调相同的幂等交付流程,不另写跳过金额核对的发货路径。查询金额口径在开通时确认后再转换比较;未知结果保留待核实。
联调至少测试重复通知、先查单后回调、先回调后查单、数据库临时失败,以及成功后的交付重试。技术人员会协助确认具体配置和异常处理。