通过回调进行异步通知#
AIO 支持基于回调机制的异步通知功能，可在交易状态发生变化时自动向您指定的服务地址推送交易详情，便于您及时处理后续逻辑（如更新订单状态、记录流水、发起业务通知等）
回调接入流程#
1
实现接收回调的接口
在 您的服务端实现一个 HTTP POST 接口，用于接收并解析 AIO 推送的回调信息
2
配置 Callback URL
在 AIO 仪表盘配置你实现的 Callback URL
如何实现一个接收回调的接口#
接口概览#
为了确保您能够安全、稳定地接收并正确处理该请求，在实现 Callback 接口时需注意以下内容：请求将附带一组签名相关的请求头，用于身份验证与数据完整性校验；
请求体为 JSON 格式，包含本次交易的详细信息，字段结构遵循 CallbackTxData 定义
User-Agent：标识该请求来源于 AIO 回调系统。Algorithm：签名算法，当前使用 HMAC-SHA256。Date：请求发起时间（UTC 时间戳），建议用于防重放攻击校验。Body-MD5：对请求体内容计算得到的 MD5 值，用于校验内容完整性。Aio-Sign：使用您的 API Key 所绑定的 Secret Key 进行签名生成，用于验证请求合法性建议在服务器端验证 Aio-Sign 签名，以确保请求未被篡改并来源可信
请求体 - Request Body#
请求体为交易详情的数据字节流 (bytes)，内容格式为 JSON，对应的字段结构遵循 CallbackReqContentData 的定义。其基本结构如下：{
"type": "Transaction",
"data": {
"uid": "U_PAC116HWGD",
"txid": "O00745a1afF66fcbBd",
"status": "Pending Execution",
"type": "Pay Out",
"vs_token": null,
"vs_amount": null,
"usd": "24.96",
"chain": "Ethereum",
"token": null,
"amount": null,
"bind_info": null,
"sub_txs": [
{
"sub_txid": "6616936959160282",
"status": "Pending",
"token": "ETH",
"amount": "0.01",
"hash": null,
"from_addr": null,
"to_addr": "0xe5ac5A490Aa8EFEAF0e3Ddcb494eb8c513016430"
}
]
}
}
如何验证签名#
配置好 URL 后，当交易发生变更时系统将自动向您配置的 Callback URL 发送一条 POST 请求，请求中将包含一组用于签名验证的请求头 headers幂等处理#
为确保交易通知的稳定性，AIO 回调系统内置了重试机制：
当调用商户提供的 Callback URL 返回非 200 的 HTTP 状态码，或响应超时，系统会在一定时间内自动重试推送。因此，您在实现回调接口时，必须确保该接口具有幂等性。即：
在接收到相同的回调数据时，多次调用接口应产生相同的处理结果，不会引发重复执行、重复更新或重复写入等问题。使用回调数据中的 tx_id 和 sub_tx_id 作为幂等处理的唯一标识；
在首次处理时记录该标识，后续接收到相同标识的 数据时直接忽略或返回处理成功状态。
配置 Callback URL#
您可以在仪表盘中配置回调地址以接收交易状态更新通知：1.
登录 AIO 仪表盘，进入左侧导航栏的 Integrations -> Callback Management 页面。 2.
启用并配置回调地址（Callback URL），用于接收交易状态更新。
请妥善保存您的 Secret Key，以用于签名验证操作
4.
每当交易状态发生变化，系统将自动向您配置的 Callback URL 发送一条 POST 请求，内容为交易的变更详情。
请确保您的服务器支持 HTTP/HTTPS 协议，并能够正常响应 POST 请求，响应状态码建议为 200 OK，否则系统将认为回调失败并可能尝试重试
AIO 回调概念#
为了能让您更好的实现 Callback 可能需要了解的知识回调重试机制#
为提升系统的可靠性和稳定性，AIO 平台在推送交易状态更新回调时，内置了自动重试机制。当您的服务器未能成功接收或处理回调请求时，平台将按照一定策略进行指数退避重试，以便最大程度保障交易通知的送达。健康检查 系统会检测最近 3 天是否有成功回调，如果没有系统将标记为异常并触发错误日志或通知
回调触发关系#
在交易的生命周期中，AIO 平台会根据交易状态的变化，自动向您配置的回调地址（Callback URL）发送一条包含交易详情的 POST 请求。请求内容为 JSON 格式，结构详见 CallbackReqContentData| 交易状态 | 触发时机说明 | sub_txs 内容 | 回调用途说明 |
|---|
Pending Approval | 当主交易生成，等待审批时触发 | 空数组或初始状态的 SubTx 列表 | 通知系统交易待审批 |
Pending Execution | 当主交易通过审批或等待执行时触发 | 空数组或初始状态的 SubTx 列表 | 通知系统准备执行交易 |
Pending | 每当有新的子交易生成时触发 | 包含新生成的一条 SubTx 列表 | 通知系统有新交易入账 |
Completed | 当主交易状态变为已完成时触发 | 包含完成前的一条 SubTx 列表 | 通知交易处理完成 |
Closed | 当主交易被关闭时触发 | 包含关闭前的一条 SubTx 列表 | 通知交易关闭 |
Overdue | 当交易超时未完成时触发 | 包含一条超时前生成的 SubTx 列表 | 通知交易已超时 |
