当终端用户向商户的收款地址充值时，NUSDpay 通过 Webhook 推送充值事件。

​
入账判断

满足以下任一条件，即可判断充值已到账：
  1. 事件 type 为 wallets.transaction.succeeded 且 status 为 Completed
  2. 区块确认数 confirmed_num ≥ 10
为什么 10 个区块即可认为到账？基于 Ethereum 2.0 Beacon Chain 的 Finalize 机制，10 个区块后交易被回退的概率已极低。官方建议的完全确认为 100 个区块（15-20 分钟），但 10 个区块已满足绝大多数业务场景的安全要求。

​
Payload 示例

{
  "event_id": "48bf7cdc-7dd9-4d61-aa61-496003a4787c",
  "url": "https://apidev.nusd.me/webhooks/real",
  "created_timestamp": 1757407060503,
  "type": "wallets.transaction.created",
  "data": {
    "transaction_id": "157d3c84-294b-4ca1-8ca7-f0bbb3b98787",
    "wallet_id": "5c8e4ee0-e701-43b8-9724-7815d7c12643",
    "type": "Deposit",
    "status": "Confirming",
    "source": {
      "source_type": "DepositFromAddress",
      "addresses": ["0xf3f42f3d87ac8687b845146ec38aa9672d9669ab"]
    },
    "destination": {
      "destination_type": "DepositToAddress",
      "amount": "0.001",
      "address": "0x25246af7149a20b2d742b0796431df070eec7048",
      "wallet_id": "5c8e4ee0-e701-43b8-9724-7815d7c12643"
    },
    "chain_id": "TBSC_BNB",
    "token_id": "TBSC_BNB",
    "confirmed_num": 1,
    "confirming_threshold": 15,
    "transaction_hash": "0x77e1a72d410f279d589b185b4b74d4cc7e030cc67d42c7f0f0d3a96d84c08664",
    "block_info": {
      "block_number": 64752220,
      "block_timestamp": 1757407051000
    },
    "timeline": [{
      "status": "Confirming",
      "finished": false,
      "finished_timestamp": 1757407059000
    }]
  }
}

​
字段说明

字段类型说明
event_idstring事件唯一标识
typestring事件类型（wallets.transaction.created / updated / succeeded）
created_timestampnumber事件创建时间戳（毫秒）
data.transaction_idstring交易唯一标识
data.wallet_idstring商户钱包 ID
data.typestring交易类型（Deposit = 充值）
data.statusstring交易状态（Confirming / Completed）
data.source.addressesarray充值来源地址（终端用户的地址）
data.destination.amountstring充值金额
data.destination.addressstring充值目标地址（商户的收款地址）
data.chain_idstring链标识
data.token_idstring代币标识
data.confirmed_numnumber当前区块确认数
data.confirming_thresholdnumber所需最小确认数
data.transaction_hashstring链上交易哈希
data.block_infoobject区块信息（区块号、时间戳）
data.timelinearray状态变更时间线

​
处理建议

同一笔充值可能触发多次 Webhook（created → updated → succeeded）。请使用 transaction_id 做幂等判断，避免重复入账。
收到事件后，先校验 data.wallet_id 是否为您的项目钱包，非本项目的事件应忽略。
除 Webhook 外，建议定期调用 交易记录 接口做对账兜底，防止 Webhook 丢失。

​
Manual 收单场景

Manual 收单复用本回调：付款方向后台创建的固定地址转账后，系统通过正常的 Webhook 通道推送与线上充值完全相同的事件结构。没有新的通知机制——商户直接复用已有的入账处理代码即可。
项目区分方式与线上一致：事件中的 data.wallet_id 即项目收单钱包 ID（现成字段），各项目对应的钱包 ID 由 NUSDpay 在接入时提供，商户据此路由（如仅将线下入账转发到运营通知群）。

​
常用字段对照

从第三方收单服务迁移时，常见通知字段与本回调的映射关系：
常见字段NUSDpay Webhook 字段说明
walletName（地址备注）—Webhook 不下发地址备注。商户侧以 data.destination.address 反查创建地址时填写的「描述」，自行维护映射
chaindata.chain_id链标识（上文 Payload 示例中的 TBSC_BNB 为测试网值，生产取值以实际回调为准）
toAddressdata.destination.address固定收款地址
notifyTimecreated_timestamp毫秒时间戳（UTC）
orderAmountdata.destination.amount链上收到的原始金额（服务费与汇率换算前）
currencydata.token_id代币标识，含链前缀（如 TRON_USDT），完整列表见 支持的币种与公链
hashdata.transaction_hash链上交易哈希
txIddata.transaction_idNUSDpay 交易 ID（幂等键）
statustype + data.statustype 为 wallets.transaction.succeeded 且 status 为 Completed 即成功；或 confirmed_num ≥ 10（同上文「入账判断」）
mchNo（商户号/项目号）data.wallet_id以项目钱包 ID 区分项目（现成字段），各项目对应的 ID 由 NUSDpay 提供
典型用法：订阅本回调 → 校验 wallet_id 为 Manual 收单钱包 → 按上表组装消息 → 推送到内部 IM 群机器人（如飞书/企微），运营无需登录后台即可实时看到线下入账。