支付開發

發卡平臺支付對接:驗簽、冪等、庫存鎖與自動交付

自動發卡不是收到一個“支付成功”字符串就發出一份卡密。可靠的流程需要把可信支付通知、訂單狀態、庫存分配和交付任務銜接起來,并允許網絡重試、進程重啟和人工修復。本文給出與供應商無關的通用設計;所有字段、簽名方式和應答內容都要按實際接入協議實現,不能直接當作稳付pay的接口說明。

文章目錄

將付款與交付拆成兩個狀態維度

至少區分待支付、已支付、已退款等付款狀態,以及待分配、已分配、已交付和交付異常等交付狀態。否則客戶付款后遇到庫存不足,系統只能在“成功”與“失敗”之間二選一,無法保留真實的中間事實。

  1. 創建訂單服務端固定商品、金額、幣種與有效期
  2. 確認付款驗簽、核對字段并持久化支付事實
  3. 分配庫存事務中鎖定訂單與對應卡密
  4. 執行交付持久任務重試并保留交付結果
瀏覽器返回頁面可以展示進度,付款事實來自可信的服務端確認流程。

購買數量、價格和優惠由服務器計算,不能直接采用瀏覽器提交的最終金額。訂單保存當時的價格快照,之后商品漲價也不應改變已經創建的付款要求。

先驗簽,再核對商戶、金額和業務歸屬

回調處理在后端執行,依照支付文檔驗證簽名、簽名覆蓋的數據、時間窗口和密鑰。供應商若要求使用原始請求體,應在框架解析或重新序列化之前保留原始字節。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的實際接口地址、簽名頭或密鑰獲取流程。準備對接時,請先聯系確認實際協議,再據此實現請求驗證、應答與補單規則,完成測試后上線。

參考資料與技術文檔

以下官方資料用于核對協議及實現原理。文中代碼與場景用于技術解釋,具體環境和正式接入協議應分別驗證。

  1. Stripe:Webhook 驗證與重復事件
  2. PostgreSQL:數據庫約束
  3. PostgreSQL:顯式鎖與行鎖
  4. PostgreSQL:事務原子性
  5. OWASP:交易業務數據驗證

繼續完善你的站點

從網絡、訂單到資金通知,按業務場景確認每一步。支付接入與USDT監控需求,可通過聯系頁面溝通。

聯系稳付pay ↗