如何可靠接收 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 会为每个可接受组合分配一个收款候选地址，并返回应用或 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整理成处理异常付款的客服手册。