API ReferenceDeveloper ConsoleDeveloper Community

3D Secure Transactions

Suggest Edits

3D Secure transactions are a secure method of authenticating Visa card transactions and most international cards.

This process involves redirecting the user to an external web page for authentication using methods such as OTP (One-Time Password) or any other authentication flow enabled by their bank.

This documentation outlines the steps for handling 3D Secure transactions.

📘

This flow starts when the responseCode returned in the purchase call is S0

Initiating the Transaction

To initiate a 3D Secure transaction, you need to make a call to the Card Payments API. Below is an example of the JSON request:

{
    "customerId": "1407002510",
    "amount": "2000",
    "transactionRef": "1234vvx5mnbdghgkm6s",
    "currency": "NGN",
    "authData": "NxJbhgkD3X2F957PT7A/xXkQ7ZUdNXnp7CoJC5kNc+RlvGjZ8RH5knJ1Jp7lOBb6qvOks+OjrveFQS5RqyEZXZXsjvTZKq/gJPPL/4w2bq3JpDqxsgoda5jRTma7T/tzW8EyppDVVkjgOB38S8COJSwajbaICyxyvu6J4Nfxl3inOrbb3VoVHZ1mAZiXtFhB6LSLwsqPNVORpVir+YrTXENUj5evTpk3RPc1deY+AMXD02d2+kpW7ckowcDPfmZjbW/JKYlmu1G1GuuYMulWNgwFOl224AK84kd8eQIbvMEdEINcYDSnUrEsuJK8mRienxFkyLtvKRSY/oizGFtQSg==",
    "deviceInformation": {
        "httpBrowserLanguage": "en-US",
        "httpBrowserJavaEnabled": false,
        "httpBrowserJavaScriptEnabled": true,
        "httpBrowserColorDepth": "24",
        "httpBrowserScreenHeight": "820",
        "httpBrowserScreenWidth": "360",
        "httpBrowserTimeDifference": "",
        "userAgentBrowserValue": "Mozilla/5.0 (Linux; Android 12; Infinix X6819) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Mobile Safari/537.36",
        "deviceChannel": "Browser"
    }
}

🚧

It is compulsory to collect device information from the user's browser and include it in the payment request.

A successful response would look something similar to this:

{
    "transactionRef": "1234vvx5mnbdghgkmW6s",
    "paymentId": "474486206",
    "amount": "2000.00",
    "responseCode": "S0",
    "transactionId": "4FVhyAVbqAtSTg7l3T21",
    "jwt": "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIwZjA1MTdkNC02OWZjLTQ0NTQtOGY3ZC00MjViMDEzM2IzZTgiLCJpYXQiOjE2ODQzMzM0NTksImlzcyI6IjVmZTIwZDBkNmJiMzg0MzJlYjgzNjRiOCIsIk9yZ1VuaXRJZCI6IjU1ZWYzZjgyZjcyM2FhNDMxYzk5ZTJlNiIsIlJldHVyblVybCI6Imh0dHBzOi8vcWEuaW50ZXJzd2l0Y2huZy5jb20vY29sbGVjdGlvbnMvYXBpL3YxL3BheS9jYXJkaW5hbENhbGxCYWNrIiwiUmVmZXJlbmNlSWQiOiIxMjM0dnZ4NW1uYmRnaGdrbVc2cyIsIlBheWxvYWQiOnsiQUNTVXJsIjoiaHR0cHM6Ly8xbWVyY2hhbnRhY3NzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tL01lcmNoYW50QUNTV2ViL2NyZXEuanNwIiwiUGF5bG9hZCI6ImV5SnRaWE56WVdkbFZIbHdaU0k2SWtOU1pYRWlMQ0p0WlhOellXZGxWbVZ5YzJsdmJpSTZJakl1TWk0d0lpd2lkR2h5WldWRVUxTmxjblpsY2xSeVlXNXpTVVFpT2lKaU16STJZbVF6TXkwMU5tUTBMVFJrWlRNdFlXSTFaaTA0TWpoaFpURTNZek00WkRZaUxDSmhZM05VY21GdWMwbEVJam9pTXpZNVptSmhaRGN0WkRZeU5TMDBaV1pqTFdJNVptVXROVGN5WW1aak1HVm1aamcySWl3aVkyaGhiR3hsYm1kbFYybHVaRzkzVTJsNlpTSTZJakF5SW4wIiwiVHJhbnNhY3Rpb25JZCI6IjRGVmh5QVZicUF0U1RnN2wzVDIxIn0sIk9iamVjdGlmeVBheWxvYWQiOnRydWV9.1brfCo9uaWgzpI_QTg40ajV1mKtLLs4zeYN6S3rfjy8",
    "MD": "474486206",
    "ACSUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
    "TermUrl": "https://qa.interswitchng.com/collections/api/v1/pay/cardinalCallBack",
    "eciFlag": "07"
}

3D Secure Authorization

Option A (Redirect)

To proceed with the 3D Secure authorization, you need to create an HTML form to be submitted when the page loads.

This form should be submitted to the ACSUrl value provided in the response from step one. You can choose to display the form within an iframe on your payment page or redirect the user to the provided URL.

Example HTML form:

<body onload ='form1.submit()'>
  <form id="form1" action=ACSUrl method="post">
    <input name="JWT" value={JWT}>
    <input name="MD" value={MD}>
  </form>
