如何可靠接收 USDT 支付：地址、確認與 Webhook

如果要在生產環境接收 USDT，第一件要設計的事不是“展示哪個錢包地址”，而是“我們要求客戶為哪個業務訂單，在什麼鏈、什麼資產、什麼地址、什麼金額上付款”。

USDT 存在於多條鏈上。同名資產如果發到了錯誤網路，即使金額看起來正確，也不是這筆訂單的成功付款。可靠的 USDT 收款流程需要明確的付款指令、確定性的匹配規則、確認與重組處理，以及用於履約的已驗證 Webhook 邊界。StableOps 提供這層訂單與事件基礎設施，商戶繼續控制自己的收款地址。

如果你還在決定企業應採用哪種模式接受穩定幣支付，請先用完整指南確定資金路徑和上線步驟；本文專門討論 USDT 的多鏈收款細節。

USDT 是資產加鏈

客戶常把 USDT 理解成一個餘額，但支付系統不能這樣處理。TRON、Ethereum、Optimism、BNB Chain 或 Solana 上的 USDT，對應不同的鏈上事件、地址格式、代幣合約或 mint、手續費和確認行為。結帳頁必須讓客戶選擇具體的 (chain, asset)，而不是隻寫“傳送 USDT”。

實用模型如下：

業務訂單
      |
      v
Payment Order：金額 + 可接受鏈/資產組合 + 過期時間
      |
      v
付款指令：chain + USDT + address + exact amount
      |
      v
按 organization、environment、chain、asset、address、amount 匹配鏈上轉帳
      |
      v
payment.detected -> payment.confirmed -> payment.finalized

StableOps 會在建立訂單時拒絕不支援的 (chain, asset) 組合。對於支援的組合，StableOps 會為每個可接受組合分配一個收款候選地址，並返回應用或 Checkout 頁面應展示的精確 paymentInstructions。即時鏈支援範圍以文件首頁中的支援資產表為準。

用明確的 USDT 選項建立訂單

先建立並持久化你的業務訂單，再建立 Payment Order。不可變的業務訂單 ID 成為 merchantOrderId，金額和過期時間也應在重試時保持穩定。不要因為瀏覽器重新整理，就用新的過期時間建立一筆新的收款嘗試。

import { StableOps } from '@stableops/api-sdk'

const stableops = new StableOps({
  apiKey: process.env.STABLEOPS_API_KEY!,
})

export async function createUsdtPayment(order: {
  id: string
  amount: string
  paymentExpiresAt: string
}) {
  return stableops.paymentOrders.create(
    {
      merchantOrderId: order.id,
      amount: order.amount,
      acceptedAssets: [
        { chain: 'tron', asset: 'USDT' },
        { chain: 'ethereum', asset: 'USDT' },
        { chain: 'solana', asset: 'USDT' },
      ],
      expiresAt: order.paymentExpiresAt,
      metadata: { product: 'checkout' },
    },
    { idempotencyKey: `payment-order:${order.id}` },
  )
}

重試時，請傳入相同的 merchantOrderId、金額、可接受資產、過期時間和冪等鍵。前端應渲染返回的 paymentInstructions，不要在瀏覽器裡自行拼接地址或代幣合約。付款人選擇 TRON USDT，就展示 TRON 的指令；選擇 Ethereum USDT，就展示 Ethereum 的指令。即使業務訂單和發票金額相同，它們也是不同的支付路徑。

amount 是資產單位的十進位制字串。鏈上事件會在應用代幣精度後以最小單位比較，因此應從 order.amount 展示精確金額，從 order.expiresAt 展示過期時間，並從選中的 paymentInstructions 條目展示 chain、asset 和 address。如果你使用共享地址和自動金額調整，返回的 order.amount 可能不同於請求時的基礎金額；客戶必須精確支付返回金額。Payment Orders說明了地址分配和匹配行為。

匹配完整指令，而不是錢包餘額

當 USDT 支付閘道器或直連錢包流程把“錢包餘額增加”當成付款憑據時，可靠性會很快下降。這樣會丟失轉帳與訂單之間的關係，尤其是在多條鏈、多個客戶同時付款時。

StableOps 只會在轉帳與開放訂單的所有關鍵欄位都匹配時推進訂單：

在你自己的記錄中，應始終保留這個元組：

(internal order id, StableOps payment order id, chain, asset, address, amount, expiry)

客服、對帳和履約都應引用這個元組，而不是隻看交易雜湊或錢包餘額。交易雜湊適合排查，但不足以判斷某個業務訂單已經付款。

有意識地設計地址複用

地址策略是營運決策，不只是錢包管理細節。

對於 USDT，不同鏈族的地址格式不同。EVM 地址使用 0x...，TRON 地址是以 T 開頭的 base58 字串，Solana token account 和錢包地址遵循 Solana 約定。請儲存並展示 paymentInstructions 返回的地址，不要把適用於某一鏈族的歸一化規則套到另一鏈族上。

