# Handling callbacks {#en_platform_callbacks}

An article about working with callbacks which are programmatic messages that allow merchants to receive up-to-date information significant for processing of each payment, includes the description of callback types and data structures used in them.

**Parent topic:**[Handling payment processing information](en_platform_payment_information.md)

## Overview {#en_callbacks_overview}

### Introduction {#section_zcz_nrw_z5b .section}

A *callback* is a system message sent from the Ecommpay payment platform to the merchant's web service. It contains information about a specific event in the payment platform that usually takes place in the context of processing a paymentor storing customer payment data.

Callbacks allow merchants to receive information about various events. Along with that, the callback payload as well as the conditions of sending callbacks can be flexibly configured: you can define what data the callback should contain as well as specify in what cases, in what format, and where it should be sent. This article covers general information about callbacks, the procedure and special aspects of working with them.

### Callback types {#section_idc_bsw_z5b .section}

Callbacks can be roughly divided into two groups: *prescriptive* \(that require certain actions from the web service side\) and *informational* \(that are sent for informational purposes\).

Prescriptive callbacks are triggered by the necessity of a certain action: for example, specific data has to be sent to the payment platform, the customer must be provided with specific information or redirected to third-party services, and so on. Such callbacks always contain intermediate information, and you cannot opt out of receiving them since timely response to this category of callbacks is indispensable for payments to be processed correctly.

Informational callbacks are triggered by such events as the change of the payment status or the generation of the payment card token. These callbacks can contain intermediate or final payment information, and you can opt out of receiving them \(selectively or fully\).

