当终端用户向商户的收款地址充值时，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 丢失。