Checkout Integration

Version: 6.6.2
Released: 2025/02/26

Introduction

This document describes the Checkout integration procedures between Checkout service and the website for e-commerce merchants.
To make your integration easier, please download collection and try it out:
Postman Collection

General Information

Checkout service is a fast and easy way to create a secure payment page. It allows collecting and submitting payments and sending them for processing.

To use the Checkout service on the site you have to perform integration. Checkout integration provides a set of APIs that allow customizing payment processing for the business. These protocols implement acquiring payments (purchases) using specific API interaction with the merchant websites.

The API requires request data as json string data and responds also with json string data.

⚠️ Pay attention

Checkout protocol requires requests to be sent using JSON formatting with the following content type:
Header: Content-Type: application/json

Checkout process

Checkout payment flow is shown below. When a Customer wants to make a purchase on your site the following happens:

Customer places an order and initiates payment on the site.
Site confirms the order and sends the payment processing request to the Checkout system with information about the order, payment and hash.
Checkout system validates the request and sends to the site the response with the redirect link.
The site redirects the Customer on the Checkout page by redirect link.
Customer selects the payment method, enters the payment data and confirms the payment. The payment method will be specifying automatically If only one method is available.
The payment processes at Payment Gateway.
Payment Gateway sends a callback to the site with the payment result.
The payment result is shown to the Customer.

The payment could be declined in case of invalid data detection.

Protocol Mapping

It is necessary to check the existence of the protocol mapping before using the Checkout integration. Merchants can’t make payments if the CHECKOUT protocol is not mapped.

Customer return after payment

After completing the payment, the payer will be returned to the URL specified in the Authentication request in the "success_url" and "cancel_url" parameters. If you need to get additional parameters in the return URLs, you should configure it in the Protocol Mappings modules by enabling the "Return parameters" attribute. In that case, "success_url" and "cancel_url" will contain the following data:

Parameter	Description
`payment_id`	Payment ID Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`trans_id`	Transaction ID Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`order_id`	Order ID Example: order-1234
`hash`	Special signature, used to validate data. Addition in Signature section. Must be SHA1 of MD5 encoded string (uppercased): payment_public_id + order.number + order.amount + order.currency + order.description + merchant.pass

⚠️ Pay attention

that for "cancel_url", the payer's return to the merchant with parameters is possible only after the decline has happened and the payer has closed the payment form (not the browser tab). If the payer closes the payment form without initiating the payment (pressing the PAY button), the redirection to "cancel_url" occurs without passing additional parameters.

DMS mode

If you need to use Checkout integration to work with payments in DMS-mode (two-step payments), you should set the corresponding MID configuration in the admin panel. Specify DMS-mode for the MID attribute. In this case, the payment request will be processed as an authorization stage for DMS-mode. The capture requests will be generated and gathered in the queue. You could monitor and manage the capture request queue via the admin panel as well. For detailed information, please contact your administrator.

Checkout page description

Checkout page is shown to the Customer after a payment initiation. There are the fields to enter the payment data.

Fields and Validation

The list of the fields on the Checkout page depends on the request parameters and the specified payment method.

Your customers will not see the fields if the acquirer does not need the information that is transmitted in them. For example, if an alternative payment method is specified, the card data is not displayed on the Checkout page.

As well, pay attention to the conditional fields such as e-mail or billing address. If the e-mail and billing address (data object) parameters are specified in the request, the Checkout page will not contain them.

Additional fields can also be displayed if a payment method is selected that requests additional data from the Customer.

The Checkout page has the fields validation. In case of the invalid data the error message will be shown and the field will be highlighted.

The list of the general fields and possible errors on the Checkout page is below:

Fields	Type	Limitations	Error
`Card number`	Integral	Lun algorithm, length 14-19 numbers	Invalid card number
`Expirу Date`	Date	2-2 numbers (in the format mm-yy), after today's date	The expiration date of card is expired and not valid.
`Security code`	Integral	Up to 4 characters	Invalid security code
`Name on card`	String	Up to 32 characters	The name on card field Must contain at least 2 words: first name and last name. Allowed special characters: hyphens, apostrophes, diacritics
`Country`	List	2-letters code	Country is required. Please enter a valid Country
`State/Region`	String List - for USA, Canada, Australia, Japan, India
`City`	String	Up to 32 characters	City is required. Please enter a valid City
`Address line`	String	Up to 32 characters	Address line is required. Please enter a valid Address line
`Zip code`	String	Up to 32 characters	Zip code is required. Please enter a valid Zip code
`Phone number`	String	Up to 32 characters	Phone number is required. Please enter a valid Phone number

Pre-routing

To make payment method choice easier for the Customer, pre-routing is provided on the Checkout.

The functionality allows you to set up matches in the admin panel via the Custom routing module, which will determine the list of payment methods suitable for the current payment.

This way, you can restrict your Customers from randomly choosing a payment method that is not available in their region, for example. This will help you to increase the number of successful payments and reduce the risk of declined transactions.

Note that if the Authentication request contains a list of the payment methods in the methods array, then the pre-routing configurations will be ignored.

Card data tokenization

For regular customers, we have made the payment page even more convenient and simple.

You can save the customer's card data so that they can reuse it for future payments.

To do this, you need to send the req_token = true parameter in the Authentication request. And then, in the callback, you will receive a card token.

Use the token when sending the next Authentication request and your client will see anonymized card details on the payment form, which will greatly simplify the payment process.

Web information

Checkout service gathers information about browser, which the Customer uses.

When the Customer is on the Checkout page, the service gets the data about the Customer's OS, browser, and browser language. That information is sent to the acquirer in some cases.

iFrame option

You can use iFrame option to show Checkout page on your domain. All you need is just to past in the code redirect url received in the response to the Authentication request.

Please follow the example:

<iframe src=redirect_url height="600" width="300"></iframe>

Note that screen size can be adjusted according to your requirements.

Important: cross-domain requests are prohibited by security policy of our service.

⚠️ Pay attention

By adding our Checkout Payment Page to the iframe on your site, ensure you ALLOW ACCESS TO COOKIE STORAGE.
This is required to avoid issues when redirecting the payer back to your site, such as after 3DS authentication. If you prohibit the storage of third-party data in your cookies, you will prevent the identification of the payer after returning from 3DS. This can cause interruptions in the payment session.

Page Customization

The administration service provides the ability to stylize the Checkout page in accordance with the preferences of the merchant. The action is available for the authorized users only. To customize the payment page you need:

Click the “Configuration → Branding” item on the menu bar. The settings are displayed in the work area.
Select a page template to make changes.
Change the settings:
1. login icon selection;
2. color selection for the following items:
  1. heading;
  2. background;
  3. buttons;
Click the “Submit” button to apply the settings. The selected settings will be displayed to the Customers on the Checkout page.

Authentication request parameters

The merchant submits an authorization request and as a result of successful response receives the redirect_url - link on the Checkout page.

/api/v1/session

The authentication performs when the payment is initiated.

You need to send an authentication POST request in JSON format on Checkout form URL (CHECKOUT_URL) to start checkout process for the Customers. As a result of the authentication request you will receive the following:

An authentication session is created with a unique identifier (Session ID). The session expires after one hour.
A link is generated to redirect to the Checkout page: one link corresponds to one payment. The link becomes invalid after a successful payment. The authentication request parameters are below.

If DMS-mode (two-stages payment) is available, after successful authentication it is necessary to capture. The capture would be performed automatically according to the settings or you can do it manually in the admin portal.

Request Parameters

