Authenticate Payer

You can verify the customer’s identity using the Authenticate Payer API. This step helps to follow the 3DSecure process, through which customers would need to authenticate the card by entering an additional authentication code.

To carry out this operation, you will need the following details from other API calls:

Parameter	Datatype	Description
`sessionId`	String	A session ID is a unique identifier that a server generates as part of the response to the Create Session API call and assigns to a merchant transaction for the duration of the session (15 min). This must be a valid GUID.
`orderId`	String	This is a unique identifier for this order to discern it from others order you created. If orderId is not sent with the request, an orderId is created by the server and returned in the response. The orderid can be used to refer to this order in subsequent transactions and in retrieving meta data about the order. The orderId must always be unique for every order created under your merchant profile. This must be a valid GUID. This is generated as part of the Initiate Authentication API call.

📘
During the customer journey, the merchant redirects the customer to a page containing a form for accepting a one-time passwordTP). The customer is expected to enter the OTP and submit the form.

🚧
Merchants need to dynamically extract the device details of the browser during the transaction and pass them as part of the API payload in the device object. If the same device values are repeated, the Network Associate (Visa, MasterCard and so on) will disallow the transaction.

API Request

To initiate 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
orderId	String	This is a unique identifier for this order to discern it from others order you created. If orderId is not sent with the request, an orderId is created by the server and returned in the response. The orderid can be used to refer to this order in subsequent transactions and in retrieving meta data about the order. The orderId must always be unique for every order created under your merchant profile. This must be a valid GUID. This is generated as part of the Initiate Authentication API call.	Yes
paymentMethod	Object	Payment method used for the transaction. Use this to enter the card details. This will include the cardholder name, card number, expiry date and CVV	Yes
Yes	String	Valid card number, as a string without separators. Length of 16 for Visa, MasterCard, and Mada cards. Length of 15 for American Express cards.	Yes
paymentMethod.cardholderName	String	Name on card	Yes
paymentMethod.cvv	String	Card Verification Value. This code is usually composed of a three-digit number provided and available at the back of the card or 4 digit number above the card number on the right side on the front of the card	Yes
paymentMethod.expiryDate	Object	Expiry month and year of the card	Yes
paymentMethod.expiryDate.month	String	2 digit number for the month	Yes
paymentMethod.expiryDate.year	String	2-digit year code	Yes
deviceIdentification	Object	Attributes that uniquely identify the device. This needs providerDeviceId, language and userAgent	Yes
deviceIdentification.providerDeviceId	String	Unique identifier of the customer device used for the payment.	Yes
deviceIdentification.language	String	The language settings of the device or browser. ISO 639-1 code must be used.	Yes
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.	Yes
timeZone	Integer	Time in minutes from UTC timezone.	No
source	String	Source of capturing the transaction.	No

You can find a complete list of parameters that can be used with the Authenticate Payer API here.

📘
You can use various test cards available here to test this API.

