Callbacks

When a payment is completed Gate sends you a callback, that contains information about the last transaction when the payment was made. 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

Gate 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 Gate 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,12^n-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 same or different URLs to send callbacks about successful and unsuccessful requests or about different operation types results.

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 follow the following guidelines:

Accept callbacks only from the IP address received from the ecommpay support service.
On a successfully received callback your system must respond with HTTP 200 OK.
If a callback has been already received by your system, your system must respond with HTTP 200 OK also.
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).
For reminders that were not previously received, your system must try to accept the callback again.
Your system should not limit the delivery time for callbacks, because deliveries can occur with delays.

Callback parameters

The set of parameters passed in callbacks may differ depending on the operation type and callback settings. The following is the list of parameters that can be sent in standard callbacks. Objects and parameters included in standard callbacks by default are marked as such.

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

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
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	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 Indicators	130-40 130
id integer, optional	Unique ID of the operation	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 string*, optional	CRC32 ID of the external provider gate. * In some cases, because of payment system or provider requirements, the type of this parameter may be integer.	130-70-30 130-70
id integer, optional	The payment provider that has been used to process the operation.	130-70-40 130-70
payment_id string, optional	Unique ID of the payment in the provider system.	130-70-50 130-70
request_id string, required	Unique ID of the last request related to the operation	130-80 130
status string, required	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 Example: `2017-07-27T15:19:13+0000`	140-20 140
description string, optional default	The description of the payment as specified in the initial request	140-30 140
id string, required default	Unique ID of the payment in your web service	140-40 140
is_new_attempts_available boolean, optional	The indicator that shows if the customer can retry the payment. `true`—customer can retry the payment `false`—customer cannot retry the payment This parameter is issued, if the "Try Again" functionality is enabled in Payment Page	140-50 140
method string, optional default	Payment method Example: `card`	140-60 140
merchant_refund_id string, optional	Unique identifier of a refund in the merchant system Example: `refund_1`	140-61 140
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	150
provider_extra_fields object, optional default	The object that contains the data from the payment provider that are required to complete the payment or to compile reports.	160
recurring object, optional default	The object that contains COF purchase registration data. The data are submitted, if the initial request for payment includes the recurring_register=1 line and the payment is successful.	170
currency string, optional default	COF purchase currency ISO 4217 alpha-3. Example: `USD`	170-10 170
id integer, optional default	COF payment ID.	170-20 170
register_payment_id string, optional	COF payment ID on merchant side	170-30 170
status string, optional	COF purchase status. Possible values: `active`—COF purchase is active. `canceled`—COF purchase is cancelled.	170-40 170
type string, optional	COF purchase type. Possible values: `R`—COF purchase `U`—autopayment `C`— payment	170-50 170
valid_thru string, optional default	Expiration date of the COF purchase ID	170-60 170
redirect_data object, optional	The object that contains the data for redirecting customer to 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	190

Table 2. Callback objects and parameters related to token creation or revoke
Parameter	Description	tree
general object, required	The object with the general request data.	1
project_id string, required	The unique identifier of your project. Example: `42`.	1-11
customer_id string, optional	The unique identifier of the customer in your project.	1-21
signature string, required	Callback signature	1-31
request object, required	The object with the request data	2
id integer, required	Unique identifier of the request Example: `3718000054`	2-12
action string, optional	Type of the request. The following options are available: `tokenize`—token creation request `token_revoke`—token revoke request parameter is missing from callback — token is expired and deactivated. The platform initiates a callback with missing action automatically, immediately after the token expires. Such callback is not issued in response to a request.	2-22
status string, required	The request status. The following options are available: `success`—request successfully completed `error`—error(s) encountered when processing request. The error details are passed in the errors array.	2-32
errors array, optional	Array of error messages.	2-42
ErrorItem object, required	The object with information about a single error.	2-4-12-4
code string, optional	Error code. Example: `10309`.	2-4-1-12-4-1
message string, optional	A message that clarifies the error cause. Example: `Attempt to make COF purchase without registered recurrent payments.`	2-4-1-22-4-1
field string, optional	The parameter in which the error occurred if it was defined	2-4-1-32-4-1
token string, optional	Token of the customer bank card. The token is generated automatically when a successful payment is performed if the appropriate option is enabled.	3
token_created_at string, optional	The date and time the token was generated. Example: `2017-07-21T03:31:24+0000`	4
token_status string, optional	Token status. Example: `active`	5