Authentication/Sale

The merchant submits an authorization request and as a result of successful response receives the redirect_url parameter. Merchant is required to redirect the customer on encrypted checkout link received in redirect_url parameter.

API Endpoint

Request URL:      {{CHECKOUT_HOST}}/api/v1/session
Request Method:   POST
Request Body:     JSON

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.

info

If DMS-mode (two-stages payment - Auth/Capture) 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. Reference: Available Payment Methods
`success_url`	String	Required Valid URL max: 1024	URL to redirect the Customer in case of the successful payment Merchant can opt to enable parameters to be added to this url. For details, click here 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) Merchant can opt to enable parameters to be added to this url. For details, click here 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. For details, click here
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: QAR
`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" } }`

Parameters Availibility - Success/Cancel Url

The capability can be activated by reaching out to the support team. Subsequently, the received parameters in the success_url / cancel_url are as follows:

Parameter	Required	Type	Limitations	Description	Valid Value
payment_id	Y	String	UUID	Payment Public ID	45f3a510-90da-4432-9c85-257441a4361f
trans_id	Y	String	UUID	Transaction ID (operation available in transaction details)	dc66cdd8-d702-11ea-9a2f-0242c0a87002
order_id	Y	String	Up to 255 characters	Merchant Order ID	order-1234
hash	Y	String		Special signature, used to validate received data. For details, click here	0ec6e598002e9e3c0d4bcd01dec1643dd07066d8

Examples

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": "QAR",
        "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",
        "applepay"
    ],
    "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": "QAR",
        "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}}"
}
'

Response (OK)

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

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."
    }
  ]
}

Request 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":"QAR",
      "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."
    }
  ]
}

Authentication/Sale

API Endpoint​

Request Parameters​

Parameters Availibility - Success/Cancel Url​

Examples​

Possible Errors​

Parameter Values Validation​

Request Hash Validation​