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:

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.

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:

⚠️ 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:

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:

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.

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​

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": "[email protected]"
  },
  "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}}"
}
'

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": "[email protected]"
    },
    "billing_address": {
      "country": "US",
      "state": "CA",
      "city": "Los Angeles",
      "disctrict": "Beverlywood",
      "address": "Moor Building 35274",
      "house_number": "17/2",
      "zip": "123456",
      "phone": "347771112233"
    },
    "card_token": [
      "f5d6a0ab6fcfb6487a39e2256e50fff3c95aaa97075ee5e539bb662fceff4dc1"
    ],
    "req_token": true,
    "hash": "{{session_hash}}"
  }
}
'

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":"[email protected]"
    },
    "payee": {
        "name":"John Doe",
        "email":"[email protected]"
        },
    "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}}"
}
'

{
  "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.

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":"[email protected]"
   },
   "recurring_init": "true",
   "hash":"728d13b95cf2b6b3ee04b20dc2fc9889ffff1cf4"
}
'

{
  "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.

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"
}
'

{
  "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:

⚠️ 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:

* 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​

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&
[email protected]&
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

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&
[email protected]&
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

 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&
 [email protected]&
 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

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&
[email protected]&
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&
[email protected]&
payee_country=US&
payee_state=California&
payee_city=Los Angeles&payee_address=Moor Building 35274 State ST Fremont. U.S.A

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&
[email protected]&
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

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&
[email protected]&
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

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&
[email protected]&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

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&
[email protected]&
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&
[email protected]&
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

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​

Response Parameters​

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": "[email protected]"
    },     
       "recurring_init_trans_id":"dc66cdd8-d702-11ea-9a2f-0242c0a87002", 
       "recurring_token":"9a2f-0242c0a87002",
       "schedule_id":"57fddecf-17b9-4d38-9320-a670f0c29ec0", 
       "hash":"{{session_hash}}"
}'

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": "[email protected]"
    }
}'

{
  "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",
  "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​

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​

{
  "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​

Response Parameters by payment_id​

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}}"
}
'

{
  "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": "[email protected]"
  }
}

{
  "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": "[email protected]"
  }
}

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​

Response Parameters by order_id​

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}}"
}
'

{
    "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": "[email protected]"
    }
}

{
  "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": "[email protected]"
  }
}

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​

Response Parameters​

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}}"
}
'

{
  "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​

Response Parameters​

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}}"
}
'

{
  "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"
  }
}

{
  "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.

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.

card​

If the payer chooses the card payment method, fields with card data will be displayed on the Checkout page.

For some connector services, it is necessary to send additional parameters in the Authenticaion request for the paramaters object (for more information, contact your manager).

Additional parameters - Set 1 (BNG)​

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"
    ],
        "parameters": {
                "card": {
            "bnrg_installm_def": "03",
            "bnrg_installm_months": "03",
            "bnrg_installm_plan": "03"
        }
    },   
    "order": {
        "number": "order-1234",
        "amount": "1000.19",
        "currency": "MXN",
        "description": "Important gift"
    },
    "cancel_url": "https://example.com/cancel",
    "success_url": "https://example.com/success",
     "customer": {
        "name": "John Doe",
        "email": "[email protected]"
    },
    "billing_address": {
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "address": "Moor Building 35274",
        "zip": "123456",
        "phone": "347771112233"
    },
    "hash": "{{session_hash}}",
}
'

Additional parameters - Set 2 (FCP)​

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"
    ],
        "parameters": {
                "card": {
            "document_type": "cpf",
            "document_number": "231.002.999-00",
            "social_name": "Harry Potter",
            "fiscal_country": "BR",
            "toBankAccountId": "a1a1134a-32c6-442c-90c9-66b587d5be00"
        }
    },   
    "order": {
        "number": "order-1234",
        "amount": "1000.19",
        "currency": "BRL",
        "description": "Important gift"
    },
    "cancel_url": "https://example.com/cancel",
    "success_url": "https://example.com/success",
     "customer": {
        "name": "John Doe",
        "email": "[email protected]"
    },
    "billing_address": {
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "address": "Moor Building 35274",
        "zip": "123456",
        "phone": "347771112233"
    },
    "hash": "{{session_hash}}",
}'

