Handling callbacks

Overview

Introduction

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 payment or 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.

A callback is a system message with information about a specific event sent from the ecommpay payment platform to the merchant's web service. This article covers general information about callbacks, the procedure and special aspects of working with them.

Callback types

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).

Callbacks can be roughly divided into two groups: prescriptive and informational.

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.

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.

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) and the Data API (details) as well as using the tools of the Dashboard interface and the Telegram bot. 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

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.

    Figure: Example of callback data indicating that the payment has been assigned an intermediate status

    {
        "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..."
    }

    Figure: Example of callback data indicating that the payment has been assigned a final status

    {
        "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.

    Figure: Example of callback data indicating that the customer redirection is required

    "redirect_data": {
        "body": {},
        "method": "GET",
        "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC"
      }

    Figure: Example of callback data indicating that displaying a QR code to the customer is required

     "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).

    Figure: Example of callback data indicating that a payment card token has been generated

    {
        "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

Configuring for projects

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), 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:

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, you can use the capabilities of Dashboard and the Gate API and contact our technical support to configure the following properties:

  • 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.

    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.

  • 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.

    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.

  • 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.

    If necessary, callbacks can be sent with a delay of up to 600 seconds (inclusive).

  • 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.

    You can vary the callback 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.

    Figure: Example of standard callback data indicating that the one-time purchase has been completed

    {
        "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...=="
    }

    Figure: Example of customised callback data indicating that the one-time purchase has been completed

    {
        "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": "Arthyr",
            "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

When processing payments via Payment Page, you can set up the URLs where callbacks will be delivered to. To do this, use the merchant_callback_url parameter in the requests for opening the payment form.

Figure: Example of the request for opening Payment Page with the callback settings specified

https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=ru&customer_id=customer_12&project_id=42&payment_amount=131970&payment_id=456789&merchant_callback_url=https%3A%2F%2Fexample.com&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB...

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 specification.

Figure: Example of data sent in the purchase request with the callback settings specified

{
    "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

Handling callbacks

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:

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.

    Callbacks should be accepted only if they have been sent from the payment platform IP addresses provided by the ecommpay technical support specialists, and the waiting time for callbacks should not be limited. Along with that, data integrity should be validated by way of verifying the signature included in every callback.

  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.

    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, HTTP 400 Bad Request.

    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

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:

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. 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 hours until 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.

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 and Telegram bot if necessary.

Troubleshooting

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), Dashboard, and Telegram bot.

There can be cases when callbacks are not received at the specified URLs for various reasons: for example, 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. The merchant can handle such situations as follows:

  1. Ensure that callbacks are not disabled for the whole project in use or for certain event types in the project.
  2. 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.
  3. Check if the URLs for delivering callbacks are correct. 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.
  4. If the previous steps did not help, contact the ecommpay technical support specialists.

Callback parameters

Callback parameters for payments and operations

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).

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 (detailsdetails).

10-60 10

type
string, optional

Payment card brand or mobile provider name that was used in the processing of the payment:

  • Payment card brands: amex, mastercard, maestro, visa and others
  • Mobile providers: KCELL, ACTIV, MPESA
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) 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).

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 (detailsdetails).

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).

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 (detailsdetails).

Example: Success

130-60 130

provider
object, optional

Object with the payment result information received from a provider or a payment system. 130-70 130

auth_code
string, optional

Authorisation code received from a provider or a payment system.

Example: 331040

130-70-10 130-70

date
string, optional

Date and time of the payment processing completion on a provider or a 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 provider or a payment system.

Example: 2

130-70-30 130-70

id
integer, optional

Identifier of a provider or a payment system in the payment platform.

Example: 2

130-70-40 130-70

payment_id
string, optional

Payment identifier on a provider or a 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). 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 modelthe payment model).

Example: success

130-90 130

sum_converted
object, optional

Object with information about the operation amount and currency after conversion (learn more about currency conversionlearn more about currency conversion). 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 modelthe payment model).

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):
  • 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):
  • true—additional attempt is available.
  • false—additional attempt is not available.
140-50 140

method
string, optional

Payment method code (details).

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).

Example: eea

140-80 140

status
string, required

Payment status (according to the payment modelthe payment model).

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), in seconds.

Example: 360

140-110 140

type  
string, required

Payment type (according to the payment modelthe payment model).

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 payment system or a provider. 160

recurring
object, optional

Object with a COF purchase data (details) 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) 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) 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):
  • 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):
  • COneClick 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).

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). 190

Callback parameters for tokens

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