充值回调

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

入账判断

满足以下任一条件，即可判断充值已到账：

事件 type 为 wallets.transaction.succeeded 且 status 为 Completed
区块确认数 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_id`	string	事件唯一标识
`type`	string	事件类型（`wallets.transaction.created` / `updated` / `succeeded`）
`created_timestamp`	number	事件创建时间戳（毫秒）
`data.transaction_id`	string	交易唯一标识
`data.wallet_id`	string	商户钱包 ID
`data.type`	string	交易类型（`Deposit` = 充值）
`data.status`	string	交易状态（`Confirming` / `Completed`）
`data.source.addresses`	array	充值来源地址（终端用户的地址）
`data.destination.amount`	string	充值金额
`data.destination.address`	string	充值目标地址（商户的收款地址）
`data.chain_id`	string	链标识
`data.token_id`	string	代币标识
`data.confirmed_num`	number	当前区块确认数
`data.confirming_threshold`	number	所需最小确认数
`data.transaction_hash`	string	链上交易哈希
`data.block_info`	object	区块信息（区块号、时间戳）
`data.timeline`	array	状态变更时间线

处理建议

幂等处理

同一笔充值可能触发多次 Webhook（created → updated → succeeded）。请使用 transaction_id 做幂等判断，避免重复入账。

验证 wallet_id

收到事件后，先校验 data.wallet_id 是否为您的项目钱包，非本项目的事件应忽略。

对账兜底

除 Webhook 外，建议定期调用交易记录接口做对账兜底，防止 Webhook 丢失。

Manual 收单场景

Manual 收单复用本回调：付款方向后台创建的固定地址转账后，系统通过正常的 Webhook 通道推送与线上充值完全相同的事件结构。没有新的通知机制——商户直接复用已有的入账处理代码即可。

项目区分方式与线上一致：事件中的 data.wallet_id 即项目收单钱包 ID（现成字段），各项目对应的钱包 ID 由 NUSDpay 在接入时提供，商户据此路由（如仅将线下入账转发到运营通知群）。

常用字段对照

从第三方收单服务迁移时，常见通知字段与本回调的映射关系：

常见字段	NUSDpay Webhook 字段	说明
`walletName`（地址备注）	—	Webhook 不下发地址备注。商户侧以 `data.destination.address` 反查创建地址时填写的「描述」，自行维护映射
`chain`	`data.chain_id`	链标识（上文 Payload 示例中的 `TBSC_BNB` 为测试网值，生产取值以实际回调为准）
`toAddress`	`data.destination.address`	固定收款地址
`notifyTime`	`created_timestamp`	毫秒时间戳（UTC）
`orderAmount`	`data.destination.amount`	链上收到的原始金额（服务费与汇率换算前）
`currency`	`data.token_id`	代币标识，含链前缀（如 `TRON_USDT`），完整列表见支持的币种与公链
`hash`	`data.transaction_hash`	链上交易哈希
`txId`	`data.transaction_id`	NUSDpay 交易 ID（幂等键）
`status`	`type` + `data.status`	`type` 为 `wallets.transaction.succeeded` 且 `status` 为 `Completed` 即成功；或 `confirmed_num` ≥ 10（同上文「入账判断」）
`mchNo`（商户号/项目号）	`data.wallet_id`	以项目钱包 ID 区分项目（现成字段），各项目对应的 ID 由 NUSDpay 提供

典型用法：订阅本回调 → 校验 wallet_id 为 Manual 收单钱包 → 按上表组装消息 → 推送到内部 IM 群机器人（如飞书/企微），运营无需登录后台即可实时看到线下入账。

快速开始

接入规范

交易与通知

更多集成

参考

入账判断

Payload 示例

字段说明

处理建议

Manual 收单场景

常用字段对照

​入账判断

​Payload 示例

​字段说明

​处理建议

​Manual 收单场景

​常用字段对照

入账判断

Payload 示例

字段说明

处理建议

Manual 收单场景

常用字段对照