發卡平臺對接詳細流程:從商品配置到支付回調與自動發貨驗收
準備了商品、域名和一套發卡程序,下一步怎樣讓客戶付款后可靠收到自己的授權碼?本文按一次完整接入的順序梳理準備、開發、聯調和上線。示例面向自有或已獲授權的數字商品;文中的字段名與偽代碼僅用于說明映射關系,不是稳付pay的實際接口文檔。
文章目錄
第一步:明確商品、支付和交付各自負責什么
先畫出三條邊界:發卡平臺管理商品、訂單和交付;支付服務識別交易并通知;結算流程按約定將應結款項交付給商戶。付款成功、商品已交付、結算已到賬是三個事實,不能共用一個“完成”開關。
- 準備商品確定 SKU、庫存與售后規則
- 創建支付后端固定訂單金額與支付嘗試
- 驗證付款可信回調配合服務端查單
- 自動交付事務分配與持久任務重試
例如售賣自己開發的軟件激活碼,訂單可以已付款、待發貨,同時尚未進入當次結算。客戶已經付款卻因結算隊列未完成而一直拿不到商品,通常說明系統把這幾條鏈路錯誤綁定了。
第二步:備齊商品、庫存與運行環境
給每個規格分配穩定的商品編號,明確授權期限、適用版本、購買數量上限、交付形式與售后聯系方式。平臺展示價格和服務端結算價格使用同一可信數據源;不要讓瀏覽器自行決定應付金額。
庫存先區分可售、預留、已分配、已交付。預留應有有效期和原子釋放條件;支付等待時間與預留時間需要協調。已經確認付款的訂單不能因為一個到期任務執行,就被改回未付款并無條件釋放庫存。
上線環境至少準備有效 HTTPS、獨立測試配置、可靠數據庫、持久任務進程和備份恢復方式。卡密只對所屬訂單授權用戶展示,訪問日志和錯誤堆棧不得記錄完整卡密、私鑰或支付密鑰。
第三步:先確認接入能力,再做字段對照表
把實際協議逐項確認:身份認證、簽名覆蓋內容、原始報文要求、查詢能力、支付狀態、通知應答、重試方式、時區和金額精度。若平臺現成插件不匹配,應修改適配層,不要用改頁面模板代替支付對接。
| 本地業務信息 | 對接時核對 | 保存目的 |
|---|---|---|
| 商戶訂單號 | 長度、字符和唯一范圍 | 貫穿商品、付款與交付 |
| 支付嘗試號 | 同一訂單重試如何識別 | 避免超時后重復創單 |
| 應付金額、幣種 | 單位、精度、允許狀態 | 阻止少付或幣種錯配 |
| 渠道交易號、事件號 | 是否存在、作用域及查詢方式 | 付款認領與通知去重 |
| 回調地址、返回地址 | 服務端通知與瀏覽器跳轉區別 | 分離業務確認和進度展示 |
| 網絡、資產、收款地址 | USDT 對應網絡和資產標識 | 防止跨鏈或同名代幣誤認 |
表中的名稱僅為業務概念;最終字段和簽名方法以雙方確認的真實文檔為準,不能照抄本文當作請求格式。
第四步:后端創建訂單,保存每次支付嘗試
用戶選好商品后,后端重新讀取價格、核對庫存和購買限制,生成商戶訂單號,保存金額快照、幣種和有效期。調用支付服務前先保存支付嘗試記錄,使網絡中斷后仍能定位“這一次請求”。
創單請求超時只代表沒有得到明確答復,不代表支付服務沒有創建成功。優先按原商戶訂單號或約定查詢條件核實;只有供應商協議支持冪等請求時,才以相同業務內容和約定的冪等標識安全重試。參考 Stripe 的冪等請求說明理解這種機制,不能假設所有渠道都支持同樣的請求頭。
客戶重新選擇支付方式時保留舊嘗試的歸屬,避免舊通知被映射到新的渠道訂單。若出現兩筆真實付款,應分別記錄并進入重復付款處理,不應發兩份商品來掩蓋問題。
第五步:展示支付指引,返回頁面只展示進度
把服務端取得的支付鏈接或必要參數交給前端,展示訂單號、應付金額、有效期和售后入口。對接 USDT 時還要展示準確網絡與收款地址,不能只寫“USDT”讓客戶猜網絡。
客戶支付后跳回網站、關閉網頁、切換設備,都不應改變后端確認流程。返回頁面只向自己的后端查詢訂單進度,不根據網址里的 success 參數直接交付。訂單詳情與卡密查詢應驗證登錄身份或足夠強的訂單訪問憑證。
OWASP 的第三方支付集成指南強調服務端驗證與金額匹配。支付提示中的“已提交”“確認中”也要與“已支付”區分,避免把一筆尚未確認的轉賬誤報成成功。
第六步:后端驗簽、查單并核對業務字段
接收通知時依實際協議驗簽,檢查商戶歸屬、訂單、金額、幣種及成功狀態;需要原始請求體的協議,應在解析重寫前保留原始字節。簽名有效仍不能代替業務字段檢查。
按接入方案使用已認證的服務端查單確認支付狀態,尤其在回調缺失、創單超時或狀態沖突時。查詢暫時不可用就保留待確認并安排重試,不把網絡錯誤當作“已失敗”,也不憑付款截圖自動發貨。
Stripe 的 Webhook 文檔說明了通知驗證、重復投遞和亂序等情況。通知接收成功必須符合協議,并以事件及后續處理責任已經可靠持久化為前提;先應答再只把任務留在內存,進程重啟就可能丟單。
第七步:事務記錄付款與庫存,提交后異步發貨
支付事實、庫存分配和發貨任務要能一起保存。對同一訂單采用行鎖或帶狀態條件的原子更新,事件、交易和交付分別設置適當范圍的唯一約束。庫存分配也應按訂單行及購買數量設置唯一歸屬,重復處理返回原分配結果,不能因交付任務尚未完成就再取一張卡。只有“先查有沒有,再寫入”擋不住并發。
# Protocol mapping example, not a runnable payment integration.
event = verify_using_confirmed_protocol(raw_request)
payment = query_and_match_payment(event)
with database_transaction():
lock_order(payment.order_id)
persist_verified_event_once(event)
record_payment_once(payment)
if not fulfillment_exists(payment.order_id):
if allocate_or_reuse_stock_once(payment.order_id):
create_outbox_job_once(payment.order_id, "deliver")
else:
mark_paid_awaiting_stock(payment.order_id)
create_outbox_job_once(payment.order_id, "stock_review")
return acknowledgement_required_by_protocol()
PostgreSQL 的事務說明可用于理解共同提交;行鎖機制用于協調競爭。外部查詢和郵件發送放在短事務之外;Outbox 是與業務數據共同落盤的任務記錄,提交后由工作進程執行。示意省略異常捕獲,生產實現仍需處理重復鍵、死鎖和失敗重試。
第八步:補齊缺貨、晚到付款和退款分支
付款確認后發現無庫存,保存“已付款待處理”,通知站長補貨、協商交付或退款,不能退回“未支付”。過期訂單收到有效的晚到付款,也先記錄付款,再根據當前庫存與約定規則處理,不能直接忽略。
發送郵件超時不等于郵件未發出。交付任務保持穩定編號;調用支持冪等的外部授權服務時復用對應標識,不支持時先查詢或人工核對。重發原訂單卡密與重新分配一張卡密是兩種操作,前者不應再扣一次庫存。
退款保留獨立的申請、處理中、成功或失敗狀態,并關聯原交易。已經展示或兌換的授權碼不能簡單恢復成可售;可撤銷授權也要先核實撤銷結果。退款或補發操作記錄操作人、原因與關聯單號。
第九步:用驗收矩陣證明系統能應對異常
聯調不只做一筆正常付款。為每條用例保存訂單號、支付嘗試號、驗證結果、付款記錄、庫存分配和任務狀態,讓另一名維護者也能復核。
| 測試輸入 | 預期訂單結果 | 交付驗收 |
|---|---|---|
| 真實成功付款 | 已付款且交易可核對 | 數量正確、僅交付一次 |
| 錯誤簽名或金額 | 不確認成功并記錄原因 | 不分配庫存 |
| 相同通知并發到達 | 同一付款只認領一次 | 只有一份有效分配 |
| 創單超時、回調暫缺 | 查單恢復明確狀態 | 不重復付款或漏發 |
| 最后一份庫存被并發購買 | 付款事實各自保存 | 不超賣,缺貨單可處理 |
| 付款晚到、頁面已關閉 | 保留已付款事實 | 按規則補發或售后 |
| 提交后進程重啟 | 持久記錄仍在 | 任務恢復且不多發 |
| 退款與發貨同時發生 | 獨立狀態可追溯 | 按協調規則處理沖突 |
供應商有測試環境時優先使用;沒有時,事先確認小額實付、退款和費用規則。本文中的流程未替代實際渠道聯調,也不能作為“已經通過驗收”的證明。
第十步:小范圍上線,回滾時繼續處理舊訂單
發布前保留可恢復備份、舊版適配程序及配置,確認變更后的數據結構能否回滾。先限制接入范圍并關注待確認數量、驗簽失敗、已付款未交付、任務積壓與查單異常。
發現異常時可暫停新支付嘗試,但應繼續接收和核對舊訂單通知,保留原協議兼容與密鑰輪換安排。不能通過刪除回調地址或清空隊列“回滾”,否則舊付款可能永遠沒有歸屬。
稳付pay支持支付寶、微信等渠道接入,渠道代收后的 USDT 結算按雙方約定執行;USDT 自有地址監控則由客戶直接付到商戶錢包。目前監控支持 Tron(TRC20)與 Ethereum(ERC20),達到配置確認條件后提供秒級業務回調,不代表區塊確認僅需幾秒。商戶后臺仍在開發,請先聯系確認協議、結算條件和聯調范圍,再編寫對應適配層。
參考資料與技術文檔
官方資料用于核對通用技術原理。示例需結合實際接口文檔與運行環境驗證。