Parameter	Type	Mandatory, Limitations	Description
`merchant_key`	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
`operation`	String	Required	Defines a payment transaction Possible values: purchase, debit, transfer Send the “purchase” value so that the payment page for sale initiation will be shown to the customer. Send the “debit” value so that the payment page for debit initiation will be shown to the customer. Send the “transfer” value so that the payment page for transfer initiation will be shown to the customer. Example: purchase
`methods`	Array	Optional	An array of payment methods. Limits the available methods on the Checkout page (the list of the possible values in the Payment methods section). In the case of parameter absence, the pre-routing rules are applied. If pre-routing rules are not configured, all available payment methods are displayed. Condition: for purchase operation only For purchase and debit operations. Example: card, paypal, googlepay
`channel_id`	String	Optional max: 16	This parameter is used to direct payments to a specific sub-account (channel). If the channel is configured for Merchant Mapping, the system matches the value with the corresponding `channel_id` value in the request to route the payment. Note: The channel must correspond to one of the payment `methods` (brands) listed in the `methods` array. If the methods array is empty, only the `channel_id` will affect the selection of the payment method (Merchant Mapping).
`session_expiry`	Integer	Optional Values from 1 to 720 min	Session expiration time in minutes. Default value = 60. Could not be zero. Example: 60
`success_url`	String	Required Valid URL max: 1024	URL to redirect the Customer in case of the successful payment Example: https://example.domain.com/success The return of additional parameters can be configured for success_url. See the “Customer return after payment” section for details.
`cancel_url`	String	Optional Valid URL min: 0 max: 1024	URL to return Customer in case of a payment cancellation (“Close” button on the Checkout page). The logic of redirection on “cancel_url” could be configured in the admin panel (Configuration -> Protocol Mappings section): use the “Maximum count declines” field to set the payment failed attempts quantity before redirection. For example, if the field value is set to "1", then after the first declined attempt, a payer will be redirected to "cancel_url." Example: https://example.domain.com/cancel The return of additional parameters can be configured for cancel_url. See the “Customer return after payment” section for details.
`expiry_url`	String	Optional Valid URL min: 0 max: 1024	URL where the payer will be redirected in case of session expiration Example: https://example.domain.com/expiry
`error_url`	String	Optional Valid URL min: 0 max: 1024	URL to return Customer in case of undefined transaction status. If the URL is not specified, the cancel_url is used for redirection. Example: https://example.domain.com/errorurl
`url_target`	String	Optional Possible values: `_self`, `_parent`, `_top`. Find the result of applying the values in the HTML standard description (Browsing context names)	Name of, or keyword for a browsing context where Customer should be returned according to HTML specification. Example: _parent
`req_token`	Boolean	Optional default - false	Special attribute pointing for further tokenization If the `card_token` is specified, `req_token` will be ignored. For purchase and debit operations. Example: false
`card_token`	Array of Strings	Optional String 64 characters	Credit card token value For purchase and debit operations. Example: f5d6a0ab6fcfb6487a39e2256e50fff3c95aaa97
`recurring_init`	Boolean	Optional default - false	Initialization of the transaction with possible following recurring Only for purchase operation Example: true
`schedule_id`	String	Optional It s available when recurring_init = true	Schedule ID for recurring payments Only for purchase operation Example: 57fddecf-17b9-4d38-9320-a670f0c29ec0
`vat_calc`	Boolean	Conditional true or false default - false	Indicates the need of calculation for the VAT amount • 'true' - if VAT calculation needed • 'false' - if VAT should not be calculated for current payment. Only for purchase operation Example: false
`hash`	String	Required	Special signature to validate your request to Payment Platform Addition in Signature section. Example: Must be SHA1 of MD5 encoded string (uppercased): order_number + order_amount + order_currency + order_description + password
order	Object	Required	Information about an order
`number`	String	Required max: 255 [a-z A-Z 0-9 -!"#$%&'()*+,./:;&@]	Order ID Example: order-1234
`amount`	String	Required Greater then 0 [0-9] max: 255	Format depends on currency. Send Integer type value for currencies with zero-exponent. Example: 1000 Send Float type value for currencies with exponents 2, 3, 4. Format for 2-exponent currencies: XX.XX Example: 100.99 Pay attention that currencies 'UGX', 'JPY', 'KRW', 'CLP' must be send in the format XX.XX, with the zeros after comma. Example: 100.00 Format for 3-exponent currencies: XXX.XXX Example: 100.999. Format for 4-exponent currencies: XXX.XXXX Example: 100.9999 ⚠️ Note! For crypto currencies use the exponent as appropriate for the specific currency. For purchase operation with crypto: Do not send parameter at all if you want to create a transaction with an unknown amount - for cases when the amount is set by the payer outside the merchant site (for example, in an app). As well, you have to omit "amount" parameter for hash calculation for such cases. For transfer operation: Send amount if you want to show default value in the amount field on the Checkout. The customers can change the value manually on the payment form.Send "-1" value if you want to show empty amount field on the Checkout so that the Customers could enter the value manually.
`currency`	String	Required 3 characters for fiat currencies and from 3 to 6 characters for crypto currencies [A-Z] ISO 4217	Currency Example (fiat): USD Example (crypto): USDT
`description`	String	Required min: 2 max: 1024 [a-z A-Z 0-9 !"#$%&'()*+,./:;&@]	Product name Example: Very important gift - # 9
customer	Object	Conditional	Customer's information. Send an object if a payment method needs
`name`	String	Conditional min: 2 max: 32 Latin basic [a-z A-Z]	Customer's name Condition: If the parameter is NOT specified in the request, then it will be displayed on the Checkout page (if a payment method needs) - the "Cardholder" field Example: John Doe
`email`	String	Conditional min: 2 max: 255 email format	Customer's email address Condition: If the parameter is NOT specified in the request, then it will be displayed on the Checkout page (if a payment method needs) - the "E-mail" field Example: example@mail.com(url)
`birth_date`	String	Conditional format: yyyy-mm-dd ISO 8601	Payer's birth date Example: 1970-02-17
billing_address	Object	Conditional	Billing address information. Condition: If the object or some object's parameters are NOT specified in the request, then it will be displayed on the Checkout page (if a payment method needs)
`country`	String	Conditional 2 characters (alpha-2 code) ISO 3166-1	Billing country Example: US
`state`	String	Optional min: 2 max: 32 [a-z A-Z] It is 2-letters code for USA, Canada, Australia, Japan, India	Billing state address Example: CA
`city`	String	Conditional min: 2 max: 40 [a-z A-Z]	Billing city Example: Los Angeles
`district`	String	Optional min: 2 max: 32 [a-z A-Z 0-9 - space]	City district Example: Beverlywood
`address`	String	Conditional min: 2 max: 32 [a-z A-Z 0-9]	Billing address Example: Moor Building
`house_number`	String	Optional min: 1 max: 9 [a-z A-Z 0-9/ - space]	House number Example: 17/2
`zip`	String	Conditional min: 2 max: 10 [a-z A-Z 0-9]	Billing zip code Example: 123456, MK77
`phone`	String	Conditional min: 1 max: 32 [0-9 + () -]	Customer phone number Example: 347771112233
payee	Object	Conditional	Payee's information. Specify additional information about Payee for transfer operation if it is required by payment provider.
`name`	String	Required min: 2 max: 32 Latin basic [a-z A-Z]	Customer's name. Example: John Doe
`email`	String	Conditional email format	Customer's email address. Example: example@mail.com
payee_billing_address	Object	Conditional	Billing address information for Payee.
`country`	String	Conditional 2 characters (alpha-2 code) ISO 3166-1	Billing country Example: US
`state`	String	Optional min: 2 max: 32 [a-z A-Z] It is 2-letters code for USA, Canada, Australia, Japan, India	Billing state address Example: CA
`city`	String	Conditional min: 2 max: 40 [a-z A-Z]	Billing city Example: Los Angeles
`district`	String	Optional min: 2 max: 32 [a-z A-Z 0-9 - space]	City district Example: Beverlywood
`address`	String	Conditional min: 2 max: 32 [a-z A-Z 0-9]	Billing address Example: Moor Building
`house_number`	String	Optional min: 1 max: 9 [a-z A-Z 0-9/ - space]	House number Example: 17/2
`zip`	String	Conditional min: 2 max: 10 [a-z A-Z 0-9]	Billing zip code Example: 123456, MK77
`phone`	String	Conditional min: 1 max: 32 [0-9 + () -]	Customer phone number Example: 347771112233
crypto	Object	Optional	Additional information regarding crypto transactions
`network`	String	Optional max: 50	You can use an arbitrary value or select one from the following. Example: • ERC20 • TRC20 • BEP20 • BEP2 • OMNI • solana • polygon
parameters	Object	Optional	Extra-parameters required for specific payment method Example: `"parameters": { "payment_method": { "param1":"val1", "param2":"val2" } }`
custom_data	Object	Optional	Custom data This block can contain arbitrary data, which will be returned in the callback. Example: `“custom_data”: {“param1”:”value1”, “param2”:”value2”, “param3”:”value3”}`

Authentication (OK)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchant_key": "xxxxx-xxxxx-xxxxx",
  "operation": "purchase",
  "methods": [
    "card",
    "method1"
  ],
  "parameters": {
    "card": {
      "param1": "val-1",
      "param2": "val-2"
    },
    "method1": {
      "param1": "val-3",
      "param2": "val-4"
    }
  },
  "session_expiry": 60,
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "USD",
    "description": "Important gift"
  },
  "cancel_url": "https://example.domain.com/cancel",
  "success_url": "https://example.domain.com/success",
  "expiry_url": "https://example.domain.com/expiry",
  "url_target": "_blank",
  "customer": {
    "name": "John Doe",
    "email": "test@gmail.com"
  },
  "billing_address": {
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "district": "Beverlywood",
    "address": "Moor Building 35274",
    "house_number": "17/2",
    "zip": "123456",
    "phone": "347771112233"
  },
  "card_token": [
    "f5d6a0ab6fcfb6487a39e2256e50fff3c95aaa97075ee5e539bb662fceff4dc1"
  ],
  "req_token": true,
  "recurring_init": true,
  "schedule_id": "9d0f5cc4-f07b-11ec-abf4-0242ac120006",
  "hash": "{{session_hash}}"
}
'