Additional parameters - Set 3 (LBP)​

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"
    ],
        "parameters": {
                "card": {
            "descriptor": "Testy International LTD"
        }
    },   
    "order": {
        "number": "order-1234",
        "amount": "1000.19",
        "currency": "BRL",
        "description": "Important gift"
    },
    "cancel_url": "https://example.com/cancel",
    "success_url": "https://example.com/success",
     "customer": {
        "name": "John Doe",
        "email": "[email protected]"
    },
    "billing_address": {
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "address": "Moor Building 35274",
        "zip": "123456",
        "phone": "347771112233"
    },
    "hash": "{{session_hash}}",
}
'

Additional parameters - set 4 TWD​

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"
  ],
  "parameters": {
    "card": {
      "customer_phone": "1234567890",
      "customer_telnocc ": "123",
      "shipping_street1": " Moor Building 35274",
      "shipping_ city": "Los Angeles",
      "shipping_state": "CA",
      "shipping_postcode": "809654321",
      "shipping_ country": "US"
    }
  },
  "order": {
    "number": "order-1234",
    "amount": "1000.19",
    "currency": "USD",
    "description": "Important gift"
  },
  "cancel_url": "https://example.com/cancel",
  "success_url": "https://example.com/success",
  "customer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "billing_address": {
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "address": "Moor Building 35274",
    "zip": "123456",
    "phone": "347771112233"
  },
  "hash": "{{session_hash}}"
}
'

Additional parameters - Set 5 (ERS)​

This set should be used for debit operation.

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"
  ],
  "parameters": {
    "card": {
      "payer_identity_type": "Passport",
      "payer_identity_id": "ABC123456",
      "payer_identity_country": "KZ",
      "payer_identity_exp_date": "2026-05-15",
      "payer_nationality": "Kazakhstani",
      "payer_country_of_birth": "Kazakhstan",
      "payee_first_name": "John",
      "payer_last_name": "Doe",
      "payee_middle_name": "Smith",
      "payee_address": "123 Main Street",
      "payee_city": "Almaty",
      "payee_state": "Almaty Province",
      "payee_country": "Kazakhstan",
      "payee_zip": "050000",
      "payee_phone": "77123456789",
      "payee_birth_date": "1990-01-01",
      "payee_identity_type": "National ID",
      "payee_identity_id": "XYZ987654",
      "payee_identity_country": "Kazakhstan",
      "payee_identity_exp_date": "2030-12-31",
      "payee_nationality": "Kazakhstani",
      "payee_country_of_birth": "Kazakhstan"
    }
  },
  "order": {
    "number": "order-1234",
    "amount": "1000.19",
    "currency": "USD",
    "description": "Important gift"
  },
  "cancel_url": "https://example.com/cancel",
  "success_url": "https://example.com/success",
  "customer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "billing_address": {
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "address": "Moor Building 35274",
    "zip": "123456",
    "phone": "347771112233"
  },
  "hash": "{{session_hash}}"
}
'

afsbenefit​

payment_method = afsbenefit

airtel​

payment_method = airtel

paydefi​

If the payer chooses the allpay payment method, the customer’s confirmation via app may be necessary to finish the payment.

Apple Pay​

To use the applepay payment method, configure the Wallets setting in the admin dashboard. Ensure that the payment provider has confirmed the Apple Pay certificates and verified your domain in the Apple Pay account.

To enable payers to make Apple Pay payments, you can either connect to the Checkout page or work directly via the S2S protocol:

Checkout Page: No additional development is required on your side.

S2S Protocol: You must be able to obtain the Apple Pay payment token and include it in the SALE request.

Regardless of the protocol you have to make settings in the admin panel and set the following configurations:

