Implementing a 3DS Integration using the 3DS JavaScript API

This guide outlines all the steps that are required to add 3DS to your gateway integration using the 3DS JavaScript (JS) API, including how to use the authentication result to process a payment.

The 3DS JS integration guidelines complement the Authentication API integration guidelines and as such must be used in conjunction with it.

Step 1: Create and Update Session

3DS JS uses session-based authentication. As a first step, you must create a session, which you can then update with the request fields and values you wish to store in the session.

You can create a session using the Create Session call. This is a server-side API call and is a prerequisite for integrating with the JS API. It returns the following fields:

  • session.id: A unique session identifier which you must provide on subsequent requests to reference session contents.
  • session.authenticationLimit: The limit on the number of transaction requests the payer's browser can submit. You can supply a value in the request or use the gateway's default. By default, the gateway sets it to 5 but you can provide a value up to 25. This limit prevents malicious users from using the authentication request as a potential carding attack, and from performing Denial of Service (DoS) attacks on your site by submitting large numbers of (potentially billable) transactions.
    Note that any authentication retries you initiate will be checked against the authentication limit.
  • session.aes256Key: The key you can use to decrypt sensitive data passed to your website via the payers's browser or mobile device.
  • session.version: You can use this field to implement optimistic locking of the session content.
  • session.updateStatus: A summary of the outcome of the last attempt to modify the session.
Update Session Request

You can add or update fields in a session using the Update Session call. It allows you to add payment and payer data into a session that can subsequently become the input to determine the risk associated with a payer in an authentication operation. The following fields are required in a session:

Parameter Existence Description
session.id or sourceOfFunds.provided.card.* or sourceOfFunds.token Required Details of the card being used for the payment.
Note that you can also use network tokens and device payment tokens as source of funds in payer authentication. For more information, see FAQs.
order.amount Required The total amount of the order.
order.currency Required The currency of the order.
transaction.id Required A unique identifier for this payment authentication.
order.id Required A unique identifier for this order.
authentication.channel Required The channel in which the authentication request is being initiated. You can specify one of the following:
  • MERCHANT_REQUESTED: If you are requesting authentication of a cardholder without the payer being available for interaction (for example, as part of processing of a recurring payment). This option is currently not supported.
  • PAYER_BROWSER: If the payer is interacting via web browser (for example, with the merchant's ecommerce web-site).
authentication.redirectResponseUrl Optional The URL to which you want to redirect the payer after completing the payer authentication process. You must provide this URL, unless you are certain that there will be no interaction with the payer.
authentication.purpose Optional By default, this field is set to "PAYMENT_TRANSACTION" to indicate that authentication is to be performed when processing a card payment. However, you can specify a different purpose to indicate non-payment authentication. See Submit a Non-Payment Authentication Request.
authentication.acceptVersions Optional The 3DS versions that you will accept for this payment. If you do not specify a version, both 3DS1 and 3DS2 will be accepted. The gateway uses 3DS2 (if supported by the issuer and the card) and falls back to 3DS1 only where 3DS2 is not available. If both are not available, the authentication will not proceed. Note that the fallback scenarios will only apply to markets with a 3DS1 extension.
order.merchantCategoryCode Optional Provide the Merchant Category Code if you want to override the default value configured on your acquirer link.
Please note that you cannot remove fields from a session but can only overwrite values for existing fields.

Step 2: Initialize the API

Reference the 3DS JS API (threeDS.js) from the gateway servers. This will place a ThreeDS object into the window/global namespace.

Once you have created a session, initialize the API using the configure( ) method. This method should be called during the page load or when the DOM is in ready state. It should be called only once for the page load. After calling this method, 3DS JS will provide configuration values as member variables.

3DS JS Initialization Request

You can initialize the 3DS JS API by invoking the configure() method, with the following mandatory fields as arguments in a map object:

  • merchantId: Your merchant identifier on the gateway.
  • sessionId: The session Id that you created using the Create Session call.
  • containerId: The <div> id in your html where the API will inject a hidden iframe.
  • callback: A function that will be invoked once the API has been initialized.
  • configuration: JSON value supporting data elements like userLanguage(Optional), REST API version (wsVersion).
Examples
Initialize API Configuration
<html>
    <head>
    <script src="https://na.gateway.mastercard.com/static/threeDS/1.3.0/three-ds.min.js"
            data-error="errorCallback"
            data-cancel="cancelCallback">
    </script>

    <script type="text/javascript">
        //The output of this call will return 'false', since the API is not configured yet
        console.log(ThreeDS.isConfigured());
        /**
        Configure method with the configuration{} parameter set and demonstrates the state change of the ThreeDS object before and after the configure method is invoked.
        */
        ThreeDS.configure({
            merchantId: {merchantId},
            sessionId: {sessionId},
            containerId: "3DSUI",
            callback: function () {
                if (ThreeDS.isConfigured())
                    console.log("Done with configure");
            },
            configuration: {
                userLanguage: "en-AU", //Optional parameter
                wsVersion: 70
            }
        });

        //The output of this call will return 'true', since the API is configured
        console.log(ThreeDS.isConfigured());

        //The output of the following code might look like "ThreeDS JS API Version : 1.2.0"
        console.log("ThreeDS JS API Version : " + ThreeDS.version);
    </script>
    </head>
    <body>
        <div id="3DSUI"></div>
    </body>
</html>

Step 3: Initiate Authentication

Once all payer and payment data has been gathered into a session, you can initiate the authentication by invoking the initiateAuthentication() method. It determines the versions of payer authentication available to you for a given card, which will be based on the following:

  • the 3DS versions configured on your merchant profile
  • the card type
  • preferences you have indicated in the request
  • the version of 3DS the card has been enrolled in, and
  • the 3DS transaction filtering rules configured by you or your payment service provider.

The operation also enables any background activities (such as a 3DS2 ACS Call) to be carried out for purposes such as gathering additional payer data to support a subsequent authenticatePayer() method.

To allow any ACS call process to complete before you attempt the authenticatePayer() method, it is recommended that you invoke the initiateAuthentication() method at the earliest opportunity in your checkout process, and act on the response immediately. This will typically be when the payer completes entering their card number on the checkout page, for example, 'onBlur' event of the Card Number input field, or when selecting a card from those recorded against their account, if your site has card-on-file capabilities. Allow at least ten seconds for the ACS Method call to complete.
Initiate Authentication Request

You can initiate authentication by providing the following mandatory fields in the initiateAuthentication() method:

  • transactionId: The unique identifier for this payment authentication.
  • orderId: The unique identifier for this order.
  • callback: The callback function.
  • optionalParams: (Optional) argument with any additional Initiate Authentication REST API request fields such as correlationId.
Initiate Authentication Response

If 3DS authentication of the payer is available, the following fields are returned in the data argument of the callback function. Otherwise, the response will include an error.

  • data.restApiResponse: Contains raw response from the Initiate Authentication REST API call.
  • data.correlationId: The last correlation Id that was used for making the Initiate Authentication REST API call. It allows you to match the response to the request.
  • data.gatewayRecommendation
  • data.authenticationVersion: Returns 3DS1 or 3DS2 if authentication is available. Note that the fallback scenarios will only apply to markets with a 3DS1 extension.

To determine the next step, check the gateway's recommendation provided in the gatewayRecommendation field. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

gatewayRecommendation Next step
DO_NOT_PROCEED Do not proceed with 3DS authentication for this card, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method.
PROCEED You can proceed to authenticate the payer using the authenticatePayer( ) method call.
Examples
Initiate Authentication Request
var optionalParams = {
    sourceOfFunds: {
        type: "CARD"
    },
    order: {
        walletProvider: "MASTERPASS_ONLINE"
    }
};

ThreeDS.initiateAuthentication({orderId}, {transactionId}, function (data) {
    if (data && data.error) {
        var error = data.error;

        //Something bad happened, the error value will match what is returned by the Authentication API
        console.error("error.code : ", error.code);
        console.error("error.msg : ", error.msg);
        console.error("error.result : ", error.result);
        console.error("error.status : ", error.status);
    } else {
        console.log("After Initiate 3DS ", data);

        //data.response will contain information like gatewayRecommendation, authentication version, etc.
        console.log("REST API raw response ", data.restApiResponse);
        console.log("Correlation Id", data.correlationId);
        console.log("Gateway Recommendation", data.gatewayRecommendation);
        console.log("HTML Redirect Code", data.htmlRedirectCode);
        console.log("Authentication Version", data.authenticationVersion);

        switch (data.gatewayRecommendation) {
            case "PROCEED":
                authenticatePayer();//merchant's method
                break;
            case "DO_NOT_PROCEED":
                displayReceipt(data);//merchant's method, you can offer the payer the option to try another payment method.
                break;
        }
    }
}, optionalParams);
Initiate Authentication Response -3DS2
{ 
   "authentication":{ 
      "3ds2":{ 
         "methodCompleted":false,
         "methodSupported":"SUPPORTED"
      },
      "redirect":{ 
         "customized":{ 
            "3DS":{ 
               "methodPostData":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA0LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS80ZjNmMGQyMjM5NzQwODE2OWIwMWFiYzg2OTQyZTY5NzBmODA2M2M0MDU4ZjAzNjNlOTFlMmJiOTNkOTA0NzU3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhYWY5YjU5ZC0yZTA0LTRjZDUtOTQzOC01OGU4MGEzNzBiNWEifQ==",
               "methodUrl":"<method_url>"
            }
         }
      },
      "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://<host_name>/acs/v2/method\" target=\"methodFrame\"> <input type=\"hidden\" name=\"threeDSMethodData\" value=\"eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA0LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS80ZjNmMGQyMjM5NzQwODE2OWIwMWFiYzg2OTQyZTY5NzBmODA2M2M0MDU4ZjAzNjNlOTFlMmJiOTNkOTA0NzU3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhYWY5YjU5ZC0yZTA0LTRjZDUtOTQzOC01OGU4MGEzNzBiNWEifQ==\" /> </form> <script>document.getElementById(\"initiate3dsSimpleRedirectForm\").submit();</script> </div>",
      "version":"3DS2"
   },
   "order":{
      "currency":"AUD",
      "status":"AUTHENTICATION_INITIATED"
   },
   "response":{
      "gatewayCode":"AUTHENTICATION_IN_PROGRESS",
      "gatewayRecommendation":"PROCEED_WITH_AUTHENTICATION"
   },
   "result":"SUCCESS",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "number":"512345xxxxxx0008"
         }
      },
      "type":"CARD"
   },
   "transaction":{
      "authenticationStatus":"AUTHENTICATION_AVAILABLE"
   },
   "version":"70"
}