Debit Operation (OK)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \
--header 'Content-Type: application/json' \
--data-raw '{
  "merchant_key": "xxxxx-xxxxx-xxxxx",
  "operation": "debit",
  "methods": [
    "card"
  ],
  "parameters": {
    "card": {
      "param1": "val-1",
      "param2": "val-2"
    },
    "session_expiry": 60,
    "order": {
      "number": "order-1234",
      "amount": "0.19",
      "currency": "USD",
      "description": "Important gift"
    },
    "cancel_url": "https://example.domain.com/cancel",
    "success_url": "https://example.domain.com/success",
    "expiry_url": "https://example.domain.com/expiry",
    "url_target": "_blank",
    "customer": {
      "name": "John Doe",
      "email": "test@gmail.com"
    },
    "billing_address": {
      "country": "US",
      "state": "CA",
      "city": "Los Angeles",
      "district": "Beverlywood",
      "address": "Moor Building 35274",
      "house_number": "17/2",
      "zip": "123456",
      "phone": "347771112233"
    },
    "card_token": [
      "f5d6a0ab6fcfb6487a39e2256e50fff3c95aaa97075ee5e539bb662fceff4dc1"
    ],
    "req_token": true,
    "hash": "{{session_hash}}"
  }
}
'

Transfer Operation (OK)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \
--header 'Content-Type: application/json' \
--data-raw '{  
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "operation":"transfer",
   "order":{
      "number":"order-1234",
      "amount": "100.55",
      "currency":"USD",
      "description":"Important gift"
   },
   "cancel_url":"https://example.com/cancel",
   "success_url":"https://example.com/success",
   "customer":{
        "name":"John Doe",
        "email":"success@gmail.com"
    },
    "payee": {
        "name":"John Doe",
        "email":"success@gmail.com"
        },
    "billing_address":{
        "country":"US",
        "state":"California",
        "city":"Los Angeles",
        "address":"Moor Building 35274 State ST Fremont. U.S.A",
        "zip":"94538",
        "phone":"0987654321",
        "district":"Brentwood",
        "house_number":"123"
    },
    "payee_billing_address":{
        "country":"US",
        "state":"New York",
        "city":"New York",
        "address":"Moor Building 35274 State ST Fremont. U.S.A",
        "zip":"94538",
        "phone":"0987654321",
        "district":"Brentwood",
        "house_number":"123"
    },
   "hash":"{{session_hash}}"
}
'

Example Response (OK)

{
  "redirect_url": "{{CHECKOUT_HOST}/auth/ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOaUo5LmV5SnBZWFFpT2pFMU9UWXhPRFl6T0Rnc0ltcDBhU0k2SWpGbE5qTTNObVZoTFdRek1HUXRNVEZsWVMxaE16QXlMVEF5TkRKak1HRTRNekF4TWlJc0ltVjRjQ0k2TVRVNU5qRTRPVGs0T0gwLm9CMmVhdlRtTU5DMXFTajlDVFlqQ0dOMDlHdUs1NXRkQTVpWFR3d2F2cWR0cEpEU2NRWWFaT3Z5dmJSVjJUSFNUVlFlS0NUX3pRdFNycDlKS1M4X0pqUzRMclM5MnUyNXRfSHNGa1FUQ0VOdGtadHQtaGxONERYdVhkLTU5cEhKLUN1RXBqSmZ4UDZEQXhFaVAxWEpRZDlyQldNa1RQVDdGZm1ac0g4LTM5YnV6LTI3MWxKMndkekdvSGJYa0NKVnNTNFJldGxrbno2U3dGd3ZFMW5KNDhwYTBGMDNLWjBpNnhpRFVPR3p2U0ZKdGZfMndDTTdzTTdsemc1TlBmSDl0Q0RKQmZEaG1hUmJCRmR6RlZMZlJncG5tMzB3VWpTMGMxbmt6SkkxOGJTd2Z6Z0hfZFpnc1cyUFhCM2ZLdG9pWDJXeFRsQzlxR204QTRYVm9EQy1mOWxvRHlMd0F5eV9xY3JrWmNuQTJVSjk5Zl91c0cwODZKUlBTT0I4VHVRZndSTzUxSEN2bEU2TXdFYzVYRmtnYjBleEZRcXdpNGE4S2RlWV9HX3ZQam42bnpZODdtVzFINlpQMjJ0dzVzazYtUENMeHdvNXctUmFBWC1mYVVhcEVHTzFLZkVHbndaQWZBZVNyc3U4MV9XQUFJMlN5RUxGWi1IU1lXMUZLWFgybzNNeF93Ty1DS3FLTWZsUTV1cGc2eDAybzhsbFhoeGJlVmVIOWlkMHgzYldRWE9vWk5hWm1MeVpJMmJsT2dtVDV0cHR4NHNQNDNqT0NtYW1sdkxyUkZvQmxCNTJ4V0RUQTBZQnhBLW5meUxCRHRJN0dPaVRWQjJ5cWd1Z1lBdGRfbWFQN2x2YTJpbVJWaHhxT0R5SlRiZThxcDdhWkw4bkJvTHZocnZDOHlv"
}

Authentication request possible errors

Parameter Values Validation

Checkout service validates the request parameters and sends the error responses in case of an invalid data detection.

Example Request - Validation (bad)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \
--header 'Content-Type: application/json' \
--data-raw '{  
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "operation":"credit",
   "methods":[ "" ],
   "order":{
      "number":"",
      "amount": "1.2",
      "currency":"Dollar",
      "description":""
   },
   "cancel_url":"1.com",
   "success_url":"",
   "customer":{
      "name":"John Doe",
      "email":"example@mail.com"
   },
   "recurring_init": "true",
   "hash":"728d13b95cf2b6b3ee04b20dc2fc9889ffff1cf4"
}
'

Example Response - 400 Bad Request