• Merchant Identifier, Country and Shop Name – according to the merchant’s data from Apple Pay Developer account
  
• Certificate and Private Key – generated Apple Pay certificate and private key
  
• Merchant Capabilities and Supported Networks – configurations for Apple Pay payments
  
• Processing Private Key – private key that uses for payment token decryption (requires if payment provider supports).
  

We also recommend checking out the demo provided by Apple for Apple Pay: https://applepaydemo.apple.com/

Set up Apple Pay

If you are using the Checkout protocol for Apple Pay payments, you will need to configure your Apple Developer account. Follow these steps to set up Apple Pay in your Apple Developer account:

1. Create a Merchant ID in the "Certificates, Identifiers & Profiles" section.

2. Register and verify the domains involved in the interaction with Apple Pay (e.g., the checkout page URL where the Apple Pay button is placed) in the "Merchant Domains" section. Download the verification file and provide it to support to complete the domain verification.

3. Create a Merchant Identity Certificate in the "Merchant Identity Certificate" section:

• Generate a pair of certificates (*.csr and *.key) and upload the *.csr file in the "Merchant Identity Certificate" section.
• Create a Merchant Identity Certificate based on the generated CSR file.
• Download the *.pem file from the portal.

⚠️ Note

The *.csr file can be obtained from the payment provider that processes Apple Pay, and the *.pem file should be uploaded to your payment provider's dashboard, following their instructions.

4. Create a Processing Private Key in the "Apple Pay Payment Processing Certificate" section:

• Generate a pair of certificates (*.csr and *.key) and upload the *.csr file.
• Create a Payment Processing Certificate based on the generated CSR file.

For more detailed instructions on setting up Apple Pay, refer to the following resource: Learn more about setting up Apple Pay

Next, enter the data from your Apple Pay developer account into the platform's admin panel: Go to the "Merchants" section, initiate editing, open the "Wallets" tab, navigate to the Apple Pay settings, and fill in the following fields:

• Merchant Identifier: Enter the Merchant ID.
• Certificate: Upload the *.pem file downloaded from the "Merchant Identity Certificate" section.
• Private Key: Upload the *.key file from the certificate pair generated for the Merchant Identity Certificate.
• Processing Private Key (required for token decryption): Paste the text from the Processing Private Key file. Ensure it is a single line of text (without spaces or breaks) placed between "BEGIN" and "END."

Apple Pay Payment Flow

By default, all Apple Pay payments on the platform are classified as virtual. As a result:

• Card details are not stored for these transactions.
• Functionality is limited for DMS payments and the creation of recurring transactions.
  

You can maximize the benefits of Apple Pay payments by leveraging card flow for digital wallets:

• Access to post-transaction operations, such as capture in DMS mode
• Support for recurring payments (MIT) – scheduled or on-demand
• Smart routing for optimized payment processing
• Payment cascading for improved success rates

Note! Ensure your provider supports these operations.

To access the card flow for Apple Pay payments, you need to:

• Set up the Processing Private Key in the admin panel settings ("Merchants" section → "Wallets" tab) to enable token decryption.
• Verify that your payment provider supports card flow processing (ask your support if available).
  

How It Works:

• If both requirements are met, the system will always decrypt the Apple Pay token during payment and store the decrypted card data for future transactions.
• You can view decrypted card details in the Transaction Details section of the admin panel.
• If any requirement is not met, the payment will be processed using the virtual flow instead.
• If your provider supports card flow but does not accept decrypted data, platform can still store the card details for processing. However, some features (e.g., smart routing and cascading) will not be available.

araka​

payment_method = araka

astropay​

If the payer chooses the astropay payment method, the redirection to another page will happen to finish the payment.

awcc​

