開發者接入指南:把稳付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。 |
密鑰只保存在后端,前端只取得業務訂單和允許展示的支付鏈接。測試與正式配置分別保存;日志應對密鑰及簽名原文中的密鑰部分脫敏。
第二步:接通完整支付流程
- 創建業務訂單服務端確定商品、金額、幣種和唯一商戶訂單號,保存待支付記錄。
- 服務端簽名下單生成當前毫秒時間戳,計算簽名,請求代收創建接口。
- 展示有效支付鏈接檢查實際返回的 payUrl,再引導付款;沒有鏈接時進入查詢或異常處理。
- 核驗成功通知后端驗簽,核對商戶、訂單、幣種與金額,不依靠瀏覽器跳轉判斷到賬。
- 冪等更新與交付支付狀態持久化,使用唯一交付記錄,避免重復發卡、充值或發貨。
- 查單與核對對超時、通知遺漏和長時間待支付的訂單主動查詢,保留處理記錄。
第三步:在產品中準備四個接入位置
| 系統位置 | 接入職責 | 保留記錄 |
|---|---|---|
| 下單服務 | 校驗業務訂單、簽名并調用創建接口。 | 商戶訂單號、金額分、幣種、平臺訂單號。 |
| 支付展示頁 | 展示真實支付鏈接和本地狀態。 | 關聯訂單與客戶訪問權限。 |
| 異步通知接口 | 驗簽、核對、冪等持久化成功結果。 | 通知摘要、校驗結果和接收時間。 |
| 查單任務 | 補齊未知結果,進入同一交付流程。 | 查詢結果、次數和最后核對時間。 |
使用現成發卡平臺時,把這些邏輯接入其支付插件或服務端擴展。確認平臺能保存獨立商戶訂單號、按原始參數驗簽,并支持冪等交付;只增加一個跳轉鏈接還不算完成對接。
上線前的接入驗收清單
- 完成約定的測試訂單,下單金額按分傳入,能關聯正確的平臺訂單與支付入口。
- 正確簽名可通過,缺字段、篡改金額和錯誤簽名能夠被識別與記錄。
- 用戶關閉瀏覽器后,服務端仍能通過通知或查單更新狀態。
- 重復通知、通知與查單同時成功時,均只交付一次。
- 下單超時先查原訂單,不盲目換訂單號重下;未知結果保留待核實。
- 支付成功但交付失敗可安全重試,支付與商品交付均有記錄。
- 通知接口可被公網訪問,密鑰不進入頁面源碼、公開附件和日志。
測試額度、通道權限和異常處理由技術人員與你確認。需要協助時,提供脫敏訂單號、請求時間和錯誤摘要即可,不要在截圖中展示密鑰。
繼續完成接口接入
依次閱讀代收下單與查詢、請求簽名規則和回調驗簽與冪等交付。技術人員會按你的開發框架、發卡系統和已開通通道提供接入協助。
本文依據稳付pay接入規范整理。示例用于解釋調用位置和參數結構,正式聯調使用分配給你的配置。