Below is an example of executing an Authentication Payer 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/payer \
     --header 'accept: application/json' \
     --header 'authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOjI2ZDMxOTE3LTcxNWUtNDhhYy1iMDcyLWRhOTczODAxNmFmNQ==' \
     --header 'content-type: application/json' \
     --data '
{
  "source": "DirectAPI",
  "paymentMethod": {
    "cardholderName": "Ahmed",
    "cardNumber": "5123450000000008",
    "cvv": "100",
    "expiryDate": {
      "month": "01",
      "year": "39"
    }
  },
  "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"
  },
  "orderId": "09b668f7-23ff-4278-7f93-08dc400ca360",
  "sessionId": "d66bfc31-2b05-4d6b-2dc2-08dc400edeed",
  "timeZone": -480
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.merchant.geidea.net/pgw/api/v6/direct/authenticate/payer',
  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",
    "orderId": "a01e4c7a-8125-4f1b-5a52-08dc33b78153",
    "paymentMethod": {
        "cardholderName": "kanti",
        "cardNumber": "5123450000000008",
        "cvv": "100",
        "expiryDate": {
            "month": 1,
            "year": 39
        }
    },
    "deviceIdentification": {
        "providerDeviceId": "bc8e1fc68c1c6188f95947cec64ce1b0",
        "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"
    },
    "timeZone": -480,
    "source": "DirectAPI"
}',
  CURLOPT_HTTPHEADER => array(
    'accept: text/plain',
    'Content-Type: application/json',
    'Authorization: Basic NDAyMjVhODktYmUzMS00ZjJlLWExMGEtMjdiMmJiYzRlM2IzOjlmMzdkOTg1LWIzOGUtNGM5MS1iNGIyLTQxMDU1M2ZkZjA4Yg=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

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

Upon receiving a successful response for the Authenticate Payer API operation, the Payment Gateway redirects the page to the URL provided in the returnUrl parameter provided in the Initiate Authentication API operation. An error code and error message are appended as query parameters to the URL provided in the returnUrl parameter.

Error Code	Error Message
000	Success

You need to use the HTML code from the htmlBodyContent parameter and execute it in the browser or open it in a separate modal so that the 3D secure authentication process can be completed by your client.

🚧
Kindly un-escape the HTML redirection screen to load the 3DS screen successfully.

📘
For a successful Authenticate Payer API operation, the error code is ‘000’ and the message is ‘Success’. The URL of the page after redirection should look as follows :* “returnUrl?code=000&msg=Success”

You can use various test cards available here to test the following scenarios with a 3DS emulator.

Sample Response

curl --request POST \
     --url https://api.merchant.geidea.net/pgw/api/v6/direct/authenticate/payer \
     --header 'accept: application/json' \
     --header 'authorization: Basic YTA4N2Y0Y2EtOTg5MC00MDdiLTljMmYtNzYzMDgzNmNjMDIwOjI2ZDMxOTE3LTcxNWUtNDhhYy1iMDcyLWRhOTczODAxNmFmNQ==' \
     --header 'content-type: application/json' \
     --data '
{
  "source": "DirectAPI",
  "paymentMethod": {
    "cardholderName": "Ahmed",
    "cardNumber": "5123450000000008",
    "cvv": "100",
    "expiryDate": {
      "month": "01",
      "year": "39"
    }
  },
  "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"
  },
  "orderId": "09b668f7-23ff-4278-7f93-08dc400ca360",
  "sessionId": "d66bfc31-2b05-4d6b-2dc2-08dc400edeed",
  "timeZone": -480
}
'

{
    "orderId": "8362c98b-967b-4426-0496-08dc400ca7ad",
    "threeDSecureId": "e4fcb9fe-c4c0-4449-adbb-08dc400ca7dc",
    "htmlBodyContent": "<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\" style=\" height: 100vh\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"https://mtf.gateway.mastercard.com/acs/mastercard/v2/prompt\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjU0ODc2OWRlLWJjY2MtNDA2ZS04ZGM5LWRlYzBkNGIzOGQ5MyJ9\" /> </form> <iframe id=\"challengeFrame\" name=\"challengeFrame\" width=\"100%\" height=\"100%\" ></iframe> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"threedsChallengeRedirectForm\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
    "gatewayDecision": "ContinueToPay",
    "responseMessage": "Success",
    "detailedResponseMessage": "The operation was successful",
    "language": "en",
    "responseCode": "000",
    "detailedResponseCode": "000"
}

API Response

The following 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.
htmlBodyContent	HTML code snippet that needs to be executed by the merchant for redirection
gatewayDecision	Gateway decision for request
responseMessage	Message associated with response from gateway
detailedResponseMessage	Detailed 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

Authenticate Payer

📘

🚧

API Request

📘

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

Sample Request

🚧
Kindly un-escape the HTML redirection screen to load the 3DS screen successfully.

📘

Sample Response

API Response

📘

🚧

API Request

📘

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

Sample Request

🚧Kindly un-escape the HTML redirection screen to load the 3DS screen successfully.

📘

Sample Response

API Response

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

🚧
Kindly un-escape the HTML redirection screen to load the 3DS screen successfully.