{
  "error_code": 0,
  "error_message": "Request data is invalid.",
  "errors": [
    {
      "error_code": 100000,
      "error_message": "operation: The value you selected is not a valid choice."
    },
    {
      "error_code": 100000,
      "error_message": "methods: This value should not be blank."
    },
    {
      "error_code": 100000,
      "error_message": "order.number: This value should not be blank."
    },
    {
      "error_code": 100000,
      "error_message": "order.amount: This value should be greater than 0."
    },
    {
      "error_code": 100000,
      "error_message": "order.currency: This value is not valid."
    },
    {
      "error_code": 100000,
      "error_message": "order.description: This value should not be blank."
    },
    {
      "error_code": 100000,
      "error_message": "cancel_url: This value is not a valid URL."
    },
    {
      "error_code": 100000,
      "error_message": "success_url: This value should not be blank."
    }
  ]
}

Hash Validation

The Checkout service always performs hash validation. The request will be rejected if the hash value is invalid.

Example Request - Hash Validation

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \
--header 'Content-Type: application/json' \
--data-raw '{  
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "operation":"purchase",
   "methods":[
      "card"
   ],
   "order":{
      "number":"order-1234",
      "amount": "0.19",
      "currency":"USD",
      "description":"Important gift"
   },
   "cancel_url":"https://example.com/cancel",
   "success_url":"https://example.com/success",
   "customer":{
      "name":"John Doe"
   },
   "hash":"wrong hash"
}
'

Example Response - Hash error

{
  "error_code": 0,
  "error_message": "Request data is invalid.",
  "errors": [
    {
      "error_code": 100000,
      "error_message": "hash: Hash is not valid."
    }
  ]
}

Callback Notification

Checkout service sends the callback on the merchant notification_URL as a result of an operation.

You can receive the callback for the next operation types:

SALE
3DS
REDIRECT
REFUND
VOID
RECURRING
CHARGEBACK
DEBIT
TRANSFER

⚠️ Pay attention

Note that the notification URL may be temporarily blocked due to consistently receiving timeouts in response to the callback. If five timeouts accumulate within five minutes for a merchant’s notification URL, it will be blocked for 15 minutes. During this block, all merchants associated with the URL will not receive notifications. The block automatically lifts after 15 minutes. Additionally, it is possible to manually unblock the URL through the admin panel by navigating to Configuration → Merchants → Edit Merchant. In this case, the block will be removed immediately. The timeout counter resets if a callback response is successfully processed. For instance, if there are four timeouts within five minutes but a successful response on the sixth minute, the counter resets.

⚠️ Pay attention

In the case of cascading, the logic for sending callbacks differs.
If cascading is triggered for the order, in general case you will receive only callback for the last payment attempt, where the final status of the order (settled or declined) is determined. In the particular cases, you will receive callback for the first payment attempt with the data for customer’s redirection if it is required by payment provider. Callbacks for intermediate attempts (between the first decline and the last payment attempt) are not sent.

List of Possible Transaction Statuses

The possible statuses are listed below:

Transaction Status	Operation type	Description
SUCCESS	sale, 3ds, redirect, capture, refund, void, recurring, chargeback, debit, transfer	Transaction is successfully completed in Payment Platform
FAIL	sale, capture, refund, void, recurring, debit, transfer	Transaction has the errors and is not validated by Payment Platform
WAITING	sale, capture, refund, void, recurring, debit, transfer	Transaction is being processed by Payment Platform
UNDEFINED	sale, 3ds, redirect, capture, refund, void, recurring, debit, transfer	Uncertain payment status due to problems interacting with the payment provider

⚠️ Pay attention

that successful transaction does not mean successful final status for the payment.

Example for SMS mode (1-step paments) only:
Payment is successfully completed if transaction has status = success and type = sale. Payment is not completed if transaction has status = success and type = redirect.

Callback parameters

Callback is HTTP POST request whcih includes the following data:

Parameter	Type	Mandatory, Limitations	Description
`id`	String	Required	Transaction ID Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`order_number`	String	Required Up to 255 characters	Order ID Example: order-1234
`order_amount`	Float	Required Format: XX.XX, without leading zeroes	Product price Example: 0.19
`order_currency`	String	Required Up to 6 characters	Currency code. 3-characters for fiat currencies and from 3 to 6 characters for crypto currencies Example (fiat): USD Example (crypto): USDT
`order_description`	String	Required Up to 1024 characters	Product description Example: Important gift
`order_status`	String	Required Up to 20 characters	Payment status: prepare, settled, pending, 3ds, redirect, decline, refund, reversal, chargeback Example: 3ds
`type`	String	Required Up to 36 characters	Operation type: sale, 3ds, redirect, capture, refund, void, chargeback, debit, transfer Example: sale
`status`	String	Required Up to 20 characters	Transaction status: success, fail, waiting, undefined Example: success
`reason`	String	Optional Up to 1024 characters	Decline or error reason. It displays only if the transaction has FAIL status. Example: The operation was rejected. Please contact the site support
`payee_name`	String	Optional	Payee's first and last name Returns only for transfer operation Example: John Rickher
`payee_email`	String	Optional	Payee's e-mail Returns only for transfer operation Example: example@mail.com
`payee_country`	String	Optional Up to 3 characters	Payee's country Returns only for transfer operation Example: US
`payee_state`	String	Optional Up to 32 characters	Payee's state Returns only for transfer operation Example: California
`payee_city`	String	Optional Up to 32 characters	Payee's city Returns only for transfer operation Example: Los Angeles
`payee_address`	String	Optional Up to 32 characters	Payee's city Returns only for transfer operation Example: 123 Sample Street
`connector_name` *	String	Optional	Connector's name (Payment Gateway). Example: MyPaymentConnector
`rrn` *	String	Optional	Retrieval Reference Number value from the acquirer system. Example: 123456789012
`approval_code` *	String	Optional	Approval code value from the acquirer system. Example: 123456
`gateway_id` *	String	Optional	Gateway ID – transaction identifier provided by payment gateway. Example: 123-456-789
`extra_gateway_id` *	String	Optional	Extra Gateway ID – additional transaction identifier provided by payment gateway. Example: abc123
`merchant_name`*	String	Optional	Merchant Name Example: TESTMerchantName
`mid_name` *	String	Optional	MID Name Example: TESTMIDName
`issuer_country` *	String	Optional	Issuer Country Example: DE
`issuer_bank` *	String	Optional	Issuer Bank Example: Deutsche Bank
`card`	String	Optional Format: ХХХХХХ******ХХХХ	Card number mask Example: 411111******1111
`card_expiration_date`	String	Optional	Card expiration date Example: 12/2022
`payee_card`	String	Optional	Payee card number mask Returns only for transfer operation Example: 411111******1111
`card_token`	String	Optional	Card token. It is available if the parameter `req_token` was enabled It is available only for purchase operation Example: VjFRaUxDSmhiR2NpT2lKU1V6STFO
`crypto_network`	String	Optional	Blockchain network where the transaction is taking place Example: ERC20
`crypto_address`	String	Optional	Public address of a cryptocurrency wallet Example: bc1QWXYZ8901ghijkLMNOPqrstv2345wxyzABCDE
`customer_name`	String	Optional	Customer's first and last name Example: John Rickher
`customer_email`	String	Optional Format: `example@mail.com`	Customer's email address Example: fdfd@dfsds.ds
`customer_country`	String	Optional Up to 3 characters	Customer's country Example: US
`customer_state`	String	Optional Up to 32 characters	Customer's state Example: California
`customer_city`	String	Optional	Customer's city Example: Los Angeles
`customer_address`	String	Optional Up to 32 characters	Customer's address Example: 123 Sample Street
`customer_ip`	String	Required	Customer's IP Example: 255.41.45.57
`date`	Date	Optional Format: YYYY-MM-DD hh:mm:ss	Transaction date Example: 2020-08-05 07:41:10
`recurring_init_trans_id`	String	Optional	Reference to the first transaction that initializes the recurring (provided if recurring was initialized) It is available only for purchase operation Example: dc66cdd8-d702-11ea-9a2f-0242c0a87099
`recurring_token`	String	Optional	Recurring token (provided if recurring was initialized) Example: e5f60b35485e
`schedule_id`	String	Optional	It is available if schedule is used for recurring sale It is available only for purchase operation
`exchange_rate`	Decimal	Optional	Rate used to make exchange. It returns if the currency exchange has been applied for the payment.
`exchange_rate_base`	Decimal	Optional	The rate used in the double conversion to convert the original currency to the base currency. It returns if the currency exchange has been applied for the payment.
`exchange_currency`	Dictionary	Optional	Original currency. It returns if the currency exchange has been applied for the payment.
`exchange_amount`	Integer	Optional	Original amount. It returns if the currency exchange has been applied for the payment.
`vat_amount`	Float	Optional Format: XX.XX, without leading zeroes	Product VAT Returns if VAT has been calculated for the payment. It is available only for purchase operation Example: 0.09
`digital_wallet`	String	Optional	Wallet provider: googlepay, applepay. It is returned if digital wallets were used for card payment creation. Example: googlepay
`pan_type`	String	Optional	It refers to digital payments, such as Apple Pay and Google Pay, and the card numbers returned as a result of payment token decryption: DPAN (Digital Primary Account Number) and FPAN (Funding Primary Account Number). Possible values: dpan, fpan. It is returned if digital wallets were used in card payment creation. Example: dpan
custom_data	Object	Optional	Custom data This block duplicates the arbitrary parameters that were passed in the payment request Example: `“custom_data”: {“param1”:”value1”, “param2”:”value2”, “param3”:”value3”}`
`hash`	String	Required	Special signature, used to validate callback Addition in Signature section. Example: Must be SHA1 of MD5 encoded string (uppercased): payment_public_id + order.number + order.amount + order.currency + order.description + merchant.pass

* The parameters are included if the appropriate setup is configured in the admin panel (see “Add Extended Data to Callback” block in the Configurations -> Protocol Mappings section).

Examples

Callback examples

Merchant successful sale callback

id=f0a51dfa-fc43-11ec-8128-0242ac120004&
order_number=order-1234&
order_amount=3.01&
order_currency=USD&
order_description=bloodline&
order_status=settled&
type=sale&
status=success&
card=411111****1111&
card_expiration_date=12/2022&
connector_name=MyPaymentConnector&
rrn=789012345678& 
approval_code=123456&
schedule_id=4e46866c-f84b-11ec-8b4c-0242ac120007&
recurring_init_trans_id=f0a51dfa-fc43-11ec-8128-0242ac120004&
recurring_token=f0e24964-fc43-11ec-a7e0-0242ac120004&
date=2022-07-05 09:22:09&
hash=6d8d440e25bdfc5288616ce567496948d2562852&
gateway_id=123-456-789&
extra_gateway_id=abc123&
merchant_name=TESTMerchantName&
mid_name=TESTMIDName&
issuer_country=DE&
issuer_bank=Deutsche Bank&
customer_name=D D&
customer_email=success@gmail.com&
customer_country=US&
customer_state=California&
customer_city=Los Angeles&
customer_address=Moor Building 35274 State ST Fremont. U.S.A&
customer_ip=10.10.10.2&
exchange_rate_base=26.19&
exchange_rate=6.47&
exchange_currency=UAH&
exchange_amount=100.00

Merchant successful debit callback

id=f0a51dfa-fc43-11ec-8128-0242ac120004&
order_number=order-1234&
order_amount=3.01&
order_currency=USD&
order_description=bloodline&
order_status=settled&
type=debit&
status=success&
card=411111****1111&
card_expiration_date=12/2022&
date=2022-07-05+09:22:09&
hash=6d8d440e25bdfc5288616ce567496948d2562852&
customer_name=D D&
customer_email=success@gmail.com&
customer_country=US&
customer_state=California&
customer_city=Los Angeles&
customer_address=Moor Building 35274 State ST Fremont. U.S.A&
customer_ip=10.10.10.2

Merchant successful refund callback

 id=f0a51dfa-fc43-11ec-8128-0242ac120004&
 order_number=order-1234&
 order_amount=3.01&
 order_currency=USD&
 order_description=bloodline&
 order_status=settled&
 type=refund&
 status=success&
 card=411111****1111&
 card_expiration_date=12/2022&
 schedule_id=4e46866c-f84b-11ec-8b4c-0242ac120007&
 date=2022-07-05+09:28:01&
 hash=6d8d440e25bdfc5288616ce567496948d2562852&
 customer_name=D D&
 customer_email=success@gmail.com&
 customer_country=US&
 customer_state=California&
 customer_city=Los Angeles&
 customer_address=Moor Building 35274 State ST Fremont. U.S.A&
 customer_ip=10.10.10.2

Merchant successful transfer callback

id=f0a51dfa-fc43-11ec-8128-0242ac120004&
order_number=order-1234&
order_amount=3.01&
order_currency=USD&
order_description=bloodline&
order_status=settled&
type=transfer&
status=success&card=411111****1111&
card_expiration_date=12/2022&
payee_card=422222****2222&
date=2022-07-05+09:22:09&
hash=6d8d440e25bdfc5288616ce567496948d2562852&
customer_name=D D&
customer_email=success@gmail.com&
customer_country=US&
customer_state=California&
customer_city=Los Angeles&
customer_address=Moor Building 35275&
customer_ip=10.10.10.2&
payee_name=D D&
payee_email=success@gmail.com&
payee_country=US&
payee_state=California&
payee_city=Los Angeles&payee_address=Moor Building 35274 State ST Fremont. U.S.A

Merchant unsuccessful sale callback

id=1f34f446-fc45-11ec-a50f-0242ac120004&
order_number=order-1234&
order_amount=3.01&
order_currency=USD&
order_description=bloodline&
order_status=decline&
type=sale&
status=fail&
card=411111****1111&
card_expiration_date=12/2022&
reason=Declined by processing.&
date=2022-07-05+09:30:35&
hash=7f15d178e9b2c8507dea57f8ed1efddb9573fa6b&
customer_name=D D&
customer_email=success@gmail.com&
customer_country=US&
customer_state=California&
customer_city=Los Angeles&
customer_address=Moor Building 35274 State ST Fremont. U.S.A&
customer_ip=10.10.10.2

Merchant unsuccessful debit callback

id=1f34f446-fc45-11ec-a50f-0242ac120004&
order_number=order-1234&
order_amount=3.01&
order_currency=USD&
order_description=bloodline&
order_status=decline&
type=debit&status=fail&
card=411111****1111&
card_expiration_date=12/2022&
reason=Declined by processing.&
date=2022-07-05+09:30:35&
hash=7f15d178e9b2c8507dea57f8ed1efddb9573fa6b&
customer_name=D D&
customer_email=success@gmail.com&
customer_country=US&
customer_state=California&
customer_city=Los Angeles&
customer_address=Moor Building 35274 State ST Fremont. U.S.A&
customer_ip=10.10.10.2

Merchant unsuccessful refund callback

id=ba290c62-fc45-11ec-9e91-0242ac120004&
order_number=order-1234&
order_amount=3.01&
order_currency=USD&
order_description=bloodline&
order_status=decline&
type=refund&
status=fail&
card=411111****1111&
card_expiration_date=12/2022&
reason=Declined by processing.&
schedule_id=4e46866c-f84b-11ec-8b4c-0242ac120007&recurring_init_trans_id=ba290c62-fc45-11ec-9e91-0242ac120004&recurring_token=ba51844e-fc45-11ec-932c-0242ac120004&
date=2022-07-05+09:38:00&
hash=bcd78ff8b8e6b75aa1743910641217be6edc3a43&
customer_name=D D&
customer_email=success@gmail.com&customer_country=US&
customer_state=California&
customer_city=Los Angeles&
customer_address=Moor Building 35274 State ST Fremont. U.S.A&
customer_ip=10.10.10.2

