異步通知

支付回調:驗簽、訂單核對與冪等交付

回調可能延遲或重復送達。你的服務端需要接收 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 ↗