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.

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.
cardNumberstringValid card number, as a string without any separators. Length of 16 for Visa, MasterCard, and Mada cards. Length of 15 for American Express cards.
returnUrlstringThe 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 '' \
--header 'accept: text/plain' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic NjYyMGMzZTItNTA4OC00MWE4LThiZTYtOThjMDAzMTUzOTMyOmY2Yzg3NGJkLTdjYTAtNGRhNi04MmVkLTQwMzkzNGViNDg4Yw==' \
--data '{
    "amount": 123.21,
    "currency": "EGP",
    "cardNumber": "5123450000000008",
    "returnUrl": ""
    "orderId": "b39cbef7-6dc7-441c-264a-08db103edbd0",
    "threeDSecureId": "a8b9968c-42a2-4015-cb1a-08db103edbd6",
    "redirectHtml": "<div id=\"initiate3dsSimpleRedirect\" xmlns=\"\"> <iframe id=\"methodFrame\" name=\"methodFrame\" height=\"100\" width=\"200\" > </iframe> <form id =\"initiate3dsSimpleRedirectForm\" method=\"POST\" action=\"\" 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:

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