Step 4: Authenticate Payer

Where the Initiate Authentication response has indicated authentication to be available (transaction.authenticationStatus=AUTHENTICATION_AVAILABLE), you can invoke the authenticatePayer() method. You should invoke this when the payer clicks the "Pay Now" button on the checkout page.

Authenticate Payer Request

You must invoke the authenticatePayer() method by providing the following mandatory fields:

  • orderId: The same orderId as the initiateAuthentication() method that preceded it.
  • transactionId: The same transactionId as the initiateAuthentication() method that preceded it.
  • callback: The callback function.
  • optionalParams: (Optional) argument with any additional Authenticate Payer REST API request fields such as billing and shipping.
Authentication Payer Response

The following fields are returned in the data argument of the callback function:

  • data.restApiResponse: Contains raw response from the Authentication Payer REST API call.
  • data.correlationId: The last correlation Id that was used for making the Authentication Payer REST API call. It allows you to match the response to the request.
  • data.gatewayRecommendation
  • data.htmlRedirectCode: The gateway always returns this field for insertion into the page displayed to the payer.

To determine the next step, check the gateway's recommendation provided in the gatewayRecommendation field returned in the callback. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

gatewayRecommendation Next step
DO_NOT_PROCEED Do not proceed with this card as authentication is declined or unavailable, but you may wish to proceed to payment without the 3DS data. Or, you can offer the payer the option to try another payment method.
PROCEED You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow).

If the gateway recommends you to PROCEED, then paste content of the htmlRedirectCode response field into the page being displayed to the payer.

Frictionless Flow

This will redirect the payer’s browser straight back to your website. You can proceed to submit a subsequent payment to the gateway. The gateway will obtain the authentication data related to the payment and will ensure that payments will only be processed where all the 3DS transaction filtering rules (configured by you or your payment service provider) have passed.

Challenge Flow

This will redirect the payer’s browser to the ACS where the issuer’s challenge UI will be presented, after which the payer will be redirected back to your web site. The following fields are returned in the callback once the payer's browser has been returned to your website.

  • orderId
  • transactionId
  • gatewayRecommendation
  • restApiResponse

You can determine the authentication outcome using the value returned in the gatewayRecommendation field. Please note that this recommendation is only based on the 3DS transaction filtering rules configured by you or your payment service provider.

gatewayRecommendation Next step
DO_NOT_PROCEED Do not proceed with this card as authentication is declined or unavailable. You can offer the payer the option to try another payment method.
PROCEED You can proceed with the payment as authentication is granted.
Authenticate Payer Response Fields

