鏈上收款

發卡平臺對接USDT:自有地址、鏈上確認與可靠回調

鏈上看見轉賬,不等于訂單已經可靠收款;收到一次回調,也不等于可以重復發卡。把錢包、交易證據、支付狀態和庫存交付分開,才能讓商戶自行掌握資金,同時讓數字商品交付可追溯。

文章目錄

一、先確定資金邊界:地址歸商戶,監控服務不保管資產

這里的發卡平臺指數字商品、授權碼或兌換碼的自動交付系統。接入USDT時,客戶應直接付款到商戶自己的收款地址。稳付pay負責監聽和識別交易、核對到賬狀態,再向商戶業務系統回調;資金不經過稳付pay,平臺不代收、不托管。

商戶自己保管錢包和簽名權限。提供公開收款地址即可進行只讀監控,不應向監控人員提交助記詞、私鑰、錢包文件或遠程控制權限。“我幫你配置”也不是索取這些資料的理由。資金掌握在自己手上,還意味著地址備份、付款核查與退款審批由商戶負責。

二、網絡、代幣與確認條件必須在下單時固定

稳付pay當前支持USDT的Tron(TRC20)與Ethereum(ERC20)網絡。USDT是資產名稱,TRC20與ERC20描述不同網絡上的代幣標準;同名資產不能混用訂單和地址。收銀臺應清晰展示網絡,并要求客戶確認,而不是只顯示“USDT付款”。

核對項Tron / TRC20Ethereum / ERC20
鏈上交易證據核驗成功執行的目標合約轉賬事件核驗成功回執中的目標合約Transfer日志
確認依據按約定檢查已確認、固化的數據按約定的區塊確認或safe/finalized策略
共同要求核對網絡、目標合約、商戶地址、金額與訂單匹配結果

TRON交易文檔區分打包與固化;Ethereum JSON-RPC文檔也區分不同區塊狀態。確認策略應由接入雙方約定,不能用一個固定秒數代替。稳付pay的秒級回調指達到約定確認條件后的通知速度,不承諾區塊鏈本身秒級確認。

三、訂單匹配不能只靠“金額相同”

兩名客戶可以同時購買同價商品,一筆交易也可能包含多個代幣轉賬事件。訂單至少應綁定內部訂單號、網絡標識(Ethereum如chainId)、目標代幣合約、收款地址、整數金額和有效期;交易證據另記交易哈希、事件序號、區塊號與區塊哈希。不能拿客戶填入的交易哈希直接當作到賬證明。

可為訂單預分配商戶控制的獨立地址,或在共享地址模式下設置明確的支付會話與沖突規則。即便使用差異金額,也必須結合網絡、合約、地址、有效會話與交易歸屬判斷;遇到多個候選訂單,應進入人工核對,禁止“先匹配第一條”。

Ethereum單條日志通常用網絡標識、交易哈希及logIndex定位;TRON則按接口提供的事件序號建立穩定映射。保留原始事件與區塊哈希,發生重組時重新核驗所屬規范鏈。這只定位當前規范鏈上的事件,不把logIndex視為跨重組永久不變的標識;交易哈希本身也不應代替事件級唯一性。

四、金額使用最小單位,地址和合約分別驗證

不要用浮點數比較付款金額。先從受信任的目標代幣配置確認精度,再用整數最小單位入庫。例如精度為6時,12.34對應12340000個最小單位;這是換算示例,不意味著任意名叫USDT的合約都可信。鏈、合約地址和精度應來自維護的允許清單,不能采用客戶提交的同名代幣。

地址輸入要按對應網絡校驗格式,并在確認頁面完整核對。也要區分轉賬金額與錢包支付的網絡費用:客戶付出的手續費不自動算入商品款。首次接入先做小額驗證,核驗實際收款地址和事件,避免把頁面顯示成功當成鏈上收款成功。

五、交易監聽與發卡交付之間,保留明確狀態

  1. 創建支付會話固定訂單、網絡、地址、金額與有效期
  2. 發現并核驗轉賬檢查成功執行的目標代幣事件
  3. 等待約定確認保留區塊信息并復核交易歸屬
  4. 持久化收款通知業務端驗簽、去重并更新訂單
  5. 執行庫存交付獨立記錄發卡結果與補償任務
交易發現、確認、回調接收和商品交付是不同狀態,不能合并成一個“成功”。

