Callbacks

General Information

• Represented as an HTTP POST request to the client's system, sent to the URL specified in the personal account
• Data in the request and response body is available in JSON format
• The request contains the following headers:
  • Content-Type: application/json
  • User-Agent: information about the calling system
• Dates are transmitted in UTC in ISO 8601 format. For example: 2024-07-02T12:50:30Z

Callback URL Requirements

1. Must use the secure HTTPS protocol
2. Must use domain names, not IP addresses

Authentication

Authentication for a callback is performed by sending headers in the request, similar to the headers used for authorizing API requests (see the Authorization section).

Callback Verification

To prevent fraud, the client's system must verify the values of the specified callback headers as follows:

1. 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
2. The value of the X-Processing-Key header matches the value of the client's active public API access key
3. The value of the X-Processing-Signature header matches the signature of the request data signed with the secret key

Handling Callbacks

Successful Response

If the callback request is successful, the client's system must respond with the HTTP code 200 OK.

Idempotency

If, after a successful response to a callback request, another similar request arrives, the same response as for the previous one must be generated.

Requests are considered similar if they have the same values for the following parameters in the request body:

• type - Transaction type
• id - Transaction identifier in the processing system (for an address check - checkId)
• status - Transaction status

Transaction Uniqueness

To determine whether several callbacks relate to the same transaction or to different ones, use the combination of the type and id parameters from the root element of the callback JSON. This combination is unique across all transactions.

For address check callbacks (type = AddressCheck), the checkId parameter is used instead of id.

Retry Policy

Codes Without Retries

A callback will not be retried if the client's system responds with the following HTTP codes:

• 1xx
• 3xx
• 4xx

Codes With Retries

If the response has an HTTP code in the 5xx range, the callback remains in the send queue and delivery attempts continue according to an exponential backoff policy.

Backoff calculation formula:

60 seconds + {retry count}^4

Maximum number of retry attempts: 10

Retry Intervals

Attempt	Interval	Total Time
1	61 sec	61 sec
2	76 sec	137 sec
3	141 sec	278 sec
4	361 sec	594 sec
5	685 sec	1,279 sec
6	1,356 sec	2,635 sec
7	2,461 sec	5,096 sec
8	4,156 sec	9,252 sec
9	6,621 sec	15,873 sec
10	10,060 sec	25,933 sec (~7.2 hours)