The fields returned in the restApiResponse depend on the flow in effect (frictionless vs challenge) and how the authentication request was initiated (authentication.channel).

For a session-authenticated request, the response is filtered to remove data that's not related to the payer and only whitelisted fields are returned. For more information, see Session Authenticated Operations.

Advanced Integrations

The request submitted by the payer’s browser to your website on completion of the authenticatePayer() method will be parameterized allowing you to determine the authentication outcome. The individual authentication parameters, for example, authentication.3ds2.transactionStatus.data, may be useful in an advanced integration or if you have the need to provide the authentication data in a payment processed via another gateway. See Advanced Payment Session Integrations.

Examples
Authenticate Payer Request
var optionalParams = {
    fullScreenRedirect: true,
    billing: {
        address: {
            city: "London",
            country: "GBR"
        }
    }
};
 
ThreeDS.authenticatePayer({orderId}, {transactionId}, function (data) {
    if (!data.error) {
        //data.response will contain all the response payload from the AUTHENTICATE_PAYER call.
        console.log("REST API response ", data.restApiResponse);
        console.log("HTML redirect code", data.htmlRedirectCode);
        displayReceipt(data);
    }
}, optionalParams);
 
 
function displayReceipt(apiResponse) {
    var responseBody = {
        "apiResponse": apiResponse
    };
 
    var xhr = new XMLHttpRequest();
    xhr.open('PUT', '3dsreceipt', true);
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.onreadystatechange = function () {
        if (xhr.readyState == XMLHttpRequest.DONE) {
            document.documentElement.innerHTML = this.response;
        }
    }
    xhr.send(JSON.stringify(responseBody));
}
Authenticate Payer Response - 3DS2
{
   "authentication":{
      "3ds":{
         "transactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91"
      },
      "3ds2":{
         "3dsServerTransactionId":"8c4a911c-289a-46c2-a615-887e1cc01a6a",
         "acsTransactionId":"2a8234c9-e8ac-449d-a693-97a113b491fc",
         "directoryServerId":"A000000004",
         "dsTransactionId":"6dfa4509-1bf2-425b-965b-d44dd11f5f91",
         "methodCompleted":false,
         "methodSupported":"SUPPORTED",
         "protocolVersion":"2.1.0",
         "requestorId":"test2ID",
         "requestorName":"test2Name",
         "transactionStatus":"C"
      },
      "method":"OUT_OF_BAND",
      "payerInteraction":"REQUIRED",
      "redirect":{
         "customized":{
            "3DS":{
               "acsUrl":"https://<host_name>/acs/v2/prompt",
               "cReq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9"
            }
         },
         "domainName":"<domain_name>"
      },
      "redirectHtml":"<div id=\"threedsChallengeRedirect\" xmlns=\"http://www.w3.org/1999/html\"> <form id =\"threedsChallengeRedirectForm\" method=\"POST\" action=\"https://<host_name>/acs/v2/prompt\" target=\"challengeFrame\"> <input type=\"hidden\" name=\"creq\" value=\"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9\" /> </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(); e.remove(); } </script> </div>",
      "version":"3DS2"
   },
   "correlationId":"test",
   "device":{
      "browser":"MOZILLA",
      "ipAddress":"127.0.0.1"
   },
   "merchant":"TEST_3DS2-1",
   "order":{
      "amount":100,
      "authenticationStatus":"AUTHENTICATION_PENDING",
      "creationTime":"2021-04-13T02:22:59.113Z",
      "currency":"AUD",
      "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "lastUpdatedTime":"2021-04-13T02:44:07.161Z",
      "merchantCategoryCode":"1234",
      "status":"AUTHENTICATION_INITIATED",
      "totalAuthorizedAmount":0,
      "totalCapturedAmount":0,
      "totalRefundedAmount":0,
      "valueTransfer":{
         "accountType":"NOT_A_TRANSFER"
      }
   },
   "response":{
      "gatewayCode":"PENDING",
      "gatewayRecommendation":"PROCEED"
   },
   "result":"PENDING",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "expiry":{
               "month":"1",
               "year":"39"
            },
            "number":"512345xxxxxx0008",
            "scheme":"MASTERCARD"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-13T02:44:07.161Z",
   "timeOfRecord":"2021-04-13T02:22:59.113Z",
   "transaction":{
      "acquirer":{
         "merchantId":"99554411"
      },
      "amount":100,
      "authenticationStatus":"AUTHENTICATION_PENDING",
      "currency":"AUD",
      "id":"42090084",
      "type":"AUTHENTICATION"
   },
   "version":"60"
}