You can add to the Authentication request a specific list of parameters which are possible for the awcc payment method.

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": [
        "awcc"
    ],
        "parameters": {
                "awcc": {
            "network_type": "eth",
            "bech32": "false"
        }
    },   
    "order": {
        "number": "order-1234",
        "amount": "1000.19",
        "currency": "BRL",
        "description": "Important gift"
    },
    "cancel_url": "https://example.com/cancel",
    "success_url": "https://example.com/success",
     "customer": {
        "name": "John Doe",
        "email": "[email protected]"
    },
    "billing_address": {
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "address": "Moor Building 35274",
        "zip": "123456",
        "phone": "347771112233"
    },
    "hash": "{{session_hash}}",
}
'

axxi-cash​

If the payer chooses the axxi-cash payment method, the ID document field will be additionally displayed on the Checkout page. After the Pay button is clicked, the payer will be redirected to the page with the PDF payment ticket.

axxi-transfer​

If the payer chooses the axxi-transfer payment method, the additional fields will be displayed on the Checkout page. The set of the fields depends on the payer's billing country.

There is a list of possible additional fields on the Checkout page:

• Choose your bank ;
• Person Type ;
• Document Type ;
• ID document .

A list of the fields depends on payer's country.

After the fields are filled, the payer will be redirected to the bank's site to complete the transfer.

However, for some billing countries (for example, Mexico), redirection does not happen. Instead, the payment details will be displayed on the Checkout page. The payer needs to use them in order to complete the transfer directly at the bank.

axxi-pin​

If the payer chooses the axxi-pin payment method, the PIN voucher field will be displayed on the Checkout page. The payer should fill in the field to redeem the voucher and see the message with the result of the operation.

a2a_transfer​

payment_method = a2a_transfer

beeline​

If the payer chooses the beeline payment method, it needs to be specified the phone numbers of payer and (optionally) of receiver. The OTP code will be sent to the payer to confirm the payment.

billplz​

If the payer chooses the billplz payment method, the customer’s confirmation via app may be necessary to finish the payment. You can add to the Authentication request a specific list of parameters which are possible for the billplz payment method.

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": [
    "billplz"
  ],
  "parameters": {
    "billplz": {
      "bank_code": "DUMMYBANKVERIFIED",
      "bank_account_number ": "232673199763"
    }
  },
  "order": {
    "number": "order-1234",
    "amount": "1000.19",
    "currency": "MYR",
    "description": "Important gift"
  },
  "cancel_url": "https://example.com/cancel",
  "success_url": "https://example.com/success",
  "customer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "billing_address": {
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "address": "Moor Building 35274",
    "zip": "123456",
    "phone": "347771112233"
  },
  "hash": "{{session_hash}}"
}
'

bitolo-inr​

payment_method = bitolo-inr

bitolo-brl​

payment_method = bitolo-brl

bpwallet​

If the payer chooses the bpwallet payment method, the redirection to another page will happen to finish the payment.

cardpaymentz​

If the payer chooses the cardpaymentz payment method, the redirection to another page will happen to finish the payment.

citizen​

payment_method = citizen

cnfmo​

If the payer chooses the cnfmo payment method, the redirection to another page will happen to finish the payment.

coinspaid​

payment_method = coinspaid

cup-on​

payment_method = cup-on

crypto-btg​

Use the crypto-btg payment method to perform cryptocurrency payments without specifying a fixed amount. If the payer selects the crypto-btg payment method, a crypto wallet address will be generated and displayed at checkout.

cybersource​

payment_method = cybersource

dcp​

If the payer chooses the dcp payment method, the redirection to another page will happen to finish the payment.

dl​

If the payer chooses the dl payment method, the redirection to another page will happen to finish the payment. The following parameter is required:

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": [
    "dl"
  ],
  "parameters": {
      "dl": {
        "document_number": "document_number"
      }
   },
  "order": {
    "number": "order-1234",
    "amount": "100",
    "currency": "USD",
    "description": "Important gift"
  },
  "cancel_url": "https://example.domain.com/cancel",
  "success_url": "https://example.domain.com/success",
  "customer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "billing_address": {
    "country": "BR",
    "city": "city",
    "address": "address",
    "house_number": "17/2",
    "zip": "123456",
    "phone": "347771112233"
  },
  "hash": "{{session_hash}}"
}'

