Initiate Authentication

You can initiate authentication of the payment instrument using the Initiate Authentication API. This operation is required to confirm the validity of the card number.


The Initiate Authenticate API is triggered as soon as the customer inputs the card number on the payment page and when the focus of the cursor moves out of the card number field in the form.

API Request

To perform an Initiate authentication API call, you will need to provide the following required fields.

sessionIdstringA session ID is a unique identifier that a server generates as part of the create session API call and assigns to a merchant transaction for the duration of the session (15 min). This is the Id parameter in the session object, in the response of the Create Session API call.Yes
cardNumberstringValid card number, as a string without any separators. Length of 16 for Visa, MasterCard, and Mada cards. Length of 15 for American Express cards.Yes
ReturnUrlstringThe URL where the client will be automatically redirected to once the Authentication process has been successful. Must be dynamic, based on the order being created. Must be a URL with an HTTPS protocol.Yes
merchantNamestringName of the merchant initiating the transactionNo
callbackUrlstringThe URL where the response containing order details will be returned. Must be a valid URL and must have an HTTPS protocol.No
isSetPaymentMethodEnabledbooleanIf this is set to true, then the customer is allowed to use the payment gatewayNo
isCreateCustomerEnabledbooleanIf this is set to true, then the customer account will be created and can be used for later transactions.No
paymentOperationstringType of payment operation that is carried out with this transaction

Default value: "Pay"
cardOnFilebooleanThis field only applies if you collect details of card from your payers, store them, and either you or your payers use the stored value for subsequent payments.No
restrictPaymentMethodsbooleanFlag indicating whether certain type of payment methods are restricted for this transactionNo
sourcestringSource of capturing the transaction. Use "DirectAPI" for this call.

Default value: "DirectAPI"
deviceIdentificationobjectDetails of the device used to perform a transactionNo
deviceIdentification.providerDeviceIdstringUnique identifier of the customer device used for the payment.No
deviceIdentification.languagestringThe language settings of the device or browser. ISO 639-1 code must be used

Default value: "en"
deviceIdentification.userAgentstringThe User-Agent is a characteristic string that lets servers and network peers identify the application, operating system, vendor, and/or version of the requesting user agent.No

Below is an example of executing an Initiate Authentication call for a payment with the mandatory parameters.


Amount and Currency passed in this API will not be picked up for processing

Please note the Amount and Currency for the transaction must be passed in the Create Session API only. This Session ID in this API call will be processed at the backend to pick the Amount and Currency for processing the payment.

Sample Request

curl --request POST \
     --url \
     --header 'accept: application/json' \
     --header 'authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOjI2ZDMxOTE3LTcxNWUtNDhhYy1iMDcyLWRhOTczODAxNmFmNQ==' \
     --header 'content-type: application/json' \
     --data '
  "cardNumber": "5123450000000008",
  "ReturnUrl": "",
  "callbackUrl": "",
  "paymentOperation": "Pay",
  "source": "DirectAPI",
  "deviceIdentification": {
    "providerDeviceId": "6fd571631df9d1e58269af54eeb4c1f0",
    "language": "en",
    "userAgent": "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.79 Safari/537.36"
  "sessionId": "0d5025e3-0716-47f7-33c4-08dc400edeed",
  "merchantName": "John",
  "isSetPaymentMethodEnabled": true,
  "isCreateCustomerEnabled": false,
  "cardOnFile": false,
  "restrictPaymentMethods": false

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '',
    "sessionId": "05274874-0bfe-478b-557b-08dc33dd067b",
    "cardNumber": "5123450000000008",    
    "ReturnUrl": ""
    'Content-Type: application/json',
    'Authorization: Basic NDAyMjVhODktYmUzMS00ZjJlLWExMGEtMjdiMmJiYzRlM2IzOjlmMzdkOTg1LWIzOGUtNGM5MS1iNGIyLTQxMDU1M2ZkZjA4Yg=='

$response = curl_exec($curl);

echo $response;

Upon receiving a successful response for the Initiate Authenticate API operation, use the HTML code from the redirectHtml parameter in the response to handle the redirect for the page.


Embed the redirectHtml parameter value as a hidden tag within the payment page.

You can find a full list of parameters which can be used with the Initiate Authentication API here.

API Response

The parameters sent in the API response are as follows:

orderIdThis is a unique identifier for this order to discern it from the other orders you created. This value is echoed from the request.
threeDSecureId3D Secure ID of the order created through the Authenticate Payer operation.
redirectHtmlHTML code snippet that needs to be executed by the merchant for redirection
gatewayDecisionGateway decision for request
responseMessageDetailed message associated with response from gateway
detailedResponseMessageMessage associated with response from gateway
languageLanguage used for API request
responseCodeCode associated with response message returned by the gateway
detailedResponseCodeDetailed Code associated with response message returned by the gateway

Sample Response

  "orderId": "4ae463a5-4c3a-4112-048b-08dc400ca7ad",
  "threeDSecureId": "4e24fa70-1838-44c4-adab-08dc400ca7dc",
  "redirectHtml": "<div id=\"initiate3dsSimpleRedirect\" xmlns=\"\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9tdGYuZ2F0ZXdheS5tYXN0ZXJjYXJkLmNvbS9jYWxsYmFja0ludGVyZmFjZS9nYXRld2F5LzkxZGVmOWQxMmZiNjhjYWVkOWZmYzRhZjhkZDI5ZTg3M2IwN2I4MWRlNDJiMzVjMjI4N2EzMjExNjU0ODFiNmIiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImI0YjFiODNlLTBiODktNDY1Zi05YmIwLWZmMDM0NGQ4MTZlNiJ9\" /> </form> <script id=\"initiate-authentication-script\"> var e=document.getElementById(\"initiate3dsSimpleRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
  "gatewayDecision": "ContinueToPayer",
  "responseMessage": "Success",
  "detailedResponseMessage": "The operation was successful",
  "language": "en",
  "responseCode": "000",
  "detailedResponseCode": "000"