Step 5: Use the Authentication Result in a Payment Operation

When the result of the authenticatePayer() method indicates that you can proceed with the payment (gatewayRecommendation=PROCEED), you may initiate an Authorize or Pay operation. In addition to the standard fields, you must provide the following fields:

  • order.id: Provide the orderId that you supplied in the initiateAuthentication() and authenticatePayer() methods.
  • authentication.transactionId: Provide the transactionId that you supplied in the initiateAuthentication() and authenticatePayer() methods. You do not need to include any of the fields in the authentication parameter group, as the gateway will use the authentication.transactionId to look up the authentication results that it stored when you asked it to perform authentication. The gateway will pass the required information to the acquirer.
Examples
Pay Request
URL https://na.gateway.mastercard.com/api/rest/version/<version>/merchant/<your_merchant_ID>/order/<your_order_ID>/transaction/<your_transaction_ID>
HTTP Method PUT 
 
{
    "apiOperation":"PAY",
    "authentication":{
        "transactionId":"<your_transaction_ID>"
    },
    "order":{
        "amount":"100",
        "currency":"AUD",
        "reference":"<your_order_ID>"
    },
    "sourceOfFunds":{
        "provided":{ 
            "card":{ 
                "number":"<card_number>",
                "expiry":{
                    "month":"1",
                    "year":"39"
                }
            }
        },
        "type":"CARD"
    },
    "transaction":{
        "reference":"<your_order_ID>"
    }
}
Pay Response - 3DS2
{
   "authentication":{
      "3ds":{
         "acsEci":"02",
         "authenticationToken":"kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
         "transactionId":"39c25b96-7bc3-4586-bee8-056479fed3af"
      },
      "3ds2":{
         "dsTransactionId":"39c25b96-7bc3-4586-bee8-056479fed3af",
         "protocolVersion":"2.1.0",
         "transactionStatus":"Y"
      },
      "transactionId":"249213216",
      "version":"3DS2"
   },
   "authorizationResponse":{
      "posData":"1605S0100130",
      "transactionIdentifier":"TidTest"
   },
   "device":{
      "browser":"MOZILLA",
      "ipAddress":"127.0.0.1"
   },
   "gatewayEntryPoint":"WEB_SERVICES_API",
   "merchant":"TEST_3DS2-1",
   "order":{
      "amount":100.00,
      "authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
      "chargeback":{
         "amount":0,
         "currency":"AUD"
      },
      "creationTime":"2021-04-13T02:11:06.102Z",
      "currency":"AUD",
      "id":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "lastUpdatedTime":"2021-04-13T02:11:57.049Z",
      "merchantAmount":100.00,
      "merchantCategoryCode":"1234",
      "merchantCurrency":"AUD",
      "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "status":"CAPTURED",
      "totalAuthorizedAmount":100.00,
      "totalCapturedAmount":100.00,
      "totalRefundedAmount":0.00
   },
   "response":{
      "acquirerCode":"00",
      "gatewayCode":"APPROVED"
   },
   "result":"SUCCESS",
   "sourceOfFunds":{
      "provided":{
         "card":{
            "brand":"MASTERCARD",
            "expiry":{
               "month":"1",
               "year":"39"
            },
            "fundingMethod":"CREDIT",
            "issuer":"<issuer>",
            "number":"512345xxxxxx0008",
            "scheme":"Mastercard",
            "storedOnFile":"NOT_STORED"
         }
      },
      "type":"CARD"
   },
   "timeOfLastUpdate":"2021-04-13T02:11:57.049Z",
   "timeOfRecord":"2021-04-13T02:11:56.973Z",
   "transaction":{
      "acquirer":{
         "batch":1,
         "id":"<acquirer_id>",
         "merchantId":"99554411"
      },
      "amount":100.00,
      "authenticationStatus":"AUTHENTICATION_SUCCESSFUL",
      "authorizationCode":"028941",
      "currency":"AUD",
      "id":"1",
      "receipt":"1908266016",
      "reference":"807a01b6-e6c8-4aa7-b8da-799bfff89496",
      "source":"INTERNET",
      "stan":"496",
      "terminal":"1234",
      "type":"PAYMENT"
   },
   "version":"60"
}

FAQs

For general FAQs about the 3-D Secure, see Authentication FAQs.

Test your Integration

To test your integration you can use your TEST merchant profile in the Production environment, see Test your integration.

Copyright © 2022 Mastercard