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,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 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) orHTTP 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.
Parameter | Description | tree |
---|---|---|
account |
The object that contains the details of the customer bank card or other payment account | 10 |
card_holder |
Card holder name | 10-10 10 |
expiry_month |
Card expiration month | 10-20 10 |
expiry_year |
Card expiration year | 10-30 10 |
id |
ID of saved card in Gate | 10-40 10 |
number |
Masked bank card or other account number. Example: |
10-50 10 |
token |
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 |
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:
|
10-70 10 |
acs |
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 |
URL of the issuing bank ACS page. | 20-10 20 |
md |
Merchant technical data in the payment system. | 20-20 20 |
pa_req |
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 |
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 |
Postcode of the customer address. | 30-10 30 |
avs_street_address |
Customer address | 30-20 30 |
avs_result |
Result of the Address Verification Service (AVS) matching. For more information, see Checking with Address Verification Service | 40 |
bank |
The object that contains the data about a card issuer bank. | 50 |
name |
The name of the card issuer bank. | 50-10 50 |
customer |
The object that contains information about the customer who initiated the payment. | 70 |
billing |
The object that contains information about the billing address of the customer. | 70-10 70 |
address |
Street address of the customer billing address. | 70-10-10 70-10 |
city |
City of the customer billing address. | 70-10-20 70-10 |
country |
Country of the customer billing address, in ISO 3166-1 alpha-2 format. Example: |
70-10-30 70-10 |
postal |
Postcode of the customer billing address. | 70-10-40 70-10 |
region |
Region of the customer billing address. | 70-10-50 70-10 |
city |
Customer city | 70-20 70 |
country |
Country of the customer | 70-30 70 |
day_of_birth |
Birth date of the customer in the DD-MM-YYYY format. | 70-40 70 |
first_name |
Customer first name | 70-50 70 |
id |
Unique ID of the customer in your project. | 70-60 70 |
ip_address |
Customer IP address as specified in the initial request. | 70-70 70 |
last_name |
Customer last name | 70-80 70 |
middle_name |
Customer middle name | 70-90 70 |
phone |
Customer phone number. From 4 to 24 digits | 70-100 70 |
decision |
A string that contains the Risk Control System decision related to the payment. | 80 |
decision_message |
The array of strings with the messages from the Risk Control System related to the decision regarding the payment. Example: |
90 |
display_data |
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 |
The object that contains information about a single error. | 110-10 110 |
code |
Error code | 110-10-10 110-10 |
description |
The description of the error cause. | 110-10-10 110-10 |
field |
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 |
Message that explains the cause of the error. | 110-10-30 110-10 |
interface_type |
Object that contains the information about the source the payment request originates from. | 120 |
id |
Parameter that specifies the interface the payment request originates from. Possible values:
|
120-10 120 |
user |
Parameter that specifies the Dashboard user that initiated the payment request. | 120-20 120 |
operation |
The object that contains information about the operation that triggered the callback | 130 |
code |
Unified payment provider response code. For the list of the codes, see Information of operations performing | 130-10 130 |
created_date |
Date and time the operation was created. Example: |
130-20 130 |
date |
Date and time the payment status was last updated | 130-30 130 |
eci |
The indicator that shows the result of the 3‑D Secure customer authentication. For more information, see Electronic Commerce Indicators | 130-40 130 |
id |
Unique ID of the operation | 130-50 130 |
message |
Unified message from the payment provider. For the list of the codes, see Information of operations performing | 130-60 130 |
provider |
The object that contains external provider information about the result of the operation. | 130-70 130 |
auth_code |
Authorization code received from an external provider. | 130-70-10 130-70 |
date |
The date and time the payment provider finished processing the payment. | 130-70-20 130-70 |
endpoint_id |
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 |
The payment provider that has been used to process the operation. | 130-70-40 130-70 |
payment_id |
Unique ID of the payment in the provider system. | 130-70-50 130-70 |
request_id |
Unique ID of the last request related to the operation | 130-80 130 |
status |
The operation status | 130-90 130 |
sum_converted |
The object that contains the currency of the payment provider account and the initial amount denominated in this currency | 130-100 130 |
amount |
The amount in minor units of the payment provider currency | 130-100-10 130-100 |
currency |
The currency of the payment provider account in ISO 4217 alpha-3 format. Example: |
130-100-20 130-100 |
sum_initial |
The object that contains the amount and currency of the operation as specified in the initial request. | 130-110 130 |
amount |
The operation amount as specified in the initial request in minor units of the currency. | 130-110-10 130-110 |
currency |
Payment currency in ISO 4217 alpha-3 format as specified in the initial request. Example: |
130-110-20 130-110 |
type |
The operation type | 130-120 130 |
payment |
The object that contains the payment data | 140 |
cascading_with_redirect |
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.
|
140-10 140 |
date |
Date and time of the last payment status update Example: |
140-20 140 |
description |
The description of the payment as specified in the initial request | 140-30 140 |
id |
Unique ID of the payment in your web service | 140-40 140 |
is_new_attempts_available |
The indicator that shows if the customer can retry the payment.
|
140-50 140 |
method |
Payment method Example: |
140-60 140 |
merchant_refund_id |
Unique identifier of a refund in the merchant system Example: |
140-61 140 |
OperationFee |
The object that contains the information about per- operation fee charged by ecommpay | 140-70 140 |
amount |
Amount of per-operation fee specified in minor units of the fee currency | 140-70-10 140-70 |
currency |
Currency of the operation fee, in ISO 4217 alpha-3 format. Example: |
140-70-20 140-70 |
sum_with_surcharge |
Total amount of the operation surcharge and operation amount specified in minor currency units | 140-70-30 140-70 |
surcharge_amount |
Amount of the operation surcharge specified in minor currency units | 140-70-40 140-70 |
surcharge_currency |
Currency of the operation surcharge, in ISO 4217 alpha-3 format. Example: |
140-70-50 140-70 |
region |
The region of the country where the card operation is processed. | 140-80 140 |
status |
Payment status. Example: |
140-90 140 |
sum |
The object that contains the information about payment amount, including refunds, and the currency as specified in the initial request | 140-100 140 |
amount |
Payment amount, including refunds, in minor currency units | 140-100-10 140-100 |
currency |
Payment currency in ISO 4217 alpha-3 format as specified in the initial request. Example: |
140-100-20 140-100 |
timeout_attempts |
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 |
Payment type. Example: |
140-120 140 |
project_id |
The unique ID of your project | 150 |
provider_extra_fields |
The object that contains the data from the payment provider that are required to complete the payment or to compile reports. | 160 |
recurring |
The object that contains COF purchase registration data. The data are submitted, if the initial request for payment includes the recurring_register=1 |
170 |
currency |
COF purchase currency ISO 4217 alpha-3. Example: |
170-10 170 |
id |
COF payment ID. | 170-20 170 |
register_payment_id |
COF payment ID on merchant side | 170-30 170 |
status |
COF purchase status. Possible values:
|
170-40 170 |
type |
COF purchase type. Possible values:
|
170-50 170 |
valid_thru |
Expiration date of the COF purchase ID | 170-60 170 |
redirect_data |
The object that contains the data for redirecting customer to a different payment method to complete the payment. | 180 |
body |
The set of parameters with the data for redirection. | 180-10 180 |
method |
Request submission method: POST or GET . |
180-20 180 |
url |
The redirection URL. | 180-30 180 |
signature |
Callback signature. For more information, see | 190 |
Parameter | Description | tree |
---|---|---|
general |
The object with the general request data. | 1 |
project_id |
The unique identifier of your project. Example: |
1-11 |
customer_id |
The unique identifier of the customer in your project. | 1-21 |
signature |
Callback signature | 1-31 |
request |
The object with the request data | 2 |
id |
Unique identifier of the request Example: |
2-12 |
action |
Type of the request. The following options are available:
|
2-22 |
status |
The request status. The following options are available:
|
2-32 |
errors |
Array of error messages. | 2-42 |
ErrorItem |
The object with information about a single error. | 2-4-12-4 |
code |
Error code. Example: |
2-4-1-12-4-1 |
message |
A message that clarifies the error cause. Example: |
2-4-1-22-4-1 |
field |
The parameter in which the error occurred if it was defined | 2-4-1-32-4-1 |
token |
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 |
The date and time the token was generated. Example: |
4 |
token_status |
Token status. Example: |
5 |