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.
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. 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.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:
|
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. |
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.
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).<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>
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 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.
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.You can initiate authentication by providing the following mandatory fields in the initiateAuthentication()
method:
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. |
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);
{ "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" }
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.
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.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.
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.
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.
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. |
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.
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.
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)); }
{ "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" }
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:
orderId
that you supplied in the initiateAuthentication()
and authenticatePayer()
methods.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.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>" } }
{ "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" }
For general FAQs about the 3-D Secure, see Authentication FAQs.
To test your integration you can use your TEST merchant profile in the Production environment, see Test your integration.
Copyright © 2022 Mastercard