The system can send an HTTP POST request to a URL that you specify in your personal account with financial operation info. The data in the body of the request and response are available in JSON format. This feature is mostly known as WebHook. We call it here and later as Callback
The request includes the following headers:
Content-Type: application/json
User-Agent: Information about the calling system.
Dates are transmitted in UTC and are formatted according to ISO 8601. For example: 2024-07-02T12:50:30Z.
Requirements
HTTPS 'Catch'-Endpoints
White domain-name (raw ip's are prohibited)
Callback authentication
Authentication for the callback is carried out by sending headers in the request, similar to the headers for authorizing the API request (see the API Request Authorization section).
To avoid fraud, your system should verify the values of the specified callback headers as follows:
The difference between the current server time and the value of the X-Processing-Timestamp header does not exceed the value of the X-Processing-RecvWindow header.
The value of the X-Processing-Key header corresponds to the value of your active API access public key.
The value of the X-Processing-Signature header matches the signature of the request data secret key, calculated according to the algorithm of calculating the request data signature secret key value in the X-Processing-Signature header.
Callback types
We're supporting 3 types of callbacks at current moment:
Deposit callback
{
"data": {
"clientDepositId": "123456", // "Client deposit" operation identifier
"address": {
"foreignId": "200889", // Label of client's customer requisites
"address": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", // Deposit address
"tag": null // Deposit requisites payload (in case of single base address)
},
"id": 43, // Deposit identifier in CryptoBilling system
"date": "2024-03-06T09:54:39", // Datetime, when this operation was created in CryptoBilling system
"status": "success", // Dictionary: Deposit transaction statuses
"error": null, // Diagnostics field with error's description
"instrument": {
"currencyShortName": "ETH", // Shortname of the currency
"transportProtocol": "Ethereum" // Currency transport protocol, which was used to form/process this operation
},
"transaction": {
"approach": "blockchain", // Dictionary: Transaction Execution Approach
"hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", // blockchain transaction hash
"amount": 0.000600000000000000,
"confirmations": 12,
"amlRiskGrade": "low" // Dictionary: Transaction Risk Level
},
"fees": [
{
"type": "commercial", // Commercial, Technical
"currencyShortName": "ETH",
"transportProtocol": "Ethereum",
"amount": 0.000268414158054900
}
],
"type": "deposit" // Dictionary: Callback Transaction Types
}
}
Withdrawal Callback
{
"data": {
"paymentOrderId": "123456", // "Client withdrawal" operation identifier
"foreignId": "200889", // Label of client's customer requisites
"address": {
"address": "rAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", // Destination address
"tag": "123456" // Payment requisites
},
"id": 33, // Withdrawal identifier in CryptoBilling system
"date": "2024-03-07T13:09:30", // Datetime, when this operation was created in CryptoBilling system
"status": "success", // Dictionary: Withdrawal transaction statuses
"error": "Successful", // Diagnostics field with error's description
"instrument": {
"currencyShortName": "XRP", // Shortname of the currency
"transportProtocol": "Ripple" // Currency transport protocol, which was/will be used to form/process this operation
},
"transaction": {
"approach": "internal",
"hash": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
"amount": 4.000000000000000000,
"confirmations": 10,
"amlRiskGrade": "low" // Dictionary: Transaction Risk Level
},
"fees": [
{
"type": "commercial",
"currencyShortName": "XRP",
"transportProtocol": "Ripple",
"amount": 1.654684587513200000
},
{
"type": "technical",
"currencyShortName": "XRP",
"transportProtocol": "Ripple",
"amount": 0.000000000000000000
}
],
"type": "withdrawal" // Dictionary: Callback Transaction Types
}
}
ServiceOperation Callback
{
"data": {
"type": "service", // Dictionary: Callback Transaction Types
"id": 34, // Service operation identifier in CryptoBilling system
"soType": "common", // Dictionary: Service Transaction Types
"date": "2024-03-07T13:09:30", // Datetime, when this operation was created in CryptoBilling system
"status": "success", // Dictionary: Service transaction statuses
"error": "Successful", // Diagnostics field with error's description
"instrument": {
"currencyShortName": "XRP", // Shortname of the currency
"transportProtocol": "Ripple" // Currency transport protocol, which was/will be used to form/process this operation
},
"sender": "rAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", // Sender's address
"recipient": "rBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", // Recipient's address
"transaction": {
"hash": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
"amount": 4.000000000000000000,
"confirmations": 10
},
"technicalFee": // Technical commission for service operation
{
"currencyShortName": "XRP",
"transportProtocol": "Ripple",
"amount": 1.654684587513200000
}
}
}
Consuming callbacks In Your System
Successful Request
If the callback request is successful, your system should respond with an HTTP 200 OK status code. If an identical request is received after a successful callback response, you should form the same response as the previous one.
Requests are considered identical if they have the same values for the following parameters in the request body:
type - Transaction type
id - Transaction identifier in the processing system
status - Transaction status
Multiple Callbacks
Callbacks schedule
The callback will not be repeated if your system responds with the following HTTP codes: 1xx, 3xx, 4xx.
In case of an HTTP 5xx response, we will retain the callback in our sending queue and continue to attempt to send according to an exponential backoff policy. The delay of the next attempt relative to the previous one is calculated using the formula: 60 seconds + ^ 4.
The maximum number of retry attempts is 10.
The intervals for retries will be calculated as follows: