發卡平臺支付對接:驗簽、冪等、庫存鎖與自動交付
自動發卡不是收到一個“支付成功”字符串就發出一份卡密。可靠的流程需要把可信支付通知、訂單狀態、庫存分配和交付任務銜接起來,并允許網絡重試、進程重啟和人工修復。本文給出與供應商無關的通用設計;所有字段、簽名方式和應答內容都要按實際接入協議實現,不能直接當作稳付pay的接口說明。
文章目錄
將付款與交付拆成兩個狀態維度
至少區分待支付、已支付、已退款等付款狀態,以及待分配、已分配、已交付和交付異常等交付狀態。否則客戶付款后遇到庫存不足,系統只能在“成功”與“失敗”之間二選一,無法保留真實的中間事實。
- 創建訂單服務端固定商品、金額、幣種與有效期
- 確認付款驗簽、核對字段并持久化支付事實
- 分配庫存事務中鎖定訂單與對應卡密
- 執行交付持久任務重試并保留交付結果
購買數量、價格和優惠由服務器計算,不能直接采用瀏覽器提交的最終金額。訂單保存當時的價格快照,之后商品漲價也不應改變已經創建的付款要求。
先驗簽,再核對商戶、金額和業務歸屬
回調處理在后端執行,依照支付文檔驗證簽名、簽名覆蓋的數據、時間窗口和密鑰。供應商若要求使用原始請求體,應在框架解析或重新序列化之前保留原始字節。Stripe 的 Webhook 指南可作為這種機制的一個具體例子,其字段和簽名頭不能直接套到其他服務。
簽名通過只說明消息符合該密鑰對應的協議,還要核對商戶身份、訂單歸屬、支付交易號、幣種、實際金額及最終成功狀態。金額用明確的最小單位整數或精確定點數比較,不能采用有精度誤差的浮點近似相等。
USDT 還需要核對網絡、收款地址與對應的資產標識,不能只看代幣顯示名稱。前端 return 地址、支付截圖和客戶口述都不能替代這些檢查。密鑰必須留在服務端,不能放在網頁腳本中。
去重需要數據庫約束,不能只寫“先查詢”
失敗場景一:兩條通知同時到達,兩個進程都查詢到訂單未交付,于是各發一份卡密。先查詢再寫入之間存在競爭,單機運行也可能發生。去重必須落到數據庫的唯一約束和事務中,而不是只依賴內存標記。
至少分別考慮事件去重、支付交易去重和業務交付去重。相同付款可能產生不同事件編號,只有事件編號唯一仍可能重復認領付款;同一事件重復投遞則不應再次推進狀態。已處理的重復通知,可以在核實其持久記錄后按協議確認。
以下依次是通知表、付款表、交付任務表和庫存分配表中的通用約束示意,不是同一張表的完整建表腳本;字段非空、作用域和實際語法需一并設計。PostgreSQL 的約束文檔解釋了唯一約束的數據庫保障。
UNIQUE (provider, provider_event_id)
UNIQUE (provider, provider_transaction_id)
UNIQUE (order_id, fulfillment_kind)
UNIQUE (card_id)用事務保護庫存分配,避免最后一份庫存超賣
處理成功付款時,在事務中鎖定對應訂單,再檢查它是否已經分配庫存。對待分配卡密采用行鎖或帶狀態條件的原子更新,分配記錄與訂單狀態一同提交。不能先把卡密發給客戶,再回頭嘗試把數據庫標成已售。
如果采用比較并更新,也就是 CAS 思路,更新條件應包含“仍可用”,并檢查影響行數是否恰好為一;影響零行時要重新選庫存或進入缺貨流程。多件訂單應有明確的整體分配規則,不能無意中只交付一部分。
PostgreSQL 的行鎖說明展示了并發訪問的協調方式。鎖應持有盡可能短的時間,外部郵件或授權接口不放進長事務;發生死鎖或可重試沖突時,按數據庫語義重試完整事務,并保持操作冪等。
用 Outbox 銜接數據庫與外部交付
事務可以保證訂單和庫存一起保存,卻不能讓數據庫與郵件供應商天然同時成功。解決思路是在提交業務數據的同一事務中,寫入一條持久的待交付任務,也就是 Outbox;獨立任務進程隨后發送通知并記錄結果。
# Generic flow; adapt to the actual provider protocol.
event = verify_provider_request(raw_request)
with database_transaction():
persist_inbox_event_once(event)
record_verified_payment_once(event)
allocate_inventory_if_needed(event.order_id)
persist_outbox_job_once(event.order_id)
return protocol_ack_after_commit()
這是流程示意,省略了重復事件、校驗失敗和缺貨分支。無可用庫存時應提交“已付款待處理”及受控人工任務,不創建虛假的已交付記錄。持久化失敗不能先返回業務接收成功,應按協議讓對方重試或進入明確的補償查詢。
接收成功不必等到郵件發出,但前提是通知和后續任務已經可靠落盤。只有內存隊列沒有持久化時,提前應答后重啟就可能永久丟失交付工作。
缺貨、晚到付款與重復執行分別處理
失敗場景二:訂單超時釋放了庫存,客戶的付款通知晚到。系統若忽略關閉訂單,會留下已付款未處理;若直接沿用舊庫存分配,又可能把已經賣出的碼發給第二個人。應記錄付款事實,重新檢查庫存和訂單規則,轉補貨、人工履約或退款流程。
任務進程可能在外部交付完成后、寫回成功狀態前崩潰。重試時仍使用同一個交付編號;如果外部系統支持冪等鍵或結果查詢,應優先使用。若對方沒有相關能力,必須設計核對和人工分支,不能宣稱僅靠本地隊列即可做到外部操作絕不重復。
已分配的同一張卡密可以通過受控渠道重新展示給原訂單客戶,但不應因此再消耗一份庫存。重發郵件與重新發貨是不同操作,管理后臺需要分清權限和審計記錄。
退款和對賬保留完整歷史,不刪除付款記錄
退款是獨立業務事件,可能有申請中、成功、失敗或部分退款等狀態。不要通過刪訂單或直接改回未支付表達退款。需要記錄原支付交易、退款關聯號、金額和操作人,并與支付側的最終結果核對。
數字商品是否已被查看或兌換,影響售后處理,但不意味著可以任意自動退款或重新入庫。無法撤銷的授權碼不能在退款后直接放回可售庫存;可撤銷授權也要先確認撤銷結果,再決定后續動作。
定期比較支付記錄與本地已付款訂單,篩出本地缺失、金額不符、已付款未交付和退款未完成的情況。鏈上監控通知也需要關聯到唯一業務訂單,不能僅憑同金額轉賬猜測歸屬。確認條件及特殊交易處理應在接入時約定。
上線前按故障清單驗收,并明確接口邊界
- 偽造通知、錯誤簽名、錯誤商戶和錯誤金額都不能觸發交付。
- 相同事件重復發送、不同事件關聯同一交易,均不會重復分配。
- 并發購買最后一份庫存時,只有一份有效分配記錄。
- 事務提交失敗不應答成功,提交后進程重啟仍能繼續處理。
- 郵件超時、任務中斷和外部接口結果不明,都有核對入口。
- 缺貨、晚到付款、退款和人工補發都有可追溯狀態。
稳付pay的商戶后臺仍在開發,監控與回調服務已經開放。目前 USDT 支持 Tron(TRC20)和 Ethereum(ERC20),資金直接進入商戶自有地址;達到配置的鏈上確認條件后提供秒級業務通知,不代表區塊確認本身只需幾秒。
本文沒有提供稳付pay的實際接口地址、簽名頭或密鑰獲取流程。準備對接時,請先聯系確認實際協議,再據此實現請求驗證、應答與補單規則,完成測試后上線。
參考資料與技術文檔
以下官方資料用于核對協議及實現原理。文中代碼與場景用于技術解釋,具體環境和正式接入協議應分別驗證。