支付回調:驗簽、訂單核對與冪等交付
回調可能延遲或重復送達。你的服務端需要接收 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 秒重試。它不是無限重試,也不是首次之外再發送三次。
未收到通知時主動查單補償
規范明確了支付成功后的通知,不應假定失敗、關閉、失效也一定推送。對長時間待支付、下單超時或通知處理異常的訂單,后端需要主動查單。
查單確認成功后進入與回調相同的冪等交付流程,不另寫跳過金額核對的發貨路徑。查詢金額口徑在開通時確認后再轉換比較;未知結果保留待核實。
聯調至少測試重復通知、先查單后回調、先回調后查單、數據庫臨時失敗,以及成功后的交付重試。技術人員會協助確認具體配置和異常處理。