跳转至

回调机制

工作原理

消息推送

轮询间隔:系统每 1 分钟检查一次新交易。

消息按钱包号ID推送,系统分别发送充值和提币消息。

顺序处理:消息按顺序推送。如果您的端点返回非零代码,系统将在下一个周期(1 分钟后)重试失败的消息。

建议用户实现完善的错误处理,并始终及时返回 code: 0。此外,返回的 HTTP 状态码必须为 OK (200, Series.SUCCESSFUL, "OK")。由于消息是按顺序处理的,任何未收到成功确认的消息都会阻塞队列中所有后续消息,直到问题得到解决。

响应代码

代码说明系统操作
0成功 - 消息已确认

返回的 HTTP 状态码必须是 OK (200,成功系列,"OK")
继续发送下一条消息
不为 0 的数值失败 - 消息未处理队列暂停并在下一个周期重试相同消息,直到返回 0 响应。

回调安全

回调消息仅包含非敏感标识符,如 order_id、detail_id 和 event_status,不涉及任何机密或敏感数据。

所有敏感或机密信息须通过我们的 API 接口获取,相关接口已受到以下安全保护:

  • 权限校验
  • 来源 IP 白名单校验
  • 签名验证

为验证回调消息确实由我方系统发出,建议将以下 IP 地址加入您端点的白名单:

环境IP 地址
生产54.179.18.153/32
测试3.0.199.105/32

回调 Payload

Payload 示例

{
  "domain_id": "00000737c18e541f1a7d4c02b8a2c0dc3",
  "b_id": "4b511b3302de424bb3a33e218c02c000",
  "wallet_code": "CHTRON51111111111",
  "order_id": null,
  "event_type": "DEPOSIT",
  "event_status": "CONFIRMED",
  "confirmations": 1,
  "detail_id": "7000001",
  "extended_info":
    {
        "deposit_type": null
    }
}

Payload 字段

字段类型描述
domain_idString企业域 ID
b_idString业务线 ID
wallet_codeString钱包代码
order_idString订单 ID(充值时为 null,提币时存在)
event_typeString交易类型:DEPOSIT 或 WITHDRAW
event_statusString交易状态(见下方状态表)
confirmationsInteger区块确认数(用于充值)。有关不同链的确认区块高度,请参考 支持的代币 中的 默认安全高度 列。
detail_idString交易详情 ID。使用 查询钱包交易记录明细API 并在 id 参数中传递 detail_id 以检索完整的交易详情。
extended_infoObject包含 deposit_type 的对象。
deposit_typeString

表示入账类型。

可选值: null 或cold_hot_allocate

当 deposit_type 为 null 时,表示普通入账。

当 deposit_type 为 cold_hot_allocate 时,表示该入账为从冷钱包调拨至热钱包的入账(冷到热调拨入账),而非链上外部转入。


事件状态

充值状态

状态 描述
UNCONFIRMED 交易已在链上检测到,但尚未达到所需确认数
CONFIRMED 交易已达到安全确认高度
ROLLBACKED 交易已回滚
ROLLBACKED_RBF 因RBF导致的回滚交易。
FROZEN 充值被冻结
FROZEN_REFUND_WAITING_ADDRESS 交易被合规标记,需要您提供退款地址以继续处理
REFUNDED 冻结的金额已成功退回

何时接收通知:每次状态变化时都会发送回调。

提币状态

状态 描述
CREATING 提币正在创建中。该状态仅在使用创建提币订单(V2)接口时返回。
PROCESSING 提币正在处理中
ORDER_SEND_OUT 订单已发送到区块链
PARTIALLY_FAILED 订单中的部分交易失败
FAILED 提币完全失败
FINISHED 提币成功完成
CANCELED 提币已取消
MANUAL_APPROVAL 需要 KYT 或金额超过人工审核阈值。
WAITING_FOR_APPROVAL 提币订单正在等待企业下审核人员审核
REJECTED 订单审核被拒绝了

重要提示:只有当提币通知状态为 FINISHED 时,您才应使用 detail_id 调用查询钱包交易记录明细API以验证链上交易哈希。