Callback notifications

The bank API allows you to receive callback notifications on changes of payment statuses.

General information

Events that can trigger notifications

You can receive notifications about changes in order payment status and other events in the bank.

The most common notifications describe changes in order status, such as:

• debiting of funds
• holding of funds
• payment reversal
• refund

More advanced integrations may make use of additional callback triggers like:

• saving of a card (i.e., storing a credential)
• enabling/disabling an existing stored credential
• payments being declined, etc.

The trigger type is passed in the operation parameter of the callback (see details below). For convenience, the callbacks for additional triggers can be directed to another URL by using the dynamicCallbackUrl parameter in order registration requests.

Requirements for SSL certificates on the store’s website

If a callback is delivered over HTTPS connection, the identity of the Partner's website must be verified with an SSL certificate issued and signed by a trusted certificate authority (check the table below). Self-signed certificates are not allowed.

URL format for callback notifications

POST and GET requests can be sent.

Below is an example for a GET request. The parameters are received in the query.

https://mybestmerchantreturnurl.com/callback/?mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

For POST callbacks, you will receive the same parameters in HTTP body (instead of query parameters).

https://mybestmerchantreturnurl.com/callback/
mdOrder=
1234567890-098776-234-522&orderNumber=0987&operation=deposited&
callbackCreationDate=Mon Jan 31 21:46:52 UTC 2022&status=0

The passed parameters are shown in the table below.

The table contains only basic parameters. You can also use additional parameters if they are configured in bank.

Custom headers for callback notifications

You can request the technical support service to set custom headers for callback notifications. For example:

'http://mybestmerchantreturnurl.com/callback.php', headers={Authorization=token, Content-type=plain
/text}, params={orderNumber=349002, mdOrder=5ffb1899-cd1e-7c1e-8750-e98500093c43, operation=deposited, status=1}

where {Authorization=token, Content-type=plain/text} is a custom header.

Examples

https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0

Algorithm for processing status callback notifications

1. The payment gateway sends to the Partner's server the following request.
   https://mybestmerchantreturnurl.com/callback/?mdOrder=1234567890-098776-234-522&orderNumber=0987&operation=deposited&status=0
2. The Partner's server returns HTTP 200 OK to the payment gateway.

When notifications fail

If a response other than 200 OK is returned to the bank, the notification is considered unsuccessful. In this case, the bank repeats the notification at intervals of 30 seconds until one of the following conditions is met:

• the bank receives 200 OK, OR
• there are 3 successive notification failures.

When one of the above conditions is met, attempts to send a callback notification about an event stop.

Additional callback parameters

In callback notifications, you can use the following additional parameters if they are configured in the Payment Gateway. If you need them, contact our support team.