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 orderId returned in the response to the Initiate Authenticate API response.

📘

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

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 CodeError Message
000Success

📘

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 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.

🚧

Note! Kindly un-escape the HTML redirection screen in order to load the 3DS screen successfully.

📘

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

To initiate an Authenticate Payer API call, you will need to provide the following required fields.

ParameterDatatypeDescription
amountfloatThe total amount for the transaction. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.
currencystringCurrency of the order for which the authentication is initiated. Please follow ISO 4217 alpha code standards for the currency code. The currency code must be 3 characters in length. The currencies must be limited to the list configured for your merchant account.
orderIdstringThis is a unique identifier for this order to discern it from the other orders 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 metadata about the order. The orderId must always be unique for every order created under your merchant profile. This must be a valid GUID.
devicestringDevice on which transaction is initiated. These details have to be dynamically extracted from the device of the customer and added to the relevant parameters of the API call. Please check the note below this table.
device.browserstringThe browser the customer uses to process the payment.
paymentMethodobjectPayment method used for the transaction. Use this to enter the card details.
paymentMethod.cardNumberstringValid card number, as a string without separators. Length of 16 for Visa, MasterCard, and Mada cards. Length of 15 for American Express cards.
paymentMethod.cardholderNamestringName on card
paymentMethod.cvvstringCard 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
paymentMethod.expiryDateobjectExpiry month and year of the card
paymentMethod.expiryDate.monthstring2 digit number for the month
paymentMethod.expiryDate.yearstring2-digit year code

🚧

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) would disallow the transaction.

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

Below is an example of executing an Authenticate Payer call for a payment of 123.21 EGP with the mandatory parameters.

curl --location 'https://api.merchant.geidea.net/pgw/api/v4/direct/authenticate/payer' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic NjYyMGMzZTItNTA4OC00MWE4LThiZTYtOThjMDAzMTUzOTMyOmY2Yzg3NGJkLTdjYTAtNGRhNi04MmVkLTQwMzkzNGViNDg4Yw==' \
--data '{
    "amount": 123.21,
    "currency": "EGP",
    "device": {
        "browser": "Webview"
    },
    "paymentMethod": {
        "cardNumber": "5123450000000008",
        "cardholderName": "test",
        "cvv": "123",
        "expiryDate": {
            "month": "05",
            "year": "39"
        }
    },
    "orderId": "b39cbef7-6dc7-441c-264a-08db103edbd0"
}'
{
    "orderId": "b39cbef7-6dc7-441c-264a-08db103edbd0",
    "threeDSecureId": "a8b9968c-42a2-4015-cb1a-08db103edbd6",
    "htmlBodyContent": "<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"style=\" height: 100vh\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"https://ap.gateway.mastercard.com/acs/mastercard/v2/prompt\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImExZWExZTMwLTkyNGYtNDZhMS1hMzBhLTgzYjg5OGE4Y2I0NiJ9\" /> </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 parameters sent in the API response are as follows:

ParameterDescription
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.
htmlBodyContentHTML code snippet that needs to be executed by the merchant for redirection
gatewayDecisionGateway decision for request
responseMessageMessage associated with response from gateway
detailedResponseMessageDetailed message 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