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.

📘
Initiate the call to the Initiate Authenticate API 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.

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.

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

Parameter	Datatype	Description
`amount`	float	The total amount for the transaction. The amount must be greater than 0.01. Must not have more than 2 digits after the decimal point.
`currency`	string	Currency 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.
`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.
`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.

You can find a full list of parameters which can be used with the Initiate Authentication API here.

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

curl --location 'https://api.merchant.geidea.net/pgw/api/v4/direct/authenticate/initiate' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic NjYyMGMzZTItNTA4OC00MWE4LThiZTYtOThjMDAzMTUzOTMyOmY2Yzg3NGJkLTdjYTAtNGRhNi04MmVkLTQwMzkzNGViNDg4Yw==' \
--data '{
    "amount": 123.21,
    "currency": "EGP",
    "cardNumber": "5123450000000008",
    "returnUrl": "https://someurl.com"
    
}'

{
    "orderId": "b39cbef7-6dc7-441c-264a-08db103edbd0",
    "threeDSecureId": "a8b9968c-42a2-4015-cb1a-08db103edbd6",
    "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://ap.gateway.mastercard.com/acs/mastercard/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9hcC5nYXRld2F5Lm1hc3RlcmNhcmQuY29tL2NhbGxiYWNrSW50ZXJmYWNlL2dhdGV3YXkvMzlkZTU5ZmEzYzViOTNhNzMxYzk0NTE3NGI3MDE4ZTRjMWIzYmVlN2MzYzA3MDVlM2I4M2FhNGFiOTU2ZGE2NSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiYTFlYTFlMzAtOTI0Zi00NmExLWEzMGEtODNiODk4YThjYjQ2In0=\" /> </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 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

Initiate the call to the Initiate Authenticate API 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.

Embed the redirectHtml parameter value as a hidden tag within the payment page.

API Response

Embed the `redirectHtml` parameter value as a hidden tag within the payment page.