地址容量也會影響結帳頁可靠性。如果使用單地址池，應在符合條件的 USDT 地址耗盡前告警。如果使用共享地址池，應監控同金額衝突、過期訂單，以及客戶手動改金額的情況。

用確認展示進度，用 finalized 作為履約邊界

USDT 支付確認不是一個通用於所有鏈的固定區塊數。每條鏈都有自己的出塊時間、最終性假設和重組風險。應用應回應標準化的支付生命週期，而不是到處硬編碼同一個確認數。

對於不可逆動作，應等待已驗證、已去重的 payment.finalized Webhook。確認狀態模型解釋了狀態機，穩定幣支付確認提供了面向產品團隊的決策框架。

讓 Webhook 成為交接給應用的持久邊界

客戶提交錢包交易後，瀏覽器可能跳回你的頁面；錢包也可能展示交易雜湊。但二者都不是最終付款憑據。後端應在持久化接受已簽名事件後，再從 Webhook 驅動履約。

邊界可以這樣設計：

收到 StableOps Webhook
          |
          v
驗證 raw body 簽名
          |
          v
在一個事務中持久化唯一 X-Event-Id 和合法訂單狀態遷移
          |
          v
對首次收到且已驗證的 payment.finalized，按內部訂單 ID 入隊不可逆履約任務
          |
          v
返回 2xx，再由 worker 冪等履約

事件去重和履約冪等解決的是不同問題。唯一事件 ID 防止重試和重放重複應用同一事件；按內部訂單 ID 做履約冪等，則防止產品權益、發貨或帳務寫入被兩個有效程式碼路徑執行兩次。完整 Webhook 處理模式可閱讀穩定幣支付 Webhook和 Webhook 指南。

預先處理錯誤網路、錯誤金額和過期訂單

可靠的 USDT 收款包含對異常付款場景的客服策略。不要等第一個客戶發錯資金後再臨場決定。

因為 StableOps 是非託管模式，錯發資金由你從自己控制的地址中恢復。StableOps 可以幫助識別發生了什麼，但不會持有私鑰，也不會替你移動資金。錯誤金額或錯誤鏈 FAQ更詳細說明了這些營運行為。

生產檢查清單

• 明確產品接受哪些 USDT 鏈；不要只展示“USDT”而不展示網路。
• 為每個可接受的鏈/資產組合匯入並監控足夠的可用收款地址。
• 在建立 Payment Order 前持久化業務訂單，並在重試時複用同一個冪等鍵。
• 將 order.amount、order.expiresAt 與選中 paymentInstructions 條目的 chain、asset、address 一起展示。
• 在自己的對帳記錄中儲存所選付款指令元組。
• 定義錯誤鏈、錯誤資產、少付、多付、過期和遲到轉帳的客服策略。
• 用 payment.detected 和 payment.confirmed 展示進度；不可逆履約只由已驗證的 payment.finalized 觸發。
• 用 raw body 驗證 Webhook，給 X-Event-Id 加唯一約束，並按內部訂單 ID 保證履約冪等。
• 上線前測試重複投遞、重放、過期訂單和 worker 崩潰。

FAQ

可以用一個整合接收多條鏈上的 USDT 嗎？

可以，前提是這些 (chain, asset) 組合受支援，並且你有對應的合格收款地址。建立 Payment Order 時顯式傳入 TRON、Ethereum 或 Solana 等 USDT 組合，然後展示客戶所選網路對應的返回指令。

客戶發來交易雜湊後，USDT 付款就確認了嗎？

不是。交易雜湊是排查和進度訊號，不是業務訂單的最終收款憑據。只有後端驗證並去重 payment.finalized Webhook 後，才應執行不可逆履約。

客戶把 USDT 發到了錯誤鏈上怎麼辦？

除非轉帳匹配訂單接受的 chain、asset、address、amount 和開放狀態，否則訂單不會推進。因為收款地址由你控制，恢復或退款應透過你自己的資金管理或客服流程線上下完成，不屬於自動訂單生命週期。

先從一個網路開始，再有紀律地擴充套件

上線 USDT 收款最穩妥的方式，是先選擇一條鏈、一個地址策略、一個 Webhook 端點，以及一條冪等的 payment.finalized 履約路徑。當這個閉環能在 Sandbox 中承受重複投遞、過期和客服異常後，再按同樣的匹配與對帳紀律擴充套件更多 USDT 網路。

要開始實踐這套流程，請先匯入收款地址，再透過 Payment Orders在 Sandbox 建立第一筆指定鏈的 USDT 訂單。上線前，可將錯誤金額或錯誤鏈 FAQ整理成處理異常付款的客服手冊。如果還在決定只收 USDT 還是同時開放 USDC，請按商戶穩定幣收款對比中的決策樹核對客戶持幣與財務出入金路徑。