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.

Parameter	Datatype	Description	Mandatory
`sessionId`	float	A 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
`cardNumber`	string	Valid 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
`ReturnUrl`	string	The 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
`merchantName`	string	Name of the merchant initiating the transaction	No
`callbackUrl`	string	The URL where the response containing order details will be returned. Must be a valid URL and must have an HTTPS protocol.	No
`isSetPaymentMethodEnabled`	boolean	If this is set to true, then the customer is allowed to use the payment gateway	No
`isCreateCustomerEnabled`	boolean	If this is set to true, then the customer account will be created and can be used for later transactions.	No
`paymentOperation`	string	Type of payment operation that is carried out with this transaction Default value: "Pay"	No
`cardOnFile`	boolean	This 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
`restrictPaymentMethods`	boolean	Flag indicating whether certain type of payment methods are restricted for this transaction	No
`source`	string	Source of capturing the transaction. Use "DirectAPI" for this call. Default value: "DirectAPI"	No
`deviceIdentification`	object	Details of the device used to perform a transaction	No
`deviceIdentification.providerDeviceId`	string	Unique identifier of the customer device used for the payment.	No
`deviceIdentification.language`	string	The language settings of the device or browser. ISO 639-1 code must be used Default value: "en"	No
`deviceIdentification.userAgent`	string	The 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 https://api.merchant.geidea.net/pgw/api/v6/direct/authenticate/initiate \
     --header 'accept: application/json' \
     --header 'authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOjI2ZDMxOTE3LTcxNWUtNDhhYy1iMDcyLWRhOTczODAxNmFmNQ==' \
     --header 'content-type: application/json' \
     --data '
{
  "cardNumber": "5123450000000008",
  "ReturnUrl": "https://samplereturnurl.com",
  "callbackUrl": "https://www.callbackurl.com",
  "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
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.merchant.geidea.net/pgw/api/v6/direct/authenticate/initiate',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "sessionId": "05274874-0bfe-478b-557b-08dc33dd067b",
    "cardNumber": "5123450000000008",    
    "ReturnUrl": "https://webhook.site/92c440a0-4b17-4f96-ad72-bb8c91080f05"
}
',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic NDAyMjVhODktYmUzMS00ZjJlLWExMGEtMjdiMmJiYzRlM2IzOjlmMzdkOTg1LWIzOGUtNGM5MS1iNGIyLTQxMDU1M2ZkZjA4Yg=='
  ),
));

$response = curl_exec($curl);

curl_close($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:

Parameter	Description
orderId	This is a unique identifier for this order to discern it from the other orders you created. This value is echoed from the request.
threeDSecureId	3D Secure ID of the order created through the Authenticate Payer operation.
redirectHtml	HTML code snippet that needs to be executed by the merchant for redirection
gatewayDecision	Gateway decision for request
responseMessage	Detailed message associated with response from gateway
detailedResponseMessage	Message associated with response from gateway
language	Language used for API request
responseCode	Code associated with response message returned by the gateway
detailedResponseCode	Detailed 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=\"http://www.w3.org/1999/html\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"https://mtf.gateway.mastercard.com/acs/mastercard/v2/method\" 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"
}

📘

API Request

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

Sample Request

📘

API Response

Sample Response

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