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.

📘

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.

🚧

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: