Skip to main content

Checkout Integration

Version: 4.5.2
Released: 2022/10/10

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.

Checkout process#

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

  1. Customer places an order and initiates payment on the site.
  2. Site confirms the order and sends the payment processing request to the Checkout system with information about the order, payment and hash.
  3. Checkout system validates the request and sends to the site the response with the redirect link.
  4. The site redirects the Customer on the Checkout page by redirect link.
  5. 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.
  6. The payment processes at Payment Gateway.
  7. Payment Gateway sends a callback to the site with the payment result.
  8. The payment result is shown to the Customer.

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

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 22 characters
(min - 2 characters)		 The name on card field
must have at least 2 characters
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.

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:

  1. Click the “Configuration → Branding” item on the menu bar. The settings are displayed in the work area.
  2. Select a page template to make changes.
  3. Change the settings:
    1. login icon selection;
    2. color selection for the following items:
      1. heading;
      2. background;
      3. buttons;
  4. 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. INFO: You need to create an authentication request 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
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.
Example: card, paypal, googlepay
success_url String Required
Valid URL
max: 1024		 URL to redirect the Customer in case of the successful payment
Example: https://example.com/success
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)
Example: https://example.com/cancel
url_target String Optional
Possible values: _blank, _self, _parent, _top or custom iframe name.
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.
Example: false
card_token Array of Strings Optional
String 64 characters		 Credit card token value
Example: f5d6a0ab6fcfb6487a39e2256e50fff3c95aaa97
recurring_init Boolean Optional
default - false		 Initialization of the transaction with possible following recurring
Example: true
schedule_id String Optional
It s available when recurring_init = true		 Schedule ID for recurring payments
Example: 57fddecf-17b9-4d38-9320-a670f0c29ec0
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
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 		Product price. Format: XX.XX.
Pay attention that amount format depends on currency exponent.
If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY.
If exponent = 3, then format: xx.xxx (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.
Example: 0.19
currency String Required
Not blank
3 characters
[A-Z]
ISO 4217 		Currency
Example: USD
description String Required
min: 2 max: 1024
[a-zA-Z0-9!"#$%&'()*+,./:;&@]		 Product name
Example: Very important gift - # 9
customer Object Required Customer's information
name String Required
min: 2 max: 32
Latin basic
[a-zA-Z]		 Customer's name
Example: John Doe
email String Conditional
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
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-zA-Z]
It is 2-letters code for USA, Canada, Australia, Japan, India		 Billing state address
Example: CA
city String Conditional
min: 2 max: 32
[a-zA-Z]		 Billing city
Example: Los Angeles
address String Conditional
min: 2 max: 32
[a-zA-Z0-9]		 Billing address
Example: Moor Building 35274
zip String Conditional
min: 2 max: 10
[a-zA-Z0-9]		 Billing zip code
Example: 123456, MK77
phone String Conditional
min: 0 max: 32
[0-9+()-]		 Customer phone number
Example: 347771112233
parameters Object Extra-parameters required for specific payment method
Example:
"parameters": { "payment_method": { "param1":"val1", "param2":"val2" } }
Example Request
Authentication (OK) 
curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \--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",        "email": "test@gmail.com"    },    "billing_address": {        "country": "US",        "state": "CA",        "city": "Los Angeles",        "address": "Moor Building 35274",        "zip": "123456",        "phone": "347771112233"    },    "hash": "{{session_hash}}",}'
Authentication (with card token) 
curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \--data-raw '{    "merchant_key": "1c568e26-c997-11e9-8be4-0242ac12000f",    "operation": "purchase",    "methods": [        "card",        "paypal",        "netbanking-upi"    ],    "order": {        "number": "{{order_number}}",        "amount": "{{order_amount}}",        "currency": "{{order_currency}}",        "description": "{{order_description}}"    },    "cancel_url": "https://example.com/cancel",    "success_url": "https://example.com/success",    "customer": {        "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": "347771112233"    },    "card_token": [        "f5d6a0ab6fcfb6487a39e2256e50fff3c95aaa97075ee5e539bb662fceff4dc1"    ],    "req_token": true,    "hash": "{{session_hash}}"}'
Authentication (with recurring schedule) 
curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/session' \--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",        "email": "test@gmail.com"    },    "billing_address": {        "country": "US",        "state": "CA",        "city": "Los Angeles",        "address": "Moor Building 35274",        "zip": "123456",        "phone": "347771112233"    },    "recurring_init": true,    "schedule_id": "57fddecf-17b9-4d38-9320-a670f0c29ec0",    "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' \--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' \--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
  • RECURRING
  • CHARGEBACK

List of Possible Transaction Statuses#

The possible statuses are listed below:

Status Operation type Description
SUCCESS sale, 3ds, redirect, refund, recurring, chargeback Transaction is successfully completed in Payment Platform
FAIL sale, refund, recurring Transaction has the errors and is not validated by Payment Platform
WAITING sale, refund, recurring Transaction is being processed by Payment Platform

⚠️ Pay attention

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

For example:
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 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 3 characters Currency (3-characters code)
Example: USD
order_description String Required Up to 1024 characters Product description
Example: Important gift
type String Required Up to 36 characters Operation type: sale, 3ds, redirect, refund, chargeback
Example: sale
status String Required Up to 20 characters Transaction status: success, fail, waiting
Example: success
reason String Optional Up to 1024 characters Decline or error reason (for "sale" and "refund" operation types only). It displays only if the transaction has FAIL status
Example: The operation was rejected. Please contact the site support
rrn String Optional Retrieval Reference Number value from the acquirer system
approval_code String Optional Approval code value from the acquirer system
card String Optional
Format: ХХХХХХ****ХХХХ		 Card number mask
Example: 411111******1111
card_expiration_date String Optional Card expiration date
Example: 12/2022
card_token String Optional Card token. It is available if the parameter req_token was enabled
Example: VjFRaUxDSmhiR2NpT2lKU1V6STFO
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)
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
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

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  type=sale  status=success  card=411111****1111  card_expiration_date=12/2022  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  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  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 unsuccessful sale callback 
{  id=1f34f446-fc45-11ec-a50f-0242ac120004  order_number=order-1234  order_amount=3.01  order_currency=USD  order_description=bloodline  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 refund callback 
{  id=ba290c62-fc45-11ec-9e91-0242ac120004  order_number=order-1234  order_amount=3.01  order_currency=USD  order_description=bloodline  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}

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.

RECURRING request

/api/v1/payment/reсurring

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
Example: 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 		Product price. Format: XX.XX
Pay attention that amount format depends on currency exponent.
If exponent = 0, then amount is integer (without decimals). It used for currencies: CLP, VND, ISK, UGX, KRW, JPY.
If exponent = 3, then format: xx.xxx (with 3 decimals). It used for currencies: BHD, JOD, KWD, OMR, TND.
Example: 0.19
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
merchant_key String Required Transaction status
Example: PREPARE, SETTLED, PENDING, 3DS, REDIRECT, DECLINE, REFUND, REVERSAL, CHARGEBACK
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/reсurring' \--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/reсurring' \--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"  }}

Get transaction status#

To get order status you can use GET_TRANS_STATUS request. Use payment public_id from Payment Platform in the request.

GET_TRANS_STATUS request

/api/v1/payment/status

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.
Example: Must be SHA1 of MD5 encoded string (uppercased): payment_id + merchant_pass

Response Parameters#

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, 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
order Object
number String Required Up to 255 characters 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
Example: Very important gift
customer Object
name String Required Customer's name
Example: John Doe
Example Request
GET_TRANS_STATUS request (setteled) 
curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/status' \--data-raw '{     "merchant_key":"xxxxx-xxxxx-xxxxx",   "payment_id":"63c781cc-de3d-11eb-a1f1-0242ac130006",   "hash":"{{operation_hash}}"}'
GET_TRANS_STATUS request (declined) 
curl --location -g --request POST '{{CHECKOUT_HOST}}/api/v1/payment/status' \--data-raw '{     "merchant_key":"xxxxx-xxxxx-xxxxx",   "payment_id":"03e46e96-de42-11eb-aea7-0242ac140002",   "hash":"{{operation_hash}}"}'
Example Response
Status Settled 
{    "payment_id": "24f7401c-fc47-11ec-8d07-0242ac120015",    "date": "2022-07-05 09:45:03",    "status": "settled",    "order": {        "number": "f0a51dfa-fc43-11ec-8128-0242ac120004-1",        "amount": "3.01",        "currency": "USD",        "description": "bloodline"    },    "customer": {        "name": "John Doe",        "email": "success@gmail.com"    }}
Status Declined 
{  "payment_id": "03e46e96-de42-11eb-aea7-0242ac140002",  "date": "2021-07-06 10:07:47",  "status": "decline",  "reason": "Declined by processing",  "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.

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 Transaction ID (public)
Example: dc66cdd8-d702-11ea-9a2f-0242c0a87002
amount String Optional Format: XX.XX, without leading zeroes Amount to refund. It is required for particular refund. If amount is not specified the full order amount is settled by default.
Example: 0.19
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): 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' \--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
Body 
{  "payment_id": "63c781cc-de3d-11eb-a1f1-0242ac130006",  "result": "accepted"}

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#

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

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

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 CryptoJSvar

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

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/25
CVV2 any 3 digits

Result: customer is redirected to the "success_URL"

Scenario: FAILED payment (decline)

Card data:

Card number 4111 1111 1111 1111
Expiry Date 02/25
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/25
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/25
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/25
CVV2 any 3 digits

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

Payment methods#

You can choose the payment methods that you want to display on the payment form. Use methods array in the Authentication request and specify the values that correspond to the payment methods. As well, you can use the value of the payment method to add specific parameters to the Authentification request for the paramaters object. These parameters will be sent to the acquirer to pass the necessary data for successful payment.

stcpay#

payment_method = stcpay

applepay#

payment_method = applepay

cybersource#

payment_method = cybersource