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 | string | 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"
}
Updated 5 months ago