Merchant unsuccessful transfer callback

id=1f34f446-fc45-11ec-a50f-0242ac120004&
order_number=order-1234&
order_amount=3.01&
order_currency=USD&
order_description=bloodline&
order_status=decline&
type=transfer&
status=fail&
card=411111****1111&
card_expiration_date=12/2022&
payee_card=422222****2222&
date=2022-07-05+09:22:09&
hash=6d8d440e25bdfc5288616ce567496948d2562852&
customer_name=D D&
customer_email=success@gmail.com&
customer_country=US&
customer_state=California&
customer_city=Los Angeles&
customer_address=Moor Building 35275&
customer_ip=10.10.10.2&
payee_name=D D&
payee_email=success@gmail.com&
payee_country=US&
payee_state=California&
payee_city=Los Angeles&
payee_address=Moor Building 35274 State ST Fremont. U.S.A&
vat_amount=0.3

Merchant successful crypto callback

id=ac60a7e6-9abf-11ef-a549-0242ac120002&
order_number=order-1234&
order_amount=0.00000001&
order_currency=BTC&
order_description=Important+gift&order_status=pending&
type=init&status=success&
date=2024-11-04+15%3A15%3A49&
hash=871a243619e4fd04db377cfbabe9fe07505febf5&
crypto_network=ERC20&
crypto_address=bc1ABIJKL1234abfjkmoPQRTVXY5678prsx&
customer_name=John+Doe&
customer_email=success%40gmail.com&
customer_country=US&
customer_state=California&
customer_city=Los+Angeles&
customer_address=Moor+Building+35274+State+ST+Fremont.+U.S.A&
customer_ip=10.10.10.2

Recurring

Recurring payments are commonly used to create new transactions based on already stored cardholder information from previous operations. This request is sent by POST in JSON format.

RECURRING request

/api/v1/payment/recurring

Request Parameters

Parameter	Type	Mandatory, Limitations	Description
`merchant_key`	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
`recurring_init_trans_id`	String	Required	Transaction ID of the primary transaction in the Payment Platform Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`recurring_token`	String	Required	Recurring token Example: 9a2f-0242c0a87002
`schedule_id`	String	Optional	Schedule ID for recurring payments
`hash`	String	Required	Special signature to validate your request to Payment Platform Addition in Signature section Must be SHA1 of MD5 encoded string (uppercased): recurring_init_trans_id + recurring_token + order.number + order.amount + order.description + merchant_pass
order	Object
`number`	String	Required Not blank max: 255 [a-zA-Z0-9-]	Order ID Example: order-1234
`amount`	Float	Required Not blank Greater then 0 0-9 max: 255	Format depends on currency. Send Integer type value for currencies with zero-exponent. Example: 1000 Send Float type value for currencies with exponents 2, 3, 4. Format for 2-exponent currencies: XX.XX Example: 100.99 Pay attention that currencies 'UGX', 'JPY', 'KRW', 'CLP' must be send in the format XX.XX, with the zeros after comma. Example: 100.00 Format for 3-exponent currencies: XXX.XXX Example: 100.999. Format for 4-exponent currencies: XXX.XXXX Example: 100.9999
`description`	String	Required min: 2 max: 1024 [a-zA-Z0-9!"#$%&'()*+,./:;&@]	Product name Example: Very important gift - # 9

Response Parameters

Parameter	Type	Mandatory, Limitations	Description
`status`	String	Required	Payment status Example: SETTLED, PENDING, DECLINE
`reason`	String	Optional	Decline reason translation for unsuccessful payment. It displays only if the transaction is unsuccessful Example: The operation was rejected. Please contact the site support
`payment_id`	String	Required Up to 255 characters	Transaction ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`date`	String	Required Format: YYYY-MM-DD hh:mm:ss	Transaction date Example: 2020-08-05 07:41:10
`schedule_id`	String	Optional	Schedule ID for recurring payments
order	Object
`number`	String	Required max: 255	Order ID Example: order-1234
`amount`	String	Required Format: XX.XX	Product price (currency will be defined by the first payment) Example: 0.19
`currency`	String	Required 3 characters	Currency Example: USD
`description`	String	Required max: 1024	Product name Example: Very important gift - # 9

Example Request

Recurring (settled)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/recurring' \
--header 'Content-Type: application/json' \
--data-raw '{ 
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "order":{
      "number":"order-1234",
      "amount": "0.19",
      "description":"very important gift"
},
    "customer": {
        "name": "John Doe",
        "email": "success@gmail.com"
    },     
       "recurring_init_trans_id":"dc66cdd8-d702-11ea-9a2f-0242c0a87002", 
       "recurring_token":"9a2f-0242c0a87002",
       "schedule_id":"57fddecf-17b9-4d38-9320-a670f0c29ec0", 
       "hash":"{{session_hash}}"
}'

Recurring (declined)

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/recurring' \
--header 'Content-Type: application/json' \
--data-raw '{ 
    "payment_id": "1f34f446-fc45-11ec-a50f-0242ac120004",
    "date": "2022-07-05 09:30:34",
    "status": "decline",
    "reason": "Declined by processing.",
    "order": {
        "number": "order-1234",
        "amount": "3.01",
        "currency": "USD",
        "description": "bloodline"
    },
    "customer": {
        "name": "John Doe",
        "email": "success@gmail.com"
    }
}'

Example Response

Status Settled

{
  "status": "settled",
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "date": "2020-08-05 07:41:10",
  "schedule_id":"57fddecf-17b9-4d38-9320-a670f0c29ec0",
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "USD",
    "description": "very important gift"
  }
}

Status Declined

{
  "status": "declined",
  "reason": "declined by processing",
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "schedule_id":"57fddecf-17b9-4d38-9320-a670f0c29ec0",
  "date": "2020-08-05 07:41:10",
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "USD",
    "description": "very important gift"
  }
}

Retry

RETRY request is used to retry funds charging for secondary recurring payments in case of soft decline.

This action creates RETRY transaction and can cause payment final status changing.

This request is sent by POST in JSON format.

RETRY request

/api/v1/payment/retry

Request parameters

Parameter	Type	Mandatory, Limitations	Description
`merchant_key`	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
`payment_id`	String	Required Up to 255 characters	Payment ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`hash`	String	Required	Special signature to validate your request to Payment Platform Addition in Signature section. Must be SHA1 of MD5 encoded string (uppercased): payment_id + merchant_pass

Request example

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/retry' \
--header 'Content-Type: application/json' \
--data-raw '{
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "payment_id":"63c781cc-de3d-11eb-a1f1-0242ac130006",
   "hash":"{{operation_hash}}"
}'

Response Parameters

Parameter	Type	Mandatory, Limitations	Description
`payment_id`	String	Required Up to 255 characters	Payment ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`result`	String	Required	Retry request result Example: accepted

Response example

{
  "payment_id": "63c781cc-de3d-11eb-a1f1-0242ac130006",
  "result": "accepted"
}

Get transaction status

This request is sent by POST in JSON format.

To get order status you can use one the identifiers:

• payment_id – transaction ID in the Payment Platform
• order_id – merchant’s transaction ID

/api/v1/payment/status

GET_TRANS_STATUS by `payment_id`

Note: The response logic for a status request depends on the Cascading Context for Get Status setting in Cofiguration --> Protocol Mappings section. If enabled, the system returns the status of the most recently created payment within the cascade (i.e., the payment with the latest creation date), rather than the payment specified in the request.

Request Parameters by `payment_id`

Parameter	Type	Mandatory, Limitations	Description
`merchant_key`	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
`payment_id`	String	Required Up to 255 characters	Payment ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`hash`	String	Required	Special signature to validate your request to Payment Platform Addition in Signature section. Must be SHA1 of MD5 encoded string (uppercased): payment_id + merchant_pass

Response Parameters by `payment_id`