dlocal​

If the payer chooses the dlocal payment method, the redirection to another page will happen to finish the payment. The following parameter is required:

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": [
    "dlocal"
  ],
  "parameters": {
      "dlocal": {
        "document_number": "document_number"
      }
   },
  "order": {
    "number": "order-1234",
    "amount": "100",
    "currency": "USD",
    "description": "Important gift"
  },
  "cancel_url": "https://example.domain.com/cancel",
  "success_url": "https://example.domain.com/success",
  "customer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "billing_address": {
    "country": "BR",
    "city": "city",
    "address": "address",
    "house_number": "17/2",
    "zip": "123456",
    "phone": "347771112233"
  },
  "hash": "{{session_hash}}"
}'

doku-hpp​

If the payer chooses the doku-hpp payment method, the redirection to another page will happen to finish the payment. You can add to the Authentication request a specific list of parameters which may be required for the doku-hpp payment method.

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": [
    "doku-hpp"
  ],
  "parameters": {
    "doku-hpp`": {
      "product_reference_id": "1",
      "product_name": "Fresh flowers",
      "product_quantity": "1",
      "product_sku": "FF01",
      "product_category": "gift-and-flowers",
      "product_url": "http://example.com/",
      "product_image_url": "http://example.com/",
      "product_type": "ABC"
    }
  },
  "order": {
    "number": "order-1234",
    "amount": "1000",
    "currency": "IDR",
    "description": "Important gift"
  },
  "cancel_url": "https://example.com/cancel",
  "success_url": "https://example.com/success",
  "customer": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "billing_address": {
    "country": "US",
    "state": "CA",
    "city": "Los Angeles",
    "address": "Moor Building 35274",
    "zip": "123456",
    "phone": "347771112233"
  },
  "hash": "{{session_hash}}"
}
'

dpbanktransfer​

If the payer chooses the dpbanktransfer payment method, the additional information must be provided by the payer on the Checkout page.

The payer should enter the details about the beneficiary and select an account from the list of accounts available for transfer.

The confirmation code can be requested at any stage of the transfer.

e-xezine​

payment_method = e-xezine

fairpay​

If the payer chooses the fairpay payment method, the set of the fields on the Checkout page depends on the payer's billing country. Personal Identification Number is required if payer specifies one of the following countries: Brazil, Chile, and Colombia.

fawry​

If the payer chooses the fawry payment method, the customer’s confirmation via app may be necessary to finish the payment.

fxmb-india​

payment_method = fxmb-india

fxmb-netbanking​

payment_method = fxmb-netbanking

gigadat​

If the payer chooses the gigadat payment method, the redirection to another page will happen to finish the payment.

Google Pay​

To provide the payers with the possibility of Google Pay™ payment you can connect to the Checkout or work directly via S2S protocol.

If you are using Checkout integration to work with googlepay payment method, it requires no additional code implementation.

If you are using S2S integration to work with googlepay payment method, you must be able to obtain the Google Pay payment token and include it in the SALE request.

To work with Google Pay™ payments through gateway, you need to make settings in the admin panel. You can set the following configurations:
• choose the environment: TEST or PRODUCTION
• specify "Allowed Auth Method" - PAN_ONLY or CRYPTOGRAM_3DS
• determine "Supported Networks" - MASTERCARD, VISA, AMEX, DISCOVER, JCB
These configuration will be applied and used when platform interacts with Google Pay.

⚠️ Pay attention

in the case of PAN_ONLY, the responsibility for passing 3ds is transferred to the acquirer, through which the payment is processed

Set up Google Pay

To set up Google Pay, you first need to determine who acts as the gateway when processing payments: the platform or the payment provider. This depends on which side decrypts the Google Pay payment token.

• If the platform decrypts the token and then sends the decrypted payment data to the payment provider, the platform acts as the gateway.
• If the payment provider decrypts the token (i.e., expects to receive an encrypted payment token in the payment request), the payment provider is the gateway.