</body>

Make sure to replace {JWT} and {MD} with the corresponding values from the response in step one.

The form will open the Visa cardinal authorization page, where the user enters their Visa card's iPin/password and submits.

Option B (Inline HTML)

Some 3D Secure transaction authorizations don't require a redirect. What is expected is for you to parse the html returned in the response and display to the user so that they can interact with the 3D secure page to complete the authentication. The name of the field to look out for is customisedHtml

Example Response

{
    "transactionRef": "1234vv29gksm6se",
    "paymentId": "474599614",
    "bankCode": "058",
    "amount": "2000.00",
    "responseCode": "S0",
    "transactionId": "474599614",
    "customisedHtml": "<div id=\"redirectTo3ds1AcsSimple\" xmlns=\"http://www.w3.org/1999/html\"> <iframe id=\"redirectTo3ds1Frame\" name=\"redirectTo3ds1Frame\" height=\"100%\" width=\"100%\" > </iframe> <form id =\"redirectTo3ds1Form\" method=\"POST\" action=\"https://mtf.gateway.mastercard.com/acs/VisaACS/5e83f3b3-0ec0-420b-83ad-c5efe1a7916b\" target=\"redirectTo3ds1Frame\"> <input type=\"hidden\" name=\"PaReq\" value=\"eAFVUstugkAU3Zv4D4R1ZYaBsa25jkHxlYia1qapO8QJ0vKQl49tP6Yf1i/pDGhtWQDn3LmHe84FeqcoVA48y4Mk7qq6hlWFx16yDWK/q76sRq0HtceaDVjtMs7tZ+6VGWfg8Dx3fa4EW9GDxUWoqeNHrKsMltYTTxlcNJmQ1AigKxStmbdz44KB66X96ZyZOsHUAHSBEPFsajMD03tK6USKiyegmobYjThbD+fT1UQZzxZ9a7a03pSWMmwNFo4DqKqDl5RxkZ0ZbbcBXQGUWch2RbHPOwgdj0fND5ONG+7ds+YlkRb7gOQJQLcRl6UcNheOT8GWpamdDNejzbufv6YfRnlo55QcHGo7TheQPAFbt+CMYGJig2BFNzoUdwwdUMWDG8m52Hw8V74/v8id8KZhLKzXPOzl56waEOlc1P5yINLPxHquxq4I+GmfxFxIi6R/3wHdxh9MZN5eIZI1K+H6Riiukq8KUiWQoWFJXgAg2YouSxXRVIsXzL8fotn4Aa2+ujY=\" /> <input type=\"hidden\" name=\"TermUrl\" value=\"https://mtf.gateway.mastercard.com/callbackInterface/gateway/957ddcdf0729b079558ddd7fc895254dea121b745175da37ea6cc8f9ffc4d100\" /> <input type=\"hidden\" name=\"MD\" value=\"\" /> </form> <script id=\"authenticate-payer-script\"> var e=document.getElementById(\"redirectTo3ds1Form\"); if (e) { e.submit(); if (e.parentNode !== null) { e.parentNode.removeChild(e); } } </script> </div>",
    "MD": "474599614"
}

Completing the Transaction

After the user completes authentication on the 3D Secure page, they will be redirected back to your default success page.

Once the request hits the URL, you can make an API call to Authorize Transaction (3D Secure) to complete the transaction. A final successful transaction response will look like this:

{
  "paymentId":"474322315",
  "transactionId": "NO6wHD8TTVESDfmDMaB1",
  "eciFlag":"07"               
}

Redirect customer to your own URL after authentication (optional)

To control the user experience, you might decide to redirect the customer to your own website/URL after auehntication is done, before authorizing the transaction.

You can do this by specifying your callbackUrl in the original purchase call.

Here's an example:

{
    "customerId": "1407002510",
    "amount": "2000",
    "transactionRef": "1234vvx5mnbdghgkm6s",
    "currency": "NGN",
    "callbackUrl": "https://yourcallbackurl.com",
    "authData": "NxJbhgkD3X2F957PT7A/xXkQ7ZUdNXnp7CoJC5kNc+RlvGjZ8RH5knJ1Jp7lOBb6qvOks+OjrveFQS5RqyEZXZXsjvTZKq/gJPPL/4w2bq3JpDqxsgoda5jRTma7T/tzW8EyppDVVkjgOB38S8COJSwajbaICyxyvu6J4Nfxl3inOrbb3VoVHZ1mAZiXtFhB6LSLwsqPNVORpVir+YrTXENUj5evTpk3RPc1deY+AMXD02d2+kpW7ckowcDPfmZjbW/JKYlmu1G1GuuYMulWNgwFOl224AK84kd8eQIbvMEdEINcYDSnUrEsuJK8mRienxFkyLtvKRSY/oizGFtQSg==",
    "deviceInformation": {
        "httpBrowserLanguage": "en-US",
        "httpBrowserJavaEnabled": false,
        "httpBrowserJavaScriptEnabled": true,
        "httpBrowserColorDepth": "24",
        "httpBrowserScreenHeight": "820",
        "httpBrowserScreenWidth": "360",
        "httpBrowserTimeDifference": "",
        "userAgentBrowserValue": "Mozilla/5.0 (Linux; Android 12; Infinix X6819) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Mobile Safari/537.36",
        "deviceChannel": "browser"
    }
}

Updated about 1 month ago