Parameter	Type	Mandatory, Limitations	Description
`payment_id`	String	Required Up to 255 characters	Payment ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`date`	String	Required Format: YYYY-MM-DD hh:mm:ss	Transaction date Example: 2020-08-05 07:41:10
`status`	String	Required	Payment status: prepare, settled, pending, 3ds, redirect, decline, refund, reversal, void, chargeback Example: settled
`reason`	String	Optional	Decline reason translation for unsuccessful payment. It displays only if the transaction is unsuccessful Example: The operation was rejected. Please contact the site support
`recurring_token`	String	Optional	Recurring token (provided if recurring was initialized) Example: e5f60b35485e
`shedule_id`	String	Optional	Schedule ID for recurring payments. Only for purchase operation Example: 57fddecf-17b9-4d38-9320-a670f0c29ec0
order	Object
`number`	String	Required Up to 255 characters	Order ID Example: order-1234
`amount`	String	Required Format: XX.XX	Product price Example: 0.19
`currency`	String	Required Up to 3 characters	Currency Example: USD
`description`	String	Required Up to 1024 characters	Product name Example: Very important gift
customer	Object
`name`	String	Required	Customer's name Example: John Doe
`email`	String	Required	Customer's email address Example: example@mail.com
`digital_wallet`	String	Optional	Wallet provider: googlepay, applepay. It returns if digital wallets were used for card payment creation. Example: googlepay

Example Request

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/status' \
--header 'Content-Type: application/json' \
--data-raw '{  
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "payment_id":"63c781cc-de3d-11eb-a1f1-0242ac130006",
   "hash":"{{operation_hash}}"
}
'

Example Response

Status Settled

{
  "payment_id": "24f7401c-fc47-11ec-8d07-0242ac120015",
  "date": "2022-07-05 09:45:03",
  "status": "settled",
  "recurring_token": "e5f60b35485e",
  "shedule_id ": "57fddecf-17b9-4d38-9320-a670f0c29ec0",
  "digital_wallet": "googlepay",
  "order": {
    "number": "f0a51dfa-fc43-11ec-8128-0242ac120004-1",
    "amount": "3.01",
    "currency": "USD",
    "description": "bloodline"
  },
  "customer": {
    "name": "John Doe",
    "email": "success@gmail.com"
  }
}

Status Decline

{
  "payment_id": "03e46e96-de42-11eb-aea7-0242ac140002",
  "date": "2021-07-06 10:07:47",
  "status": "decline",
  "reason": "Declined by processing",
  "digital_wallet": "googlepay",
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "USD",
    "description": "Important gift"
  },
  "customer": {
    "name": "John Doe",
    "email": "test@mail.com"
  }
}

GET_TRANS_STATUS by `order_id`

Use this request to get the status of the most recent transaction in the order's transaction subsequence.

It is recommended to send an unique order number (the order.number parameter) in the Authorization request. That way, it will be easier to uniquely identify the payment by order_id. This is especially important if cascading is configured. In this case, several intermediate transactions could be created within one payment.

Request Parameters by `order_id`

Parameter	Type	Mandatory, Limitations	Description
`merchant_key`	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
`order_id`	String	Required Up to 255 characters	Merchant’s Order Number Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`hash`	String	Required	Special signature to validate your request to Payment Platform Addition in Signature section. Must be SHA1 of MD5 encoded string (uppercased): order_id + merchant_pass

Response Parameters by `order_id`

Parameter	Type	Mandatory, Limitations	Description
`payment_id`	String	Required Up to 255 characters	Transaction ID in Payment Platform Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`date`	String	Required Format: YYYY-MM-DD hh:mm:ss	Transaction date Example: 2020-08-05 07:41:10
`status`	String	Required Up to 20 characters	Payment status: prepare, settled, pending, 3ds, redirect, decline, refund, reversal, void, chargeback Example: settled
`reason`	String	Optional Up to 1024 characters	Decline reason translation for unsuccessful payment. It displays only if the transaction is unsuccessful Example: The operation was rejected. Please contact the site support
`recurring_token`	String	Optional	Recurring token (provided if recurring was initialized) Example: e5f60b35485e
`shedule_id`	String	Optional	Schedule ID for recurring payments. Only for purchase operation Example: 57fddecf-17b9-4d38-9320-a670f0c29ec0
order	Object
`number`	String	Required Up to 255 characters	Merchant’s Order ID Example: order-1234
`amount`	String	Required Format: XX.XX	Product price (currency will be defined by the first payment) Example: 0.19
`currency`	String	Required Up to 3 characters	Currency Example: USD
`description`	String	Required Up to 1024 characters	Product name or other additional information Example: Very important gift
customer	Object
`name`	String	Required	Customer's name Example: John Doe
`email`	String	Required	Customer's email address Example: example@mail.com
`digital_wallet`	String	Optional	Wallet provider: googlepay, applepay. It is returned if digital wallets were used for card payment Example: googlepay

Example Request

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/status' \
--header 'Content-Type: application/json' \
--data-raw '{  
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "order_id":"63c781cc-de3d-11eb-a1f1-0242ac130006",
   "hash":"{{operation_hash}}"
}
'

Example Response

Status Settled

{
    "payment_id": "24f7401c-fc47-11ec-8d07-0242ac120015",
    "date": "2022-07-05 09:45:03",
    "status": "settled",
    "recurring_token": "e5f60b35485e",
    "shedule_id ": "57fddecf-17b9-4d38-9320-a670f0c29ec0",
    "digital_wallet": "googlepay",
    "order": {
        "number": "f0a51dfa-fc43-11ec-8128-0242ac120004-1",
        "amount": "3.01",
        "currency": "USD",
        "description": "bloodline"
    },
    "customer": {
        "name": "John Doe",
        "email": "success@gmail.com"
    }
}

Status Decline

{
  "payment_id": "03e46e96-de42-11eb-aea7-0242ac140002",
  "date": "2021-07-06 10:07:47",
  "status": "decline",
  "reason": "Declined by processing",
  "digital_wallet": "googlepay",
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "USD",
    "description": "Important gift"
  },
  "customer": {
    "name": "John Doe",
    "email": "test@mail.com"
  }
}

Refund

To make refund you can use Refund request. Use payment public ID from Payment Platform in the request.

This request is sent by POST in JSON format.

Refund request

/api/v1/payment/refund

Request Parameters

Parameter	Type	Mandatory, Limitations	Description
`merchant_key`	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
`payment_id`	String	Required Up to 255 characters	Payment ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`amount`	String	Required Format: XX.XX, without leading zeroes	Amount to refund. It is required for particular refund. Example: 0.19
`hash`	String	Required	Special signature to validate your request to Payment Platform Addition in Signature section. Must be SHA1 of MD5 encoded string (uppercased): payment.id + amount + merchant.pass

Response Parameters

Parameter	Type	Mandatory, Limitations	Description
`payment_id`	String	Required Up to 255 characters	Transaction ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`result`	String	Required	Refund request result Example: accepted

Example Request

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/refund' \
--header 'Content-Type: application/json' \
--data-raw '{  
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "payment_id":"63c781cc-de3d-11eb-a1f1-0242ac130006",
   "amount":"0.10",
   "hash":"{{operation_hash}}"
}
'

Example Response: Refund request accepted

{
  "payment_id": "63c781cc-de3d-11eb-a1f1-0242ac130006",
  "result": "accepted"
}

Void

To make a void for an operation which was performed the same financial day you can use Void request.

The Void request is allowed for the payments in SETTLED status only.

Use payment public ID from Payment Platform in the request.

Void request

/api/v1/payment/void

Request Parameters

Parameter	Type	Mandatory, Limitations	Description
`merchant_key`	String	Required	Key for Merchant identification Example: xxxxx-xxxxx-xxxxx
`payment_id`	String	Required Up to 255 characters	Payment ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`hash`	String	Required	Special signature to validate your request to Payment Platform Addition in Signature section. Must be SHA1 of MD5 encoded string (uppercased): payment.id + merchant.pass

Response Parameters

Parameter	Type	Mandatory, Limitations	Description
`status`	String	Required	Payment status Example: VOID / SETTLED
`payment_id`	String	Required Up to 255 characters	Transaction ID (public) Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
`date`	String	Required Format: YYYY-MM-DD hh:mm:ss	Transaction date Example: 2020-08-05 07:41:10
`reason`	String	Optional	Decline or error reason (for "sale", "void "and "refund" operation types). It displays only if the transaction has FAIL status Example: The operation was rejected. Please contact the site support
order	Object
`number`	String	Required	Order ID Example: order-1234
`amount`	String	Required	Product price Example: 0.19
`currency`	String	Required Up to 3 characters	Currency Example: USD
`description`	String	Required Up to 1024 characters	Product name Example: Very important gift

Example Request

curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/void' \
--header 'Content-Type: application/json' \
--data-raw '{  
   "merchant_key":"xxxxx-xxxxx-xxxxx",
   "payment_id":"63c781cc-de3d-11eb-a1f1-0242ac130006",
   "hash":"{{operation_hash}}"
}
'

Example Response: Void successful

{
  "status": "SUCCESS", 
  "payment_status": "void",
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "date": "2020-08-05 07:41:10",
  "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "USD",
    "description": "very important gift"
  }
}

Example Response: Void failed

{
  "status": "FAIL", 
  "payment_status": "settled",
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "date": "2020-08-05 07:41:10",
  "reason": "Declined by processing",
   "order": {
    "number": "order-1234",
    "amount": "0.19",
    "currency": "USD",
    "description": "very important gift"
  }
}

Signature

Sign is signature rule used either to validate your requests to payment platform or to validate callback from payment platform to your system.

Authentication Signature

It must be SHA1 of MD5 encoded string and calculated by the formula below:

*sha1(md5(strtoupper(id.order.amount.currency.description.PASSWORD)))

// Use the CryptoJSvar

Example for JS

var to_md5 = order.number + order.amount + order.currency + order.description + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Get Transaction Status Signature (by `payment_id`)

It must be SHA1 of MD5 encoded string and calculated by the formula below:

hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

*sha1(md5(strtoupper))

// Use the CryptoJSvar

Example for JS

var to_md5 = payment.id + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Get Transaction Status Signature (by `order_id`)

It must be SHA1 of MD5 encoded string and calculated by the formula below:

hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

*sha1(md5(strtoupper))

// Use the CryptoJSvar

Example for JS

var to_md5 = order.id + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Refund Signature

It must be SHA1 of MD5 encoded string and calculated by the formula below:

hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString()); *sha1(md5(strtoupper))

// Use the CryptoJSvar

Example for JS

var to_md5 = payment.id + amount + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Void Signature

It must be SHA1 of MD5 encoded string and calculated by the formula below:

hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString()); *sha1(md5(strtoupper))

// Use the CryptoJSvar

Example for JS

var to_md5 = payment.id + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Recurring Signature

It must be SHA1 of MD5 encoded string and calculated by the formula below:

*sha1(md5(strtoupper(recurring_init_trans_id.recurring_token.order_id.amount.description.merchant.pass)))

// Use the CryptoJS

Example for JS

var to_md5 = recurring_init_trans_id + recurring_token + order.number + order.amount + order.description + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Signature for return

It must be SHA1 of MD5 encoded string and calculated by the formula below:

hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString()); *sha1(md5(strtoupper(payment_public_id.order_id.amount.currency.description.PASSWORD)))

Example for JS

var to_md5 = payment_public_id + order.number + order.amount + order.currency + order.description + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Callback Signature

It must be SHA1 of MD5 encoded string and calculated by the formula below:

hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString()); *sha1(md5(strtoupper(payment_public_id.order_id.amount.currency.description.PASSWORD)))

Example for JS

var to_md5 = payment_public_id + order.number + order.amount + order.currency + order.description + merchant.pass;

// Use the CryptoJS

var hash = CryptoJS.SHA1(CryptoJS.MD5(to_md5.toUpperCase()).toString());

var result = CryptoJS.enc.Hex.stringify(hash);

Testing

You can test your integration. To do the test you need to perform the actions with the API using (in test mode). For instance, send the request and receive the response with a link on the Checkout page.
To mark your transactions as test in the system, you should use Merchant Test Key as value of the merchant_key parameter. You can contact your administrator to make sure that you have the necessary settings to work with test transactions.

Use the following test data to emulate the different scenarios.

Scenario: SUCCESS payment

Card data:

Card number 4111 1111 1111 1111
Expiry Date 01/38
CVV2 any 3 digits

⚠️ Use that card data to create recurring payments and get a recurring token for the initial recurring. Testing recurring payments does not work with other test cards.

Result: customer is redirected to the "success_URL"

Scenario: FAILED payment (decline)

Card data:

Card number 4111 1111 1111 1111
Expiry Date 02/38
CVV2 any 3 digits

Result: customer gets an error message: Declined by processing.

Scenario: SUCCESS 3DS payment

Card data:

Card number 4111 1111 1111 1111
Expiry Date 05/38
CVV2 any 3 digits

Result: customer is redirected to the "success_URL" after 3DS verification

Scenario: FAILED 3DS payment

Card data:

Card number 4111 1111 1111 1111
Expiry Date 06/38
CVV2 any 3 digits

Result: customer gets unsuccessful sale after 3DS verification

Scenario: FAILED payment (Luhn algorithm)

Card data:

Card number 1111 2222 3333 4444
Expiry Date 01/38
CVV2 any 3 digits

Result: customer gets an error message: Bad Request. Brand of card does not support.

Introduction​

General Information​

Checkout process​

Protocol Mapping​

Customer return after payment​

DMS mode​

Checkout page description​

Fields and Validation​

Pre-routing​

Card data tokenization​

Web information​

iFrame option​

Page Customization​

Authentication request parameters​

Request Parameters​

Authentication request possible errors​

Parameter Values Validation​

Hash Validation​

Callback Notification​

List of Possible Transaction Statuses​

Callback parameters​

Examples​

Recurring​

Request Parameters​

Response Parameters​

Retry​

Request parameters​

Response Parameters​

Get transaction status​

GET_TRANS_STATUS by payment_id​

Request Parameters by payment_id​

Response Parameters by payment_id​

GET_TRANS_STATUS by order_id​

Request Parameters by order_id​

Response Parameters by order_id​

Refund​

Request Parameters​

Response Parameters​

Void​

Request Parameters​

Response Parameters​

Signature​

Authentication Signature​

Example for JS​

Get Transaction Status Signature (by payment_id)​

Example for JS​

Get Transaction Status Signature (by order_id)​

Example for JS​

Refund Signature​

Example for JS​

Void Signature​

Example for JS​

Recurring Signature​

Example for JS​

Signature for return​

Callback Signature​

Example for JS​

Testing​

Introduction

General Information

Checkout process

Protocol Mapping

Customer return after payment

DMS mode

Checkout page description

Fields and Validation

Pre-routing

Card data tokenization

Web information

iFrame option

Page Customization

Authentication request parameters

Request Parameters

Authentication request possible errors

Parameter Values Validation

Hash Validation

Callback Notification

List of Possible Transaction Statuses

Callback parameters

Examples

Recurring

Request Parameters

Response Parameters

Retry

Request parameters

Response Parameters

Get transaction status

GET_TRANS_STATUS by `payment_id`

Request Parameters by `payment_id`

Response Parameters by `payment_id`

GET_TRANS_STATUS by `order_id`

Request Parameters by `order_id`

Response Parameters by `order_id`

Refund

Request Parameters

Response Parameters

Void

Request Parameters

Response Parameters

Signature

Authentication Signature

Example for JS

Get Transaction Status Signature (by `payment_id`)

Example for JS

Get Transaction Status Signature (by `order_id`)

Example for JS

Refund Signature

Example for JS

Void Signature

Example for JS

Recurring Signature

Example for JS

Signature for return

Callback Signature

Example for JS

Testing