回调机制¶
工作原理¶
消息推送¶
轮询间隔:系统每 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_id | String | 企业域 ID |
| b_id | String | 业务线 ID |
| wallet_code | String | 钱包代码 |
| order_id | String | 订单 ID(充值时为 null,提币时存在) |
| event_type | String | 交易类型:DEPOSIT 或 WITHDRAW |
| event_status | String | 交易状态(见下方状态表) |
| confirmations | Integer | 区块确认数(用于充值)。有关不同链的确认区块高度,请参考 支持的代币 中的 默认安全高度 列。 |
| detail_id | String | 交易详情 ID。使用 查询钱包交易记录明细API 并在 id 参数中传递 detail_id 以检索完整的交易详情。 |
| extended_info | Object | 包含 deposit_type 的对象。 |
| deposit_type | String | 表示入账类型。 可选值: 当 当 |
事件状态¶
充值状态¶
| 状态 | 描述 |
|---|---|
| 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以验证链上交易哈希。