异步通知

支付回调:验签、订单核对与幂等交付

回调可能延迟或重复送达。你的服务端需要接收 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。
returnCode00 表示业务成功。
successTime成功时间,格式 yyyy-MM-dd HH:mm:ss。
notifyTime本次通知时间,格式同上。
sign业务签名,不参与自身签名。

通知示例中各字段均使用字符串。先保留收到的原值验签,尤其是 00 和 10.00;不要在验签前格式化、去零或强转数值。

先验签,再核对订单与支付结果

  1. 读取 JSON,保留字段原值,提取 Body 中的 sign。
  2. 优先取 CALLBACK_SECRET,未单独配置时取 MD5_SECRET。
  3. 排除 sign 和空字段,按字段名 ASCII 升序拼接,追加 &key=密钥,计算小写 MD5 后比较。
  4. 验签通过后核对商户号、业务类型、商户订单号及平台订单号,定位真实本地订单。
  5. 核对金额分、币种和支付成功状态,再进入幂等处理。

不能只看 returnCode=00 或 orderStatus=1 就发货。验签、订单身份、金额、币种和成功状态应完整通过;不一致时停止交付并记录异常。

兼容头 X-Plat-Signature 的规则由技术人员另行确认。本页使用 Body 的标准业务签名,不是对整个 JSON 原文直接做 MD5。

Python 验签 + 业务流程示意
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。

同一订单只记一次支付、交付一次

  1. 校验并定位订单验签、核对金额币种,找到同一商户支付记录。
  2. 事务内更新状态锁定订单或条件更新;已成功通知不重复记账。
  3. 保存唯一交付任务以订单唯一键记录发卡、充值或发货任务。
  4. 提交后再确认状态及任务可靠保存后返回 OK,交付可继续重试。
收到通知
  验签失败:拒绝处理,不返回成功确认
  商户、订单、金额或币种不符:记录异常,不交付
  开启数据库事务
    查询并锁定本地订单
    若尚未成功:更新支付成功状态
    确保交付任务存在,业务唯一键 = 本地订单ID
  提交数据库事务
  返回 HTTP 200,纯文本 OK

交付任务
  若业务唯一键已完成交付:结束
  否则安全交付一次并记录结果
  临时失败:保留任务,按业务规则重试

这是业务伪代码,并非可直接运行的事务。无法在同一事务完成商品交付时,应使用持久化任务和唯一交付记录,避免支付已成功、进程重启后却永远没有发货。

正确返回OK与处理重试

成功确认需同时满足 HTTP 200,响应 Body 包含 success、ok 或 OK。建议直接返回纯文本 OK,不用登录页、HTML 模板或框架默认 JSON 包装。

确认已处理的重复通知也返回 OK。数据库不可用、验签失败或业务校验未通过时,不能为了停止重试而先确认成功。

通知失败会异步重试,最多共通知 3 次,包含首次发送;前两次失败后分别约 60 秒和 300 秒重试。它不是无限重试,也不是首次之外再发送三次。

未收到通知时主动查单补偿

规范明确了支付成功后的通知,不应假定失败、关闭、失效也一定推送。对长时间待支付、下单超时或通知处理异常的订单,后端需要主动查单。

查单确认成功后进入与回调相同的幂等交付流程,不另写跳过金额核对的发货路径。查询金额口径在开通时确认后再转换比较;未知结果保留待核实。

联调至少测试重复通知、先查单后回调、先回调后查单、数据库临时失败,以及成功后的交付重试。技术人员会协助确认具体配置和异常处理。

本文依据稳付pay接入规范整理。返回接入总览或查看下单与查询字段。

按你的业务场景确认接入

说明商品、订单量、支付方式与结算需求,逐项确认接口、资金路径和异常处理。

联系稳付pay ↗