The gateway (whether it is the platform or the payment provider processing Google Pay) must provide the following information:

• Gateway: The name of the gateway.
• Gateway Merchant ID: The merchant identifier in the gateway's system.

⚠️ Note

If the payment provider is the gateway, it is important to clarify whether they expect the token to include additional information, such as the payer's address or phone number.

The next step is to enter the data into the admin panel.

Go to the "Merchants" section, initiate editing, open the "Wallets" tab, navigate to the Google Pay settings, and fill in the following fields:

• Merchant Identifier: Enter the identifier from the Google Business Console. If the platform is the gateway, you can duplicate the Gateway Merchant ID here.
• Gateway: The gateway for interaction with Google Pay.
• Gateway Merchant ID: The merchant identifier in the Google gateway.
• Private Key (required for decrypted token): The key for decrypting the payment token. If the platform is the gateway, the key should be provided by the platform. If the payment provider is the gateway, the key is not required.
• Include Additional Parameters to Google Token: Depending on the payment provider's requirements.

Additionally, to work with Google Pay payments, you must verify the checkout domains from which Google Pay is processed in the Google Business Console. For domain verification, you may need to contact support.

Google Pay Payment Flow

By default, all Google Pay payments on the platform are classified as virtual. As a result:

• Card details are not stored for these transactions.
• Functionality is limited for DMS payments and the creation of recurring transactions.
  

You can maximize the benefits of Google Pay payments by leveraging card flow for digital wallets:

• Access to post-transaction operations, such as capture in DMS mode
• Support for recurring payments (MIT) – scheduled or on-demand
• Smart routing for optimized payment processing
• Payment cascading for improved success rates

Note! Ensure your provider supports these operations.

To access the card flow for Google Pay payments, you need to:

• Set up the Private Key in the admin panel settings ("Merchants" section → "Wallets" tab) to enable token decryption.
• Verify that your payment provider supports card flow processing (ask your support if available).
  

How It Works:

• If both requirements are met, the system will always decrypt the Google Pay token during payment and store the decrypted card data for future transactions.
• You can view decrypted card details in the Transaction Details section of the admin panel.
• If any requirement is not met, the payment will be processed using the virtual flow instead.
• If your provider supports card flow but does not accept decrypted data, platform can still store the card details for processing. However, some features (e.g., smart routing and cascading) will not be available.

hayvn​

If the payer chooses the hayvn payment method, it needs to be specified the crypto currency for payment. After creating a payment, the payer will be shown the data necessary to complete the transaction.

helio​

If the payer chooses the helio payment method, the redirection to widget page will happen to finish the payment.

help2pay​

payment_method = help2pay

ideal_crdz​

If the payer chooses the ideal_crdz payment method, the redirection to another page will happen to finish the payment.

instant-bills-pay​

If the payer chooses the instant-bills-pay payment method, the redirection to another page will happen to finish the payment.

ipasspay​

payment_method = ipasspay

jvz​

If the payer chooses the jvz payment method, the confirmation necessary to finish the payment via APP.

kashahpp​

If the payer chooses the kashahpp payment method, the redirection to another page will happen to finish the payment.

m2p-debit​

You should add to the Authentication request a specific list of parameters in the “parameters” object that are needed for the
m2p-debit payment method.

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": [
        "m2p-debit"
    ],
        "parameters": {
                "m2p-debit": {
            "paymentGatewayName": "gateway",
            "paymentCurrency": "BTC",
            "tradingAccountLogin": "login"
        }
    },   
    "order": {
        "number": "order-1234",
        "amount": "1000.19",
        "currency": "BRL",
        "description": "Important gift"
    },
    "cancel_url": "https://example.com/cancel",
    "success_url": "https://example.com/success",
     "customer": {
        "name": "John Doe",
        "email": "[email protected]"
    },
    "billing_address": {
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "address": "Moor Building 35274",
        "zip": "123456",
        "phone": "347771112233"
    },
    "hash": "{{session_hash}}",
}
'