開發者文檔

開發者接入指南:把稳付pay接入你的產品

你的網站、發卡平臺或應用負責創建業務訂單與交付商品,稳付pay負責支付通道對接和支付結果通知。本指南按實際接入順序說明需要配置什么、調用什么,以及什么時候可以把訂單改為已支付。

文章目錄

先確認你要接入的服務

本組文檔說明已開通支付通道的代收下單、訂單查詢和支付成功通知。代付暫未開放。可用通道、正式網關、結算安排和商戶權限,由稳付pay技術人員在開通時與你確認。

代收后的結算安排,與客戶直接支付到商戶自有 USDT 錢包的鏈上監控服務,是不同的業務路徑。本組代收接口不代表 USDT 鏈上直收接口。

本文網址、訂單號和憑據均為示例。請先完成技術對接,取得屬于你自己的配置,不要把演示參數直接用于生產。

第一步:申請商戶配置

配置項使用位置需要確認的內容
API_BASE_URL商戶服務端分配的實際網關;本文以 https://gateway.example.com 示意。
MERCHANT_ID商戶服務端你的商戶號,請求字段名為 mchId。
MD5_SECRET環境變量或密鑰管理下單和查單使用的 API 密鑰。
CALLBACK_SECRET服務端密鑰管理單獨配置的回調密鑰;未配置時回退使用 API 密鑰。
wayCode支付方式映射該商戶實際開通的真實通道或聚合編碼。
notifyUrl公開 HTTPS 后端接口例如 https://merchant.example.com/pay/notify。

密鑰只保存在后端,前端只取得業務訂單和允許展示的支付鏈接。測試與正式配置分別保存;日志應對密鑰及簽名原文中的密鑰部分脫敏。

第二步:接通完整支付流程

  1. 創建業務訂單服務端確定商品、金額、幣種和唯一商戶訂單號,保存待支付記錄。
  2. 服務端簽名下單生成當前毫秒時間戳,計算簽名,請求代收創建接口。
  3. 展示有效支付鏈接檢查實際返回的 payUrl,再引導付款;沒有鏈接時進入查詢或異常處理。
  4. 核驗成功通知后端驗簽,核對商戶、訂單、幣種與金額,不依靠瀏覽器跳轉判斷到賬。
  5. 冪等更新與交付支付狀態持久化,使用唯一交付記錄,避免重復發卡、充值或發貨。
  6. 查單與核對對超時、通知遺漏和長時間待支付的訂單主動查詢,保留處理記錄。
下單成功不等于付款成功;交付應由可信的服務端支付結果觸發。

第三步:在產品中準備四個接入位置

系統位置接入職責保留記錄
下單服務校驗業務訂單、簽名并調用創建接口。商戶訂單號、金額分、幣種、平臺訂單號。
支付展示頁展示真實支付鏈接和本地狀態。關聯訂單與客戶訪問權限。
異步通知接口驗簽、核對、冪等持久化成功結果。通知摘要、校驗結果和接收時間。
查單任務補齊未知結果,進入同一交付流程。查詢結果、次數和最后核對時間。

使用現成發卡平臺時,把這些邏輯接入其支付插件或服務端擴展。確認平臺能保存獨立商戶訂單號、按原始參數驗簽,并支持冪等交付;只增加一個跳轉鏈接還不算完成對接。

上線前的接入驗收清單

  • 完成約定的測試訂單,下單金額按分傳入,能關聯正確的平臺訂單與支付入口。
  • 正確簽名可通過,缺字段、篡改金額和錯誤簽名能夠被識別與記錄。
  • 用戶關閉瀏覽器后,服務端仍能通過通知或查單更新狀態。
  • 重復通知、通知與查單同時成功時,均只交付一次。
  • 下單超時先查原訂單,不盲目換訂單號重下;未知結果保留待核實。
  • 支付成功但交付失敗可安全重試,支付與商品交付均有記錄。
  • 通知接口可被公網訪問,密鑰不進入頁面源碼、公開附件和日志。

測試額度、通道權限和異常處理由技術人員與你確認。需要協助時,提供脫敏訂單號、請求時間和錯誤摘要即可,不要在截圖中展示密鑰。

繼續完成接口接入

依次閱讀代收下單與查詢、請求簽名規則和回調驗簽與冪等交付。技術人員會按你的開發框架、發卡系統和已開通通道提供接入協助。

本文依據稳付pay接入規范整理。示例用于解釋調用位置和參數結構,正式聯調使用分配給你的配置。

按你的業務場景確認接入

說明商品、訂單量、支付方式與結算需求,逐項確認接口、資金路徑和異常處理。

聯系稳付pay ↗