Callbacks

When a payment is completed Gate sends you a callback that contains information about the last operation during the payment processing. The format of the callback can be customised according to your preferences.

Method

Callback is a HTTP POST request in JSON format sent to your system (to the provided URL) after processing the payment.

Callbacks are signed, for more information, see Signature generation and verification.

Conditions for sending callbacks

Payment Page sends callbacks in the following cases:

  • for further processing of payment after the customer authentication in the 3-D Secure program (in some cases when an external provider declines the payment processing but when it is possible to try again, you may receive several callbacks for the payment with the status awaiting 3ds result or awaiting redirect result at this step; for more information, refer to your Key Account Manager);
  • the operation on the side Payment Page has finished processing;
  • a token was generated for the bank card.

Callback delivery

Callbacks are sent immediately after an operation was performed.

Gate records the fact of callback delivery to your system after receiving the response from your system. The response must contain HTTP header with code 200 OK.

If it is necessary you can delay the callback sending by passing the delay parameter in the callback object in the payment request with the value in seconds. The maximum delay value is 600 sec.

If the callback was not delivered it is resent according to the following schedule:

  • 6 times with the 10 sec. period;
  • then the period is increased in accordance with the formula 70 + 10·1,12n-4, where n is the serial number of the attempt, until the period does not exceed 4 hours;
  • after that, every 4 hours until the maximum number of attempts is achieved.

Gate performs at maximum 120 attempts to deliver a callback within 11 days.

Callback delivery addresses

Callbacks are sent to URLs that are unique for each project. You can provide the same or different URLs to send callbacks about successful and unsuccessful requests.

For the IP addresses the payment platform will use to send you callbacks, refer to the ECommPay support service.

Callback processing

When processing callbacks, your system must adhere to the following guidelines:

  1. Accept callbacks only from the IP address received from the ECommPay support service.
  2. On a successfully received callback your system must respond with HTTP 200 OK.
  3. If a callback was not received your system must respond with HTTP 400 Bad Request (for example, if you were unable to convert a parameter string to an array) or HTTP 500 Internal Server Error (for example, if a callback was sent to the wrong URL).
  4. If a callback has been already received by your system, your system must ignore the callback.
  5. For reminders that were not previously received, your system must try to accept the callback again.
  6. Your system should not limit the delivery time for callbacks, because deliveries can occur with delays.

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 by email support@ecommpay.com.

Attention: The callback signature is generated with all the parameters of the callback used in your project.

The minimal sets of parameters in callbacks that Gate sends after payment processing and after token generation are specified in the tables below.

* Object or parameter sent in the default set of a callback.

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 ECommPay. 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 Overview. Possible values for mobile operators:
  • mBEELINE
  • mMEGAFON
  • mMTS
  • mTELE2
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, optional
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, optional
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

installment_count
integer, optional

The number of months of installment payment. For more information, see Payment installment

Example: 2

70-110 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 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 ECommPay
  • 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. 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 Information of operations performing 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 in Gate 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 in Gate 130-50 130

message
string, optional

Unified message from the payment provider. For the list of the codes, see Information of operations performing 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
integer, optional

CRC32 ID of the external provider gate. 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 in Gate 130-80 130

status
string, required

The operation status 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—cannot retry the 3D-Secure authentication.
140-10 140

date
string, optional
default

Date and time of the last payment status update in .

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

OperationFee
object, optional

The object that contains the information about per- operation fee charged by ECommPay 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 in Gate 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 recurring payment 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

Recurring payment currency ISO 4217 alpha-3.

Example: USD

170-10 170

id
integer, optional
default

Recurring payment ID. 170-20 170

register_payment_id
string, optional

Recurring payment ID on merchant side 170-30 170

status
string, optional

Recurring payment status. Possible values:
  • active—recurring payment is active.
  • canceled—recurring payment is cancelled.
170-40 170

type
string, optional

Recurring payment type. Possible values:
  • R—recurring payment
  • U—autopayment
  • C payment
170-50 170

valid_thru
string, optional
default

Expiration date of the recurring payment ID 170-60 170

redirect_data
object, optional

The object that contains the data for redirecting customer to a different payment method to complete the payment. 180

body
object, optional

The set of parameters with the data for redirection. 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