**Note:** Even if you decide not to receive informational callbacks, there still remain other options for obtaining payment information. These options include sending requests via the Gate API \([details](en_Gate_payment_status_request.md#)\) andthe Data API \([details](en_dbl_using_api.md#)\) as well as using the tools of the Dashboard interface. At the same time, callbacks are the fastest and the most reliable option for obtaining information \(with the confirmation of the information receipt\), and opting out of callbacks receipt should take place only in reasonable cases when it aligns with the aspects of the web service operation.

### Common use cases {#section_jpr_31m_1vb .section}

Callbacks are typically triggered by the following events.

-   *Payment status has changed.*

    In this case, callbacks can contain intermediate or final information about payment processing.

    ```language-json
    {
        "project_id": 42,
        "customer": {
            "id": "6361696170"
        },
        "payment": {
            "id": "456789",
            "type": "purchase",
            "status": "awaiting capture",      // intermediate payment status
            "date": "2022-01-11T13:00:40+0000",
            "method": "card",
            "sum": {
                "amount": 20000,
                "currency": "USD"
            },
            "description": ""
        },
        "account": {
            "number": "431422******0056 ",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "expiry_month": "03",
            "expiry_year": "2026"
        },
        "operation": {
            "id": 2777000002350,
            "type": "auth",
            "status": "success",
            "date": "2022-01-11T13:00:40+0000",
            "created_date": "2022-01-11T13:00:37+0000",
            "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9",
            "sum_initial": {
                "amount": 20000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "USD"
            },
            "provider": {
                "id": 120,
                "payment_id": "224750650",
                "date": "2022-01-11T13:00:39+0000",
                "result_code": "000",
                "result_message": "Approved",
                "auth_code": "505050",
                "endpoint_id": 120
            },
            "code": "0",
            "message": "Success",
            "description": "SUCCESS",
            "eci": "00"
        },
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
    }
    ```

    ```language-json
    {
        "project_id": 42,
        "payment": {
            "id": "456789",
            "type": "purchase",
            "status": "success",      // final payment status
            "date": "2022-01-11T15:54:40+0000",
            "method": "card",
            "sum": {
                "amount": 20000,
                "currency": "USD"
            },
            "description": ""
        },
        "account": {
            "number": "431422******0056 ",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "expiry_month": "03",
            "expiry_year": "2026"
        },
        "customer": {
            "id": "6361696170"
        },
        "operation": {
            "id": 7178000006597,
            "type": "capture",
            "status": "success",
            "date": "2022-01-11T15:54:40+0000",
            "created_date": "2022-01-11T15:54:39+0000",
            "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0",
            "sum_initial": {
                "amount": 20000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "USD"
            },
            "provider": {
                "id": 120,
                "payment_id": "227307324",
                "date": "2022-01-11T15:54:40+0000",
                "auth_code": "919372",
                "endpoint_id": 120
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..."
    }
    ```

-   *Actions on the web service side are required.*

    In this case, callbacks usually contain information for redirecting customers, displaying specific information to them, or specifying additional data necessary for payment processing.

    ```language-json
    "redirect_data":{
        "method": "GET",
        "body": [],
        "encrypted": [], 
        "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
      }
    ```

    ```language-json
     "display_data": [
                {
                    "type": "qr_data",
                    "title": "QR code",
                    "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG"
                },
                {
                    "type": "add_info",
                    "title": "QR Code Timeout",
                    "data": "600"
                }
            ]
    ```

-   *Payment card token has been generated or deleted.*

    In this case, callbacks contain information about events related to payment card tokens \(such as token generation or deletion\).

    ```language-json
    {
        "general":{
        "project_id":42,
        "customer_id":6361696170,
        "signature":"gmTHcy4ISuWEiV8+AupOYkl9S5eLZ",
            "request": {
    			"id": "3c7f53fdbb5b8c96f9707457d75f",
    			"action": "tokenize",
    			"status": "success"
            },
        "token":"f365bb1729f9b72fd9c0970e35c91d18070d15654",
        "token_created_at":"2021-01-28 13:30:57",
        "token_status":"active"
    }
    ```


## Setup and configuration {#en_callbacks_configuration}

### Configuring for projects {#section_jlb_dcm_1vb .section}

Callbacks for the merchant's production projects are usually set up during the integration of the web service with the Ecommpay payment platform. Along with that, to change callback settings, you can always use the capabilities of Dashboard \([details](en_dbl_projects.md#)\), specify certain parameters in payment requests, and when necessary, contact the Ecommpay technical support specialists.

The following properties can be configured on the part of the merchant:

-   Requirement for sending callbacks.

    Callbacks can be triggered by all events or only by the events that correspond to the specified set of conditions.Such conditions include certain event types, payment methods as well as types and statuses of payments and operations.For example, callbacks can be disabled for the completed payouts and enabled for the declined ones. This allows you to promptly receive only the necessary information.

-   URLs for delivering callbacks.

    Callbacks triggered by different events can be sent to different web service URLs with regard to the event type,the payment method, the payment type and status. For example, callbacks with final information about declined payments can be sent to one URL, while callbacks with final information about completed payments can be sent to another URL.

-   Delay time for sending callbacks.

    If necessary, callbacks can be sent with a delay of up to 600 seconds \(inclusive\), for example, to streamline the handling of these callbacks on the web service side.

-   Set of parameters.

    For more convenient handling of callbacks on the web service side, you can vary their payload by adding and removing parameters, changing their names, and setting the requirement to include parameters with empty values. At the same time, you cannot change the callback structure and remove required parameters.

    Bear in mind that certain parameters can be required for all or only specific types of callbacks. The required parameters are always included in callbacks, while the optional ones are only sent in cases when the corresponding information has been received, or when sending such parameters with empty values has been set up.

    Thus, callbacks triggered by the same events can include different information depending on the settings.

    ```language-json
    {
        "account": {
            "number": "431422******0056 ",
            "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "expiry_month": "11",
            "expiry_year": "2027"
        },
        "customer": {
            "id": "6361696170",
            "phone": "441223262463"
        },
        "payment": {
            "date": "2022-11-11T13:02:42+0000",
            "id": "456789",
            "method": "card",
            "status": "success",
            "sum": {
                "amount": 40000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": ""
        },
        "project_id": 42,
        "operation": {
            "id": 969000002636,
            "type": "sale",
            "status": "success",
            "date": "2022-11-11T13:02:42+0000",
            "created_date": "2022-11-11T13:01:45+0000",
            "request_id": "c6eed1eb14c6290088cbc0be4667c",
            "sum_initial": {
                "amount": 40000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 40000,
                "currency": "USD"
            },
            "provider": {
                "id": 408,
                "payment_id": "330157196",
                "date": "2022-11-11T13:02:32+0000",
                "auth_code": "",
                "endpoint_id": "612266625"
            },
            "code": "0",
            "message": "Success",
            "eci": "07"
        },
        "signature": "v7KNMpfIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
    ```

    ```language-json
    {
        "account": {
            "number": "431422******0056 ",
            "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654",
            "type": "visa",
            "card_holder": "ARTHUR EDDINGTON",
            "id": 45678,
            "expiry_month": "11",
            "expiry_year": "2027"
        },
        "customer": {            // object with extended customer information
            "id": "6361696170",
            "email": "siraseddington@gmail.com"
            "phone": "441223262463",
            "first_name": "Arthur",
            "last_name": "Eddington"
        },
        "payment": {
            "date": "2022-11-11T13:02:42+0000",
            "id": "456789",
            "method": "card",
            "status": "success",
            "sum": {
                "amount": 40000,
                "currency": "USD"
            },
            "type": "purchase",
            "description": ""
        },
        "project_id": 42,
        "operation": {
            "id": 969000002636,
            "type": "sale",
            "status": "success",
            "date": "2022-11-11T13:02:42+0000",
            "created_date": "2022-11-11T13:01:45+0000",
            "request_id": "c6eed1e088cbc0be4667c",
            "sum_initial": {
                "amount": 40000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 40000,
                "currency": "USD"
            },
            "provider": {
                "id": 408,
                "payment_id": "330157196",
                "date": "2022-11-11T13:02:32+0000",
                "auth_code": "",
                "endpoint_id": "612266625"
            },
            "code": "0",
            "message": "Success",
            "eci": "07"
        },
        "signature": "v7KNMpfogVftZ1ZZ5D/aZAeb0VMdeR+CqGrYyilUwSm...=="
    }
    ```


### Managing callbacks for individual payments {#section_kld_ffm_1vb .section}

When processing payments via Gate, you can set up the URLs where callbacks will be delivered to, the requirement, and the delay time for sending callbacks. To do this, use the following parameters when sending payment requests:

-   `merchant_callback_url` \(passed in the `general` object\)—the callback URL for this specific request;
-   `force_disable` \(passed in the `callback` object\)—an indicator for disabling callbacks \(possible values: `true`, for disabling callbacks with information about the given payment, and `false`, for enabling these callbacks\).
-   `delay` \(passed in the `callback` object\)—the delay time for sending callbacks, in seconds \(possible values are 0 to 600; for example `42`\);

To learn if these parameters can be used in requests to certain endpoints, see [the Gate API](https://api-developers.ecommpay.com/) specification.

```language-json
{
    "general":{
        "project_id":42,
        "payment_id":"456789",
        "merchant_callback_url":"https://example.com",
        "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    },
    "customer":{
        "ip_address":"192.0.2.32",
        "id":"6361696170"
    },
    "payment":{
        "amount":40000,
        "currency":"USD",
        "callback":{
            "delay":42                // delay time set to 42 seconds
        }
    },
    "card":{
        "pan":"4314220000000056",
        "year":2027,
        "month":11,
        "card_holder":"ARTHUR EDDINGTON",
        "cvv":"123"
    }
}
```

## Use {#en_callbacks_usage}

### Handling callbacks {#section_nc3_vkm_1vb .section}

A callback is an HTTP POST message sent to the URL provided by the merchant. The procedure of responding to each callback on the web service side consists of the following steps:

1.  Accept and verify the callback.

    Callbacks should be accepted only if they have been sent from the payment platform's IP addresses provided by the Ecommpay technical support specialists. Along with that, it is recommended not to limit the waiting time for callbacks since different events can occur at different times while callbacks can be sent with a specified delay.

    The callback sender and data integrity should be validated by way of verifying the signature included in every callback. For more information, see [Signature generation and verification](en_platform_signature.md#).

2.  Confirm the callback receipt.

    For confirming the receipt of callbacks, synchronous HTTP responses should be sent to the payment platform with the corresponding response codes. If no errors have been detected upon the receipt, the response code should be `200 OK`. In other cases, the response code should correspond to the error type: for example, use `HTTP 400 Bad Request` if a parameter string could not be converted into an array or `HTTP 500 Internal Server Error` if the callback has been received at an incorrect URL of the web service.

    If the `200 OK` response has not been received from the web service, the callback will be sent again regardless of the error type.

3.  Perform the required actions.

    Upon the receipt of prescriptive callbacks, the actions that are stated in these callbacks as required should be performed; and upon the receipt of informational callbacks, the actions that correspond to the aspects of the web service operation should be performed \(for example, customer notification\).


### Resending callbacks {#section_qc3_vkm_1vb .section}

If the information about a callback receipt error has been communicated to the payment platform or the callback receipt has not been confirmed, this callback is sent again. Keep in mind that the data in such callbacks can change due to the changes of the corresponding information in the payment platform: for example, if a payment status changes, all subsequent callbacks contain the newly assigned status.

Generally, resending callbacks is carried out as follows:

1.  6 attempts at an increasing interval of 10 to 60 seconds.The interval increases by 10 seconds at each attempt.
2.  58 attempts at an increasing interval of 84 seconds to 2.5 hours.

    The interval, measured in seconds, is increased according to the formula `70 + 10 × 1.12n − 4` where *n* is the sequence number of the attempt.

3.  56 attempts every 4 hoursuntil a total of 120 attempts is reached. After that, callbacks triggered by the given event are no longer sent.

This order can slightly change depending on the load on servers and communication channels, but in general the time span for automatic callback delivery attempts does not exceed 11 days. You can change this order via the Ecommpay technical support specialists.

In addition to automatic resending of callbacks, you can also initiate one-time resending via Dashboard.

### Troubleshooting {#section_tc3_vkm_1vb .section}

There can be cases when callbacks are not received at the specified URLs for various reasons. These situations and the ways to resolve them can be divided into the following groups:

-   *There are no callbacks triggered by any of the events.*

    This can happen because certain requests and events have not been initiated in the platform, or issues with communication channels have been detected, or the web service URLs are invalid, or callbacks have been disabled in the project.

    In such cases, it is recommended to proceed as follows:

    1.  Ensure that the correct requests\(i.e. they do not disable callbacks\) were sent from the web service and accepted in the platform. It may be necessary to send a test request, for example, to generate a payment card token.
    2.  If requests are accepted in the platform, but callbacks are still not received, check if the URLs for delivering callbacks are correct. If problems are found, fix the URLs or replace them with the correct ones—on your own via Dashboard, or with the help of the Ecommpay technical support specialists.
    3.  If the previous steps did not help, contact the Ecommpay technical support specialists.
-   *There are no callbacks triggered by specific event types.*

    This can happen for the following reasons: there are no events of such types, web service URLs are invalid, or callbacks have been disabled for such event types.

    In such cases, it is recommended to proceed as follows:

    1.  Ensure that the events of the types for which callbacks are not received have been initiated. You can do this by using payment information tabs in the Dashboard interface.
    2.  Check the correctness of the URLs for receiving callbacks triggered by the corresponding event types. If problems are found, fix the URLs or replace them by the correct ones—on your own via Dashboard, or with the help of the Ecommpay technical support specialists.
    3.  If the previous steps did not help, contact the Ecommpay technical support specialists.
-   *There are no callbacks for a specific operation.*

    This can happen because the `callback` object in the request for processing the operation contains the `force_disable` parameter with the `true` value.

    In this case, you can check the operation status via Gate using requests for checking current payment information\([details](en_Gate_payment_status_request.md#)\),[Dashboard](en_dbl_payments.md#).


## Callback parameters {#en_callbacks_parameters}

### Callback parameters for payments and operations {#section_e4h_s5m_1vb .section}

The set of parameters sent in callbacks with payments and operations information can be standard or customised for separate projects. The following table contains the standard set of parameters.

|Parameter|Description|tree|
|---------|-----------|----|
|account   
 object, optional

|Object with the customer's payment details\(for example, the details of a payment card, an account, or a digital wallet\).|10|
|card\_holder  
 string, optional

|Cardholder's name.

 Example: `ARTHUR EDDINGTON`

|10-10 10|
|expiry\_month  
 string, optional

|Payment card expiration month.

 Example: `11`

|10-20 10|
|expiry\_year  
 string, optional

|Payment card expiration year.

 Example: `2027`

|10-30 10|
|id  
 integer, optional

|Saved payment data identifier used in the payment platform\([details](en_gate_saved_data.md)\).

 Example: `56789`

|10-40 10|
|number   
 string, required

|Masked number or another identifier of the customer's payment instrument \(for example, a payment card, an account, or a digital wallet\).

 Example: `424242***4243`

|10-50 10|
|token   
 string, optional

|Payment card token if it has been generated during the request execution\([details](en_Gate_Token.md)\).

|10-60 10|
|type  
 string, optional

|Payment card brand that was used in the processing of the payment: `amex`,`mastercard`, `maestro`, `visa`and others|10-70 10|
|acs  
 object, optional

|Object with information about the result of the customer's 3‑D Secure authentication.|20|
|acs\_url  
 string, required

|URL of the page to which the customer is redirected for the 3‑D Secure authentication \(ACS page\).

|20-10 20|
|md  
 string, required

|Merchant data received from a global card network during the customer's 3‑D Secure authentication.

|20-20 20|
|pa\_req  
 string, required

|PAReq \(Payer Authentication Request\) message received during the customer's 3‑D Secure authentication 3‑D Secure.|20-30 20|
|avs\_data  
 object, optional

|Object with information about the Address Verification Service check \(AVS, [details](en_Gate_avs.md)\)|30|
|avs\_post\_code  
 string, optional

|Customer's postal code passed for performing the AVS check.

 Example: `BS23 1XF`

|30-10 30|
|avs\_street\_address  
 string, optional

|Customer's address passed for performing the AVS check.

 Example: `42 Walliscote Road, Weston-super-Mare`

|30-20 30|
|avs\_result  
 string, optional

|Code of the AVS check result \([details](en_Gate_avs.md)\).

 Example: `F`

|40|
|bank  
 object, optional

|Object with information about the issuer of the payment card used during payment processing.|50|
|name  
 string, optional

|Issuer's name in the payment platform.

 Example: `LLOYDS`

|50-10 50|
|customer   
 object, optional

|Object with customer information.|70|
|billing  
 object, optional

|Object with information about the customer's billing address received in the payment platform during payment processing.|70-10 70|
|address  
 string, optional

|Street name specified in the customer's billing address.

 Example: `Walliscote Road`

|70-10-10 70-10|
|city  
 string, optional

|City name specified in the customer's billing address.

 Example: `Weston-super-Mare`

|70-10-20 70-10|
|country  
 string, optional

|ISO 3166-1 alpha-2 code of the country specified in the customer's billing address.

 Example: `GB`

|70-10-30 70-10|
|postal  
 string, optional

|Postal code specified in the customer's billing address.

 Example: `BS23 1XF`

|70-10-40 70-10|
|region  
 string, optional

|Name of the state, province, or region specified in the customer's billing address.

 Example: `Somerset County`

|70-10-50 70-10|
|city  
 string, optional

|Name of the customer's city.Example: `Weston-super-Mare`

|70-20 70|
|country  
 string, optional

|Code of the customer's country in the ISO 3166-1 alpha-2 format.

 Example: `GB`

|70-30 70|
|day\_of\_birth  
 string, optional

|Customer's birth date in the format of DD-MM-YYYY.

 Example: `22-12-1882`

|70-40 70|
|first\_name  
 string, optional

|Customer's name.

 Example: `Arthur`

|70-50 70|
|id   
 string, optional

|Customer's identifier within the merchant's project.

 Example: `6361696170`

|70-60 70|
|ip\_address  
 string, required

|Customer's IP address relevant for the given operation.

 Example: `192.0.2.32`

|70-70 70|
|last\_name  
 string, optional

|Customer's last name.Example: `Eddington`

|70-80 70|
|middle\_name  
 string, optional

|Customer's middle name.Example: `Stanley`

|70-90 70|
|phone   
 string, optional

|Customer's phone number that contains 4 to 24 digits.

 Example: `441223262463`

|70-100 70|
|decision  
 string, optional

|String with information about payment processing admissibility assessment performed on the payment platform side.|80|
|decision\_message  
 array, optional

|Array of records with information about payment processing admissibility assessment performed on the payment platform side.

 Example: `reject.message("RCS reject. Amount less than allowed")`

|90|
|display\_data  
 object, optional

|Object with information that should be displayed to the customer.

 This object usually contains the data received from a provider or a payment system.The specifics of what information has to be displayed for various payment methods are usually described in the articles about these methods.

 Example: `Approve the payment request sent to your phone`

|100|
|errors   
 array, optional

|Array of error messages received during request execution.|110|
|ErrorItem  
 object, required

|Object with information about the error that occurred during request execution.|110-10 110|
|code  
 integer, optional

|Error code.

 Example: `3287`

|110-10-10 110-10|
|description  
 string, optional

|Error reason details.

 Example: `EMPTY_REFUND_CURRENCY`

|110-10-10 110-10|
|field  
 string, optional

|Name of the parameter that was erroneously specified \(if such parameter is identified\).|110-10-20 110-10|
|message  
 string, optional

|Error code description.

 Example: `The property currency is required`

|110-10-30 110-10|
|interface\_type  
 object, optional

|Object with information about the way the payment was initiated.|120|
|id  
 integer, optional

|Indicator of the interface that was used for sending the initial request:-   `1`—request was sent via Gate.
-   `5`—request was sent via Dashboard.
-   `6`—request was sent via Payment Page opened in a modal window.
-   `7`—request was sent via Payment Page opened in an iframe object.

|120-10 120|
|user  
 string, optional

|Details about an account of the Dashboard user who sent the initial request.

 Example: `janedoe@cosmoshop.com`

|120-20 120|
|operation  
 object, optional

|Object with information about the operations related to the payment.|130|
|code  
 string, optional

|Code of the operation status \([details](en_platform_payment_info_codes.md)\).

 Example: `0`

|130-10 130|
|created\_date  
 string, optional

|Date and time of the operation creation.

 Example: `2022-10-08T18:52:19+0000`

|130-20 130|
|date  
 string, optional

|Date and time of the latest change of the operation status in the payment platform.

 Example: `2022-10-08T18:52:54+0000`

|130-30 130|
|eci  
 string, optional

|Indicator of the customer's 3‑D Secure authentication result \([details](en_ECI_codes.md)\).

 Example: `07`

|130-40 130|
|id  
 integer, optional

|Operation identifier in the payment platform.

 Example: `17007255`

|130-50 130|
|message  
 string, optional

|Description of the operation status code \([details](en_platform_payment_info_codes.md)\).

 Example: `Success`

|130-60 130|
|provider  
 object, optional

|Object with the payment result information received from a providerora payment system.|130-70 130|
|auth\_code  
 string, optional

|Authorisation code received from a providerora payment system.

 Example: `331040`

|130-70-10 130-70|
|date  
 string, optional

|Date and time of the payment processing completion on a providerora payment system side.

 Example: `2022-10-08T18:52:53+0000`

|130-70-20 130-70|
|endpoint\_id  
 string \(integer\), optional

|CRC32 identifier of the payment gateway of a providerora payment system.

 Example: `2`

|130-70-30 130-70|
|id  
 integer, optional

|Identifier of a providerora payment system in the payment platform.

 Example: `2`

|130-70-40 130-70|
|payment\_id  
 string, optional

|Payment identifier on a providerora payment system side.

 Example: `603458`

|130-70-50 130-70|
|recurring\_retry  
 object, optional

|Object with the information about retrying the debit operation executed as part of the regular COF purchase \([details](en_Gate__cof_gate_side.md#)\).|130-75 130|
|next\_retry\_date  
 string, optional

|Date and time of the next scheduled retry attempt.

 Example: `2022-10-08T18:52:19+0000`

|130-75-10 130-75|
|next\_retry\_exists  
 boolean, optional

|Indicator that shows whether the next scheduled attempt is available.

 -   `true`—a retry attempt is scheduled
-   `false`— a retry attempt is not scheduled

 This parameter is required if the `recurring_retry` object is passed.

|130-75-20 130-75|
|retry\_count  
 integer, optional

|Identifier of the retry attempt for the specific debit operation \(an integer from 1 to 7\).

 Example: `3`

|130-75-30 130-75|
|trigger\_operation\_id  
 integer, optional

|Identifier of the retried debit operation in the payment platform.

 Example: `17007255`

|130-75-40 130-75|
|request\_id  
 string, required

|Identifier of the latest request within the operation in the payment platform.

|130-80 130|
|status  
 string, required

|Operation status \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `success`

|130-90 130|
|sum\_converted  
 object, optional

|Object with information about the operation amount and currency after conversion \([learn more about currency conversion](en_Gate_Conversion.md)\).|130-100 130|
|amount  
 integer, optional

|Operation amount. Specified in minor currency units \(if they are applicable\) or in major currency units.

 Example: `8726`

|130-100-10 130-100|
|currency  
 string, optional

|Operation currency code in the ISO 4217 alpha-3 format.

 Example: `EUR`

|130-100-20 130-100|
|sum\_initial  
 object, optional

|Object with information about the operation amount and currency sent in the request.|130-110 130|
|amount  
 integer, required

|Initial operation amount in minor currency units.

 Example: `9055`

|130-110-10 130-110|
|currency  
 string, required

|Code of the initial operation currency in the ISO 4217 alpha-3 format.

 Example: `USD`

|130-110-20 130-110|
|type  
 string, required

|Operation type \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `sale`

|130-120 130|
|payment   
 object, required

|Object with essential payment details.|140|
|cascading\_with\_redirect  
 boolean, optional

|Indicator of the requirement to obtain customer's confirmation of an additional purchase attempt in case of the 3‑D Secure failure \([details](en_gate_cascading.md#)\):-   `true`—additional attempt is needed.
-   `false`—additional attempt is not needed.

|140-10 140|
|date   
 string, optional

|Date and time of the latest payment status update in the payment platform.

 Example: `2022-10-08T18:52:54+0000`

|140-20 140|
|description   
 string, optional

|Payment description sent in the initial request.

 Example: `Radio-controlled flying saucer nano size with delivery`

|140-30 140|
|id  
 string, required

|Payment identifier sent in the initial request.

 Example: `18641868`

|140-40 140|
|is\_new\_attempts\_available  
 boolean, optional

|Indicator of the additional purchase attempt availability \([details](en_PP_Try_Again.md)\): -   `true`—additional attempt is available.
-   `false`—additional attempt is not available.

|140-50 140|
|method   
 string, optional

|Payment method code\([details](en_pm_codes.md)\).

 Example: `card`

|140-60 140|
|merchant\_refund\_id   
 string, optional

|Refund identifier in the merchant's web service.

 Example: `refund_143`

|140-61 140|
|OperationFee  
 object, optional

|Object with information about the fee amount.|140-70 140|
|amount  
 string, optional

|Fee amount in minor currency units if this amount is included in the total operation amount.|140-70-10 140-70|
|currency  
 string, optional

|Code of the charged fee currency in the ISO 4217 alpha-3 format.|140-70-20 140-70|
|sum\_with\_surcharge  
 string, optional

|Total amount of the operation and the fee surcharge in minor currency units.|140-70-30 140-70|
|surcharge\_amount  
 string, optional

|Fee amount added to the payment amount in minor currency units \(applicable to microfinancing organisations\).|140-70-40 140-70|
|surcharge\_currency  
 string, optional

|Code of the currency in which the fee added to the payment amount was charged \(specified in the ISO 4217 alpha-3 format\).|140-70-50 140-70|
|region  
 string, optional

|Code of the region of operation processing \([details](en_region_codes.md)\).

 Example: `eea`

|140-80 140|
|status   
 string, required

|Payment status \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `partially refunded`

|140-90 140|
|sum  
 object, optional

|Object with payment amount and currency details.|140-100 140|
|amount  
 integer, required

|Payment amount with regard to all processed operations in minor currency units.

 Example: `8855`

|140-100-10 140-100|
|currency  
 string, required

|Payment code sent in the initial request in the ISO 4217 alpha-3 format.

 Example: `USD`

|140-100-20 140-100|
|timeout\_attempts  
 string, optional

|Time allocated for a purchase retry attempt \([details](en_PP_Try_Again.md)\), in seconds.

 Example: `360`

|140-110 140|
|type     
 string, required

|Payment type \(according to [the payment model](en_platform_payment_model.md)\).

 Example: `purchase`

|140-120 140|
|scheme\_id   
 string, optional

|Identifier of the operation that initialised a COF payment. Assigned by the global card scheme \(Mastercard, Visa\). Can be passed when the COF payment is registered in the European Economic Area.

 Example: `MCS38A0790706`

|210|
|project\_id  
 integer, required

|Merchant's project identifier in the payment system.

 Example: `42`

|150|
|provider\_extra\_fields   
 object, optional

|Object with the details received from a providerora payment system.|160|
|recurring   
 object, optional

|Object with a COF purchase data \([details](en_Gate__payments_on_saved_data.md)\)|170|
|currency   
 string, optional

|Code of the COF purchase currency in the ISO 4217 alpha-3 format.

 Example: `USD`

|170-10 170|
|id   
 integer, optional

|Identifier of the record of a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\) in the payment platform.

 Example: `1001648`

|170-20 170|
|register\_payment\_id  
 string, optional

|Identifier of the record of a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\) in the merchant's web service.

 Example: `18641865`

|170-30 170|
|status  
 string, optional

|Status of the record of a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\):-   `active`—record about a series of funds debiting is active.
-   `canceled`—record about a series of funds debiting is inactive \(for example, if a COF purchase was cancelled by the merchant's request\).

|170-40 170|
|type  
 string, optional

|COF purchase type \([details](en_Gate__saved_cards_payments_type.md)\):-   `C`—OneClick purchase
-   `U`—autopurchase
-   `R`— regular purchase

|170-50 170|
|valid\_thru   
 string, optional

|Expiration date of the record about a series of funds debiting \([details](en_gate_payment_recurring_registration.md)\).

 Example: `2023-05-20T00:00:00+0000`

|170-60 170|
|redirect\_data  
 object, optional

|Object with data for customer redirection.|180|
|body  
 object, optional

|Data for customer redirection.|180-10 180|
|method  
 string, optional

|Method required for sending the redirection request: `POST` or `GET`.|180-20 180|
|url  
 string, optional

|URL to which the customer should be redirected.|180-30 180|
|signature   
 string, required

|Callback signature \([details](en_platform_signature.md#)\).|190|

### Callback parameters for tokens {#section_f4h_s5m_1vb .section}

The set of parameters sent in callbacks triggered by actions with tokens \(for example, creating or deleting a token\) can be standard or customised for separate projects. The following table contains the standard set of parameters.

|Parameter|Description| |
|---------|-----------|--|
|general  
 object, required

|Object with general identification information from the initial tokenisation request.|1|
|project\_id  
 string, required

|Merchant's project identifier in the payment platform.

 Example: `42`

|1-11|
|customer\_id  
 string, optional

|Customer identifier in the merchant's project.

 Example: `17008`

|1-21|
|signature  
 string, required

|Callback signature.|1-31|
|request  
 object, required

|Object with the initial request information.|2|
|id  
 integer, required

|Initial request identifier.

|2-12|
|action  
 string, optional

|Type of the initial request:-   `tokenize`—request for generating a token;
-   `token_revoke`—request for revoking a token.

Callbacks can be sent without this parameter if a token was revoked due to its expiration that leads to automatic sending of the callback.

|2-22|
|status  
 string, required

|Request status:-   `success`—request is completed;
-   `error`—request is not completed due to the errors specified in the `errors` array.

|2-32|
|errors  
 array, optional

|Array with information about the errors that occurred during the request execution.This array is not sent in case of a successful request processing.

|2-42|
|ErrorItem  
 object, required

|Object with information about an error that occurred during the request execution.|2-4-12-4|
|code  
 string, optional

|Code of the error that occurred during the request execution.

 Example: `3021`

|2-4-1-12-4-1|
|message  
 string, optional

|Error code description.

 Example: `Card expired`

|2-4-1-22-4-1|
|field  
 string, optional

|Name of the parameter in the initial request where an error occurred. This name is sent if the corresponding parameter is identified.|2-4-1-32-4-1|
|token  
 string, optional

|Payment card token.

|3|
|token\_created\_at  
 string, optional

|Date and time of the token generation.

 Example: `2022-07-22T03:31:24+0000`

|4|
|token\_status  
 string, optional

|Token status:-   `active`—token is active and can be used in payment processing.
-   `expiry`—token is inactive due to its expiration.
-   `revoke`—token is inactive because it was deleted upon the request from the merchant's web service.

|5|

## Related topics {#en_callbacks_links}

During the work with callbacks, the following information can come in handy:

-   [Interaction concepts](en_gate_interaction_organisation.md#)—the section with general information about the interaction with the payment platform via Gate.
-   [Signature generation and verification](en_platform_signature.md#)—the section with information about the work with data signing.
-   [Handling operation processing information](en_platform_payment_info_codes.md)—the section with information about the error codes used in the payment platform.
-   [Monitoring and performing payments](en_dbl_payments.md#)—the section with information about processing and monitoring payments and operations via Dashboard.
-   [Using tokens](en_Gate_Token.md)—the section with information about working with card tokens.
-   [API Reference](https://api-developers.ecommpay.com/)—the Gate API interface specification.