如何可靠接收 USDT 支付：地址、确认与 Webhook

如果要在生产环境接收 USDT，第一件要设计的事不是“展示哪个钱包地址”，而是“我们要求客户为哪个业务订单，在什么链、什么资产、什么地址、什么金额上付款”。

USDT 存在于多条链上。同名资产如果发到了错误网络，即使金额看起来正确，也不是这笔订单的成功付款。可靠的 USDT 收款流程需要明确的付款指令、确定性的匹配规则、确认与重组处理，以及用于履约的已验证 Webhook 边界。StableOps 提供这层订单与事件基础设施，商户继续控制自己的收款地址。

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 会为每个 accepted pair 分配一个收款候选地址，并返回应用或 Checkout 页面应展示的精确 paymentInstructions。实时链支持范围以文档首页中的 supported assets 表为准。

用明确的 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、金额、accepted assets、过期时间和幂等键。前端应渲染返回的 paymentInstructions，不要在浏览器里自行拼接地址或代币合约。付款人选择 TRON USDT，就展示 TRON 的指令；选择 Ethereum USDT，就展示 Ethereum 的指令。即使业务订单和发票金额相同，它们也是不同的支付路径。

amount 是资产单位的十进制字符串。链上事件会在应用 token decimals 后以最小单位比较，因此应从 order.amount 展示精确金额，从 order.expiresAt 展示过期时间，并从选中的 paymentInstructions 条目展示 chain、asset 和 address。如果你使用共享地址和自动金额调整，返回的 order.amount 可能不同于请求时的基础金额；客户必须精确支付返回金额。Payment Orders说明了地址分配和匹配行为。

匹配完整指令，而不是钱包余额

当 USDT payment gateway 或直连钱包流程把“钱包余额增加”当成付款凭据时，可靠性会很快下降。这样会丢失转账与订单之间的关系，尤其是在多条链、多个客户同时付款时。

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 confirmation 不是一个通用于所有链的固定区块数。每条链都有自己的出块时间、最终性假设和重组风险。应用应响应标准化的支付生命周期，而不是到处硬编码同一个确认数。

对于不可逆动作，应等待已验证、已去重的 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 收款包含对 miss case 的客服策略。不要等第一个客户发错资金后再临场决定。

因为 StableOps 是非托管模式，错发资金由你从自己控制的地址中恢复。StableOps 可以帮助识别发生了什么，但不会持有私钥，也不会替你移动资金。错误金额或错误链 FAQ更详细说明了这些运营行为。

生产检查清单

• 明确产品接受哪些 USDT 链；不要只展示“USDT”而不展示网络。
• 为每个 accepted chain/asset 导入并监控足够的可用收款地址。
• 在创建 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 和开放状态，否则订单不会推进。因为收款地址由你控制，恢复或退款应通过你自己的 treasury 或客服流程在线下完成，不属于自动订单生命周期。

先从一个网络开始，再有纪律地扩展

上线 USDT 收款最稳妥的方式，是先选择一条链、一个地址策略、一个 Webhook 端点，以及一条幂等的 payment.finalized 履约路径。当这个闭环能在 Sandbox 中承受重复投递、过期和客服异常后，再按同样的匹配与对账纪律扩展更多 USDT 网络。

要开始实践这套流程，请先导入收款地址，再通过 Payment Orders在 Sandbox 创建第一笔指定链的 USDT 订单。上线前，可将错误金额或错误链 FAQ整理成处理异常付款的客服手册。