Skip to content

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

CodeDescriptionSystem Action
0Success - message acknowledged

Returned HTTP status code must be OK (200, Series.SUCCESSFUL, "OK")
Continue to next message
Non-zeroFailed - message not processedThe 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:

EnvironmentIP Address
Production54.179.18.153/32
Development3.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

FieldTypeDescription
domain_idStringEnterprise domain ID
b_idStringBusiness line ID
wallet_codeStringWallet code
order_idStringOrder ID (null for deposits, present for withdrawals)
event_typeStringTransaction type: DEPOSIT or WITHDRAW
event_statusStringTransaction status (see status tables below)
confirmationsIntegerNumber 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_idStringTransaction detail ID. Use the Get Transaction Details API and pass the detail_id in the id parameter to retrieve full transaction details.
extended_infoObjectAn object that contains deposit_type
deposit_typeStringIndicates the type of deposit.
Allowed Values : null or cold_hot_allocate
If 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

StatusDescription
UNCONFIRMEDTransaction detected on-chain but hasn't reached required confirmations
CONFIRMEDTransaction has reached the safe confirmation height
ROLLBACKEDTransaction was rolled back
ROLLBACKED_RBFRollback transactions caused by RBF
FROZENThe deposit has been frozen
FROZEN_REFUND_WAITING_ADDRESSThe transaction has been flagged by compliance and requires a refund address to proceed.
REFUNDEDThe frozen deposit has been successfully refunded.

When you'll receive notifications: Callbacks are sent for each status change.

Withdrawal Statuses

StatusDescription
CREATINGWithdrawal order is being created. This status only returned when using the Create Withdrawal Order (v2) endpoint.
PROCESSINGWithdrawal is being processed
ORDER_SEND_OUTOrder has been sent to the blockchain
PARTIALLY_FAILEDSome transactions in the order failed
FAILEDWithdrawal failed completely
FINISHEDWithdrawal completed successfully
CANCELEDWithdrawal was canceled
MANUAL_APPROVALRequires KYT or amount exceeds manual approval threshold.
WAITING_FOR_APPROVALWithdrawal is pending approval internal checkers.
REJECTEDOrder 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.