Callback¶
Our system sends callback notifications for deposit and withdrawal transactions. This guide explains how the notification system works and how to handle messages correctly
How It Works¶
Message Delivery¶
Polling Interval: The system checks for new transactions every 1 minute.
Messages are pushed per wallet code, and the system sends deposit and withdrawal messages separately.
Sequential Processing: Messages are delivered in order. If your endpoint returns a non-zero code, the system will retry the failed message in the next cycle (1 minute later).
Users are advised to implement robust error handling and always return code: 0 promptly. In addition, the HTTP status code returned must be OK (200, Series.SUCCESSFUL, "OK"). Since messages are processed sequentially, any message that does not receive a successful acknowledgment will block all subsequent messages in the queue until the issue is resolved.
Response Codes¶
| Code | Description | System Action |
|---|---|---|
| 0 | Success - message acknowledged Returned HTTP status code must be OK (200, Series.SUCCESSFUL, "OK") | Continue to next message |
| Non-zero | Failed - message not processed | The queue pauses and retries the same message in the next cycle until a 0 response is returned. |
Callback Security¶
The callback payload only contains non-sensitive identifiers such as order_id, detail_id, and event_status — no confidential or sensitive data is transmitted.
All sensitive or confidential information must be retrieved through our API endpoints, which are protected by:
- Permission verification
- Source IP whitelisting
- Signature verification
To verify that callbacks originate from our system, we recommend whitelisting the following IP addresses on your endpoint:
| Environment | IP Address |
|---|---|
| Production | 54.179.18.153/32 |
| Development | 3.0.199.105/32 |
Callback Payload¶
Example 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 Fields¶
| Field | Type | Description |
|---|---|---|
| domain_id | String | Enterprise domain ID |
| b_id | String | Business line ID |
| wallet_code | String | Wallet code |
| order_id | String | Order ID (null for deposits, present for withdrawals) |
| event_type | String | Transaction type: DEPOSIT or WITHDRAW |
| event_status | String | Transaction status (see status tables below) |
| confirmations | Integer | Number of block confirmations (for deposits). Refer to the Default Security Height column for in the Supported Token for the confirmation block height for the different chains. |
| detail_id | String | Transaction detail ID. Use the Get Transaction Details API and pass the detail_id in the id parameter to retrieve full transaction details. |
| extended_info | Object | An object that contains deposit_type |
| deposit_type | String | Indicates the type of deposit. Allowed Values : null or cold_hot_allocateIf deposit_type is null, the deposit is treated as a regular deposit.If deposit_type is cold_hot_allocate, it indicates that the deposit is allocated from a cold wallet to a hot wallet (cold-to-hot allocation deposit), rather than an on-chain external deposit. |
Event Statuses¶
Deposit Statuses¶
| Status | Description |
|---|---|
| UNCONFIRMED | Transaction detected on-chain but hasn't reached required confirmations |
| CONFIRMED | Transaction has reached the safe confirmation height |
| ROLLBACKED | Transaction was rolled back |
| ROLLBACKED_RBF | Rollback transactions caused by RBF |
| FROZEN | The deposit has been frozen |
| FROZEN_REFUND_WAITING_ADDRESS | The transaction has been flagged by compliance and requires a refund address to proceed. |
| REFUNDED | The frozen deposit has been successfully refunded. |
When you'll receive notifications: Callbacks are sent for each status change.
Withdrawal Statuses¶
| Status | Description |
|---|---|
| CREATING | Withdrawal order is being created. This status only returned when using the Create Withdrawal Order (v2) endpoint. |
| PROCESSING | Withdrawal is being processed |
| ORDER_SEND_OUT | Order has been sent to the blockchain |
| PARTIALLY_FAILED | Some transactions in the order failed |
| FAILED | Withdrawal failed completely |
| FINISHED | Withdrawal completed successfully |
| CANCELED | Withdrawal was canceled |
| MANUAL_APPROVAL | Requires KYT or amount exceeds manual approval threshold. |
| WAITING_FOR_APPROVAL | Withdrawal is pending approval internal checkers. |
| REJECTED | Order has been rejected from approval |
IMPORTANT TO NOTE: Only when the withdrawal notification status is FINISHED should you call the Get Transaction Details API with the detail_id to verify the on-chain transaction hash.