Callbacks in Payment Page

Callback is a system message that the ITX payment platform sends to the merchant's URL to pass some information, for example payment result.

What callbacks in ITX look like

Callbacks are HTTP POST requests sent to the URL that you provide ITX with when integrating.

The callback body contains a JSON string of parameters. You can configure what parameters are to be sent in the request body. To do so, contact the ITX technical support.

Here is an example of a callback body of the typical structure. For demonstration purposes, the contents of the JSON string in the example are split into multiple lines.

Figure: Example of a callback of the typical structure

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "mobile",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The following is an example of the body of a customized callback.

Figure: Example of a customized callback

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "method": "mobile",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": ""
    },
    "customer": {            // object with expanded customer data
        "id": "customer_123",
        "email": "johndoe@example.com",
        "phone": "491234567890",
        "first_name": "John",
        "last_name": "Doe"
    },
    "operation": {
        "id": 28,
        "type": "sale",
        "status": "success",
        "date": "2022-03-25T11:08:45+0000",
        "created_date": "2022-03-25T11:08:05+0000",
        "request_id": "9e32835fb27907e0b08569d7d150e387a16a80e336c5117242b5cf60a4e17839",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-321",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4Xr4DSX2UuHp99rHrtaxkUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The callbacks from ITX always have a signature. For the information on how to verify the signature in a callback, see Signature generation and verification.

When ITX sends callbacks

The ITX payment platform sends you callbacks in the following cases:

the status of the payment has been changed. It may be due to, for example, redirecting the customer, displaying them payment instructions, completing 3D-Secure authentication, asking the customer to provide data required for the payment, etc. To learn more about operation statuses at the ITX payment platform, see Payment types, operations and payments.
If you perform payments by using Payment Page, these callbacks are sent to you for informational purposes only. Your system just has to respond with the HTTP 200 OK status code to them, no other action is required. Also, you can choose not to receive such callbacks. To do so, contact the ITX technical support.
a card token has been generated, revoked or expired. See the example of such a callback in the Callback format section.
the operation has finished processing in the ITX payment platform.

Callback delivery addresses

Callbacks are sent to the URL that you provide ITX with when integrating. If you have several projects, you can provide ITX with individual URLs for each project.

You can provide ITX with individual URLs to receive callbacks with certain information about the payment, e.g. for the payment platform to send you callbacks for successfully performed payment to one URL and callbacks for the declined ones to the other. You can also use individual URLs to receive callbacks for the payments of a certain type or payments performed with a specific payment method.

You can specify individual URLs for receiving callbacks yourself by using Dashboard. To do so, go to Dashboard, select the Projects section, and then click the Callbacks tab. The tools in Dashboard allow you to specify in what cases and where ITX will send callbacks to. To learn more about specifying URLs in Dashboard, see Working with callback settings.

Please note that your system must accept callbacks only from the IP address you receive from ITX when integrating. To double-check the IP address, contact the ITX technical support.

Callback delivery addresses for a specific payment

You can also specify an individual URL for receiving callbacks for a specific payment. To do so, add the merchant_callback_url parameter to the request for opening the checkout page and set its value to the URL that ITX should use to send callbacks to. After that the payment platform will send all the callbacks related to the payment (and only to this payment) to this URL ignoring any callback URLs configured in your project.

Figure: Example of the data from a request with the URL used for the specific payment

EPayWidget.run(
    {
        project_id: 1234,
        payment_id: 'payment_47',
        customer_id: 'customer_123',
        customer_first_name: 'John',
        customer_last_name: 'Doe',
        customer_email: 'johndoe@example.com',
        merchant_callback_url: 'http://example.com/callback',
        payment_currency: 'USD,
        payment_amount: 10000,    
        signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO\/RLUkDJrOcZzUCwX6R\/ekpZhkIQg=='
    }
)

How to respond to callbacks

Your system must respond to the callback with the HTTP 200 OK status code if it has successfully accepted it. Please note that your system shouldn't have any limitations on the time callbacks are received because callbacks from ITX may be sent with delay.

Warning: In some cases ITX may resend callbacks with payment result for the payments that have already been performed. If your system receives such a callback, it must respond to it with the HTTP 200 OK status code and not provide any services or additional goods to the customer for that payment again.

If your system fails to accept and/or process a callback, it must respond to it with the relevant error message like 400 Bad Request status code (for example, if you were unable to convert a parameter string to an array) or 500 Internal Server Error status code (for example, if the callback was sent to the wrong URL). Even though your system wasn't able to accept and/or process a callback, it must be ready to accept further callbacks for this payment.

If your system hasn't responded with the HTTP 200 OK status code to the callback, ITX will resend callbacks according to the following schedule:

6 attempts at 10-second intervals
then 62 attempts within 4 hours with increasing intervals. The interval increases according to the formula: 70 + 10·1,12^n-4, where n is the serial number of the attempt
after that, the callbacks are sent every 4 hours until the maximum number of attempts is achieved.

In total, ITX sends 120 callbacks within 11 days. The callback delivery schedule may insignificantly change depending on the system load.

Callback parameters

The parameters that are passed in callbacks may differ depending on the request. Additionally you can extend the list of parameters that are sent in callbacks for your project. To extend the parameter set, contact technical support specialists support@kzitx.com

Attention: The callback signature is generated by using all the parameters the callback contains.

The minimal set of parameters in callbacks that the payment platform sends after payment processing is described below.

Table 1. Callback objects and parameters
Parameter	Description	tree
account object, optional default	The object that contains the details of the customer bank card or other payment account	10
card_holder string, optional	Card holder name	10-10 10
expiry_month string, optional	Card expiration month	10-20 10
expiry_year string, optional	Card expiration year	10-30 10
id integer, optional	ID of saved card in Gate	10-40 10
number string, required default	Masked bank card or other account number. Example: `424242***4242`	10-50 10
token string, optional default	Token of the customer bank card. The token is generated automatically when a successful payment is performed provided the corresponding option was enabled when integrating with ITX.	10-60 10
type string, optional	Type of the customer bank card or the mobile operator which is used to perform a payment. For possible values for bank cards, see Supported payment cards.	10-70 10
acs object, optional	The object that contains the result of the customer authentication by using 3‑D Secure. This object is available in callback, if the payment was made with the card that supports 3‑D Secure.	20
acs_url string, required	URL of the issuing bank ACS page.	20-10 20
md string, required	Merchant technical data in the payment system.	20-20 20
pa_req string, required	The authentication request that need to be sent to the issuing bank. The parameter contains encoded information about the card holder, the merchant, and the payment.	20-30 20
avs_data object, optional	The object that contains the results of the AVS matching (Address Verification Service). For more information, see Checking with Address Verification Service	30
avs_post_code string, optional	Postcode of the customer address.	30-10 30
avs_street_address string, optional	Customer address	30-20 30
avs_result string, optional	Result of the Address Verification Service (AVS) matching. For more information, see Checking with Address Verification Service	40
bank object, optional	The object that contains the data about a card issuer bank.	50
name string, optional	The name of the card issuer bank.	50-10 50
customer object, required default	The object that contains information about the customer who initiated the payment.	70
billing object, optional	The object that contains information about the billing address of the customer.	70-10 70
address string, optional	Street address of the customer billing address.	70-10-10 70-10
city string, optional	City of the customer billing address.	70-10-20 70-10
country string, optional	Country of the customer billing address, in ISO 3166-1 alpha-2 format. Example: `UK`	70-10-30 70-10
postal string, optional	Postcode of the customer billing address.	70-10-40 70-10
region string, optional	Region of the customer billing address.	70-10-50 70-10
city string, optional	Customer city	70-20 70
country string, optional	Country of the customer	70-30 70
day_of_birth string, optional	Birth date of the customer in the DD-MM-YYYY format.	70-40 70
first_name string, optional	Customer first name	70-50 70
id string, required default	Unique ID of the customer in your project.	70-60 70
ip_address string, required	Customer IP address as specified in the initial request.	70-70 70
last_name string, optional	Customer last name	70-80 70
middle_name string, optional	Customer middle name	70-90 70
phone string, optional default	Customer phone number. From 4 to 24 digits	70-100 70
decision string, optional	A string that contains the Risk Control System decision related to the payment.	80
decision_message array, optional	The array of strings with the messages from the Risk Control System related to the decision regarding the payment. Example: `reject.message("RCS reject. Amount less than allowed")`.	90
display_data object, optional	The object that contains the data from the payment provider that are required to display QR code with payment details to the customer.	100
errors array, optional default	Array of error messages encountered during the payment processing.	110
ErrorItem object, required	The object that contains information about a single error.	110-10 110
code integer, optional	Error code	110-10-10 110-10
description string, optional	The description of the error cause.	110-10-10 110-10
field string, optional	This parameter contains the name of the parameter in which the error occurred, if it was possible to locate the failed parameter.	110-10-20 110-10
message string, optional	Message that explains the cause of the error.	110-10-30 110-10
interface_type object, optional	Object that contains the information about the source the payment request originates from.	120
id integer, optional	Parameter that specifies the interface the payment request originates from. Possible values: `1`—the request issued by using API Gate `2–4`— the request is issued by ITX `5`—the request is issued by using Dashboard `6`—the request is issued by Payment Page in modal window `7`—the request is issued by Payment Page in iframe	120-10 120
user string, optional	Parameter that specifies the Dashboard user that initiated the payment request. Example: `johndoe@example.com`	120-20 120
operation object, optional	The object that contains information about the operation that triggered the callback	130
code string, optional	Unified payment provider response code. For the list of the codes, see Operation statuses and response codes	130-10 130
created_date string, optional	Date and time the operation was created. Example: `2017-07-27T15:19:13+0000`	130-20 130
date string, optional	Date and time the payment status was last updated	130-30 130
eci string, optional	The indicator that shows the result of the 3‑D Secure customer authentication. For more information, see Electronic Commerce Indicator (ECI) codes	130-40 130
id integer, optional	Unique ID of the operation.	130-50 130
message string, optional	Unified message from the payment provider. For more information about the response codes, see Operation statuses and response codes.	130-60 130
provider object, optional	The object that contains external provider information about the result of the operation.	130-70 130
auth_code string, optional	Authorization code received from an external provider.	130-70-10 130-70
date string, optional	The date and time the payment provider finished processing the payment.	130-70-20 130-70
endpoint_id string (integer), optional	CRC32 ID of the external provider gate. In some cases, because of payment system or provider requirements, the type of this parameter may be integer.	130-70-30 130-70
id integer, optional	The payment provider that has been used to process the operation.	130-70-40 130-70
payment_id string, optional	Unique ID of the payment in the provider system.	130-70-50 130-70
request_id string, required	Unique ID of the last request related to the operation	130-80 130
status string, required	Operation status. For more information about operation statuses, see Operation statuses and response codes	130-90 130
sum_converted object, optional	The object that contains the currency of the payment provider account and the initial amount denominated in this currency.	130-100 130
amount integer, optional	The amount in minor units of the payment provider currency	130-100-10 130-100
currency string, optional	The currency of the payment provider account in ISO 4217 alpha-3 format. Example: `EUR`	130-100-20 130-100
sum_initial object, optional	The object that contains the amount and currency of the operation as specified in the initial request.	130-110 130
amount integer, required	The operation amount as specified in the initial request in minor units of the currency.	130-110-10 130-110
currency string, required	Payment currency in ISO 4217 alpha-3 format as specified in the initial request. Example: `USD`	130-110-20 130-110
type string, required	The operation type	130-120 130
payment object, required default	The object that contains the payment data	140
cascading_with_redirect boolean, optional	The indicator shows whether you need to redirect the customer to a different ACS URL to retry the 3D-Secure authentication when an external provider declines the operation, and to display a page with an error message and the Try Again button. `true`—retry the 3D-Secure authentication; `false`—no need to retry the 3D-Secure authentication.	140-10 140
date string, optional default	Date and time of the last payment status update Example: `2017-07-27T15:19:13+0000`	140-20 140
description string, optional default	The description of the payment as specified in the initial request	140-30 140
id string, required default	Unique ID of the payment in your web service	140-40 140
is_new_attempts_available boolean, optional	The indicator that shows if the customer can retry the payment. `true`—customer can retry the payment `false`—customer cannot retry the payment This parameter is issued, if the "Try Again" functionality is enabled in Payment Page	140-50 140
method string, optional default	Payment method Example: `card`	140-60 140
merchant_refund_id string, optional	Unique identifier of a refund in the merchant system Example: `refund_1`	140-61 140
operation_fee object, optional	The object that contains the information about per- operation fee charged by ITX	140-70 140
amount string, optional	Amount of per-operation fee specified in minor units of the fee currency	140-70-10 140-70
currency string, optional	Currency of the operation fee, in ISO 4217 alpha-3 format. Example: `EUR`	140-70-20 140-70
sum_with_surcharge string, optional	Total amount of the operation surcharge and operation amount specified in minor currency units	140-70-30 140-70
surcharge_amount string, optional	Amount of the operation surcharge specified in minor currency units	140-70-40 140-70
surcharge_currency string, optional	Currency of the operation surcharge, in ISO 4217 alpha-3 format. Example: `EUR`	140-70-50 140-70
region string, optional	The region of the country where the card operation is processed.	140-80 140
status string, required default	Payment status. Example: `success`	140-90 140
sum object, optional default	The object that contains the information about payment amount, including refunds, and the currency as specified in the initial request	140-100 140
amount integer, required	Payment amount including refunds, in minor currency units	140-100-10 140-100
currency string, required	Payment currency in ISO 4217 alpha-3 format as specified in the initial request. Example: `USD`	140-100-20 140-100
timeout_attempts string, optional	The time when the customer can retry the payment after an initial decline. This parameter is issued, if the "Try Again" functionality is enabled in Payment Page	140-110 140
type string, required default	Payment type. Example: `purchase`	140-120 140
project_id integer, required default	The unique ID of your project	150
provider_extra_fields object, optional default	The object that contains the data from the payment provider that are required to complete the payment or to compile reports.	160
recurring object, optional default	The object that contains COF purchase registration data. The data are submitted, if the initial request for payment includes the recurring_register=1 line and the payment is successful.	170
currency string, optional default	COF purchase currency ISO 4217 alpha-3. Example: `USD`	170-10 170
id integer, optional default	COF payment ID.	170-20 170
register_payment_id string, optional	COF payment ID on merchant side	170-30 170
status string, optional	COF purchase status. Possible values: `active`—COF purchase is active. `canceled`—COF purchase is canceled.	170-40 170
type string, optional	COF purchase type. Possible values: `R`—COF purchase `U`—autopayment `C`— payment	170-50 170
valid_thru string, optional default	Expiration date of the COF purchase ID	170-60 170
redirect_data object, optional	The object that contains the data for redirecting customer to provider to complete the current payment.	180
body object, optional	The set of parameters with the data for redirection. If this parameter contains no data, it is added to the callback as an empty array (`"body": []`). If this parameter does contains any data, it is added to the callback as a JSON object (`"body": {...}`).	180-10 180
method string, optional	Request submission method: `POST` or `GET`.	180-20 180
url string, optional	The redirection URL.	180-30 180
signature string, required	Callback signature. For more information, see Signature generation and verification	190