Asynchronous Notification via Callback#
AIO supports an asynchronous callback mechanism that automatically sends transaction updates to your configured service URL whenever the transaction status changes. This enables you to efficiently handle post-processing logic, such as updating order status, recording transaction flows, or triggering business notifications.
Callback Integration Process#
1
Implement the Callback Endpoint
Implement an HTTP POST endpoint on your server to receive and parse callback notifications pushed by AIO.
2
Configure the Callback URL
Configure the Callback URL you implemented in the AIO dashboard.
How to implement an interface for receiving callbacks#
Interface Overview#
To securely and reliably receive and process callback requests, please consider the following:The request will include signature-related headers for authentication and integrity validation.
The request body is in JSON format and follows the CallbackTxData schema.
The following headers are included in each callback request:| Header | Description |
|---|
User-Agent | Identifies the request as originating from the AIO callback system. |
Algorithm | Signature algorithm used; currently HMAC-SHA256. |
Date | UTC timestamp of the request; recommended for anti-replay protection. |
Body-MD5 | MD5 hash of the request body for content integrity verification. |
Aio-Sign | HMAC signature generated using your Secret Key, used to validate the request |
It is recommended to verify the Aio-Sign on your server to ensure authenticity and integrity of the request.
Request Body#
The request body is a byte stream containing transaction details in JSON format. The field structure follows the definition of CallbackReqContentData. A basic structure is shown below:{
"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"
}
]
}
}
How to Verify a Signature#
Once you have configured the callback URL, the system will automatically send a POST request to your specified URL whenever a transaction status changes. This request will include a set of headers used for signature verification.Idempotent processing#
To ensure the stability of transaction notifications, the AIO callback system has a built-in retry mechanism:
When calling the callback URL provided by the merchant returns an HTTP status code other than 200, or the response times out, the system will automatically retry the push within a certain period of time.Therefore, when implementing the callback interface, you must ensure that the interface has idempotency. That is:
When receiving the same callback data, multiple calls to the interface should produce the same processing results, and will not cause problems such as repeated execution, repeated updates, or repeated writes.Use tx_id and sub_tx_id in the callback data as the unique identifier of idempotent processing;
Record the identifier during the first processing, and directly ignore or return the processing success status when receiving data with the same identifier later.
You can configure a callback address in the AIO Dashboard to receive transaction status updates:1.
Log in to the AIO Dashboard and go to Integrations -> Callback Management in the left sidebar. 2.
Enable and configure your Callback URL to receive transaction status notifications.
Please keep your Secret Key safe, as it is required for signature verification.
4.
Whenever a transaction status changes, the system will automatically send a POST request to your configured Callback URL, with the transaction details in the request body.
Make sure your server supports HTTPS and is able to properly respond to POST requests. We recommend responding with a 200 OK status code; otherwise, the system may treat the callback as failed and attempt retries.
Callback Retry Mechanism#
To enhance system reliability and stability, the AIO platform has a built-in automatic retry mechanism for pushing transaction status update callbacks. When your server fails to successfully receive or process a callback request, the platform will perform retries using an exponential backoff strategy to maximize the probability of transaction notification delivery.The callback response is not 200 OK
Request times out or connection fails
Callback URL is unreachable
Each transaction will be retried up to 16 times
After the 8th failure, a warning will be triggered
When the maximum limit is reached, retries will stop and a log entry will be recorded
The system will check whether there has been any successful callback in the past three days
If there is no successful callback, the system will mark it as abnormal and trigger an error log or notification
Callback Trigger Relationship#
During the lifecycle of a transaction, AIO will automatically send a POST request to your configured Callback URL whenever the transaction status changes. The request body is in JSON format, structured as CallbackTxData.| Transaction Status | Trigger Description | sub_txs Content | Callback Purpose |
|---|
Pending Approval | Triggered when the main transaction is created and pending approval | An empty array or a list of initial SubTx | Notify the system of pending approval |
Pending Execution | Triggered when the main transaction is approved or waiting for execution | An empty array or a list of initial SubTx | Notify the system to prepare for execution |
Pending | Triggered whenever a new sub-transaction is generated | A list containing the newly generated SubTx | Notify the system of a new incoming transaction |
Completed | Triggered when the main transaction is marked as completed | A list containing the most recent SubTx before completion | Notify that transaction processing is complete |
Closed | Triggered when the main transaction is closed | A list containing the most recent SubTx before closure | Notify that the transaction is closed |
Overdue | Triggered when the transaction times out without completion | A list containing the most recent SubTx before timeout | Notify that the transaction is overdue |