監聽器應保存掃描游標,斷線后補掃已遺漏區間,并允許小范圍重疊掃描。重復掃描依靠唯一約束去重,而不是依賴“理論上不會重發”。未滿足確認條件的轉賬保持待確認;節點數據落后或事件被撤銷時暫停推進,不能繼續發貨。

例如在商戶數據庫中,為支付事件設置非空復合唯一鍵,為每筆訂單建立唯一的交付記錄。PostgreSQL約束文檔說明復合唯一約束的作用;具體鍵應結合網絡事件模型設計,不能機械套用到所有鏈。

六、可靠回調要解決來源、持久化和冪等

回調使用HTTPS,按接入雙方確定的協議校驗簽名、時間戳和事件身份,并校驗內部訂單、幣種、網絡與金額。若簽名覆蓋原始請求體,就必須在解析、重排JSON之前保留原始字節。密鑰輪換、時鐘容差與重試規則都應在聯調時明確,本文不虛構稳付pay接口地址或簽名字段。

可以借鑒Stripe官方Webhook指南對重復事件和驗簽的處理原則,但它不是稳付pay的接口規范。驗簽成功后先把通知可靠寫入數據庫或持久隊列,再盡快返回約定的成功響應;寫入失敗不能搶先確認。慢速發卡由后臺任務處理。

同一回調重發十次,收款狀態只能推進一次,交付也只能發生一次。把支付更新與待交付任務寫入同一事務,交付任務再鎖定訂單和庫存;失敗后重試已有任務,不重新生成第二張卡。回調暫時失敗時可重試并補查,客戶瀏覽器跳轉不能代替服務端核驗。

七、兩個故障案例:重復通知與確認前重組

案例一:已發卡,但回調請求超時后又來一次

第一次請求可能已經提交事務,只是響應在途中丟失。第二次先按事件身份去重,再讀取訂單交付狀態,返回已處理結果;不要僅憑“這次請求是新的”再取一張庫存。核對通知記錄、訂單事務和交付記錄,才能區分重復請求與真正漏發。

案例二:看見轉賬就發卡,隨后交易所屬區塊變化

未確認的交易可能受鏈上重組影響。監聽器應檢查區塊歸屬,Geth訂閱文檔說明Ethereum日志還可能帶有removed標記;發現變化后回退待確認觀察狀態,并重新掃描核驗。若在確認條件滿足前已經交付,應進入人工事件處理,保留證據,不能自動向用戶錢包執行扣回操作。

八、過期付款、缺貨與退款,分別制定規則

訂單超時不意味著地址不能再收到款。過期后發現付款,記錄為待核對收款,不自動挪給新訂單;少付、多付、同一訂單分多次付款也應按預先約定處理。庫存預留過期而款項后來確認時,要么重新核對庫存并交付,要么進入人工退款流程。

支付完成和交付成功分別記錄:付款已確認但缺貨時,保持收款事實,告知客戶待處理,而不是把訂單改回“未支付”。退款是商戶錢包發起的一筆新鏈上交易,需要獨立審批、核對退款網絡和地址、記錄手續費與交易哈希;不能憑付款來源地址自動退款,因為交易所代付地址可能并非客戶可直接接收的地址。

九、上線檢查:先讓異常路徑跑通,再擴大交易量

  • 確認收款錢包歸商戶控制,任何接入資料均不包含私鑰或助記詞。
  • 分別測試TRC20與ERC20的合約、精度、地址和確認策略。
  • 覆蓋同價訂單、重復事件、回調超時、斷線補掃與確認前重組。
  • 演練過期付款、少付多付、缺貨、發卡失敗、對賬和人工退款。
  • 確保日志能從訂單追到支付事件和交付任務,同時遮蔽密鑰與卡密。

稳付pay當前面向中小站長免費開放上述兩條網絡的監控與回調服務,企業級服務另行收費。商戶后臺仍在開發中,現階段可聯系配置接入。資金始終由商戶自己的錢包掌握;具體確認策略、回調協議和異常處理方式,應在上線前完成聯調確認。

參考資料與技術文檔

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

  1. TRON官方:交易生命周期與固化
  2. TRON官方:TRC-20代幣標準
  3. Ethereum官方:JSON-RPC、日志與區塊狀態
  4. Geth官方:訂閱日志與重組的removed標記
  5. Stripe官方:Webhook驗簽、重復事件與響應處理
  6. PostgreSQL官方:唯一約束與復合鍵

繼續完善你的站點

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

聯系稳付pay ↗