# EMV 3-D Secure with the EMV 3-D Secure JavaScript API source: https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md This topic outlines all the steps that are required to add EMV 3-D Secure to your Mastercard Gateway integration using the [EMV 3-D Secure JavaScript(JS)](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/js-libraries/three-ds/index.md) API, including how to use the authentication result to process a payment. To view examples of the API requests and responses used in the EMV 3-D Secure flow with the EMV 3-D Secure JavaScript API, download the [Postman collection](https://www.postman.com/mastercard/mastercard-developers/collection/4fakvrd/mastercard-gateway-api). For more information about some generic EMV 3-D Secure features you can take advantage of in your integration, see [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#faqs). After you have completed your integration, see [Testing your EMV 3-D Secure Integration](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/test-3ds-int/index.md) to test it. ## Prerequisites {#prerequisites} To use EMV 3-D Secure with the EMV 3-D Secure JS API: * Implement your basic [Hosted Session](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/index.md) integration. * Implement any [subsequent payment operations](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/integrate-hosted-session/subsequent-operations/index.md) you want to use with the created session. * [Use your session](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/integrate-hosted-session/create-payment-session/index.md#using-a-session-in-a-payment-transaction) before you proceed with the session to authenticate. ## Step 1: Create and update session {#step-1-create-and-update-session} EMV 3-D Secure JS uses session-based authentication. For more information about the session-based authentication, see Authentication Options. 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](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) request. This is a server-side API request and is a prerequisite for integrating with the JS API. It returns the following fields: * `session.id` Unique session identifier which you must provide on subsequent requests to reference session contents. * `session.authenticationLimit` 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. Warning: Any authentication retries you initiate are checked against the authentication limit. * `session.aes256Key` Key you can use to decrypt sensitive data passed to your website through the payer's browser or mobile device. * `session.version` Session version. You can use this field to implement optimistic locking of the session content. * `session.updateStatus` Summary of the outcome of the last attempt to modify the session. After you have created the session, you can add or update fields in a session using the [UPDATE SESSION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#session) request. This 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 table defines commonly used fields in a session. ### Session fields {#session-fields} | Field | Required/Optional | Description | |--------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `session.id` or `sourceOfFunds.provided.card.*` or `sourceOfFunds.token` | Required | Details of the card being used for the payment. You can also use network tokens and device payment tokens as source of funds in payer authentication. For more information, see [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#faqs). | | `order.amount` | Required | Total amount of the order. | | `order.currency` | Required | Currency of the order. | | `transaction.id` | Required | Unique identifier for this payment authentication. | | `order.id` | Required | Unique identifier for this order. | | `authentication.channel` | Required | Channel in which the authentication request is being initiated. You can specify one of the following: **MERCHANT_REQUESTED** : Denotes that you are requesting authentication of a cardholder without the payer being available for interaction. For example, as part of processing a recurring payment. This option is currently not supported. **PAYER_BROWSER**: Denotes that the payer is interacting through a web browser. For example, with the merchant's e-commerce web site. | | `authentication.redirectResponseUrl` | Required | URL to which you want to redirect the payer after completing the payer authentication process. You do not need to provide this URL if you are certain that there will be no interaction with the payer. | | `authentication.purpose` | Optional | Purpose of the authentication. 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. If you are establishing a payment agreement and not processing a payment along with it, provide **ADD_CARD** as the authentication purpose. See [How can I submit a Non-Payment Authentication Request?](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#faqs) Agreement details must be provided. | | `authentication.acceptVersions` | Optional | EMV 3-D Secure versions that you accept for this payment. If you do not specify a version, 3DS2 is accepted. The gateway uses 3DS2 if supported by the issuer and the card. If 3DS2 is not available, the authentication does not proceed. | | `order.merchantCategoryCode` | Optional | Merchant category code. Provide the value if you want to override the default value configured on your acquirer link. | Warning: You cannot remove fields from a session. You can only overwrite values for existing fields. ## Step 2: Initialize the API {#step-2-initialize-the-api} Reference the EMV 3-D Secure JS API (threeDS.js) from the gateway servers. This places a ThreeDS object into the window/global namespace. Once you have created a session, initialize the EMV 3-D Secure JS API using the [configure()](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/js-libraries/three-ds/index.md) function, with the following mandatory arguments in the threedsConfig map object: * `merchantId` Your merchant identifier on the gateway. * `sessionId` Session ID that you created using the CREATE SESSION request. * `containerId` ID in your HTML code where the API injects a hidden iframe. * `callback` Function to be invoked once the API has been initialized. * `configuration` JSON value supporting data elements like userLanguage (payment page language displayed to the user; optional) and wsVersion (API version). ### Initialize API configuration code example {#initialize-api-configuration-code-example} ```html
``` ## Step 3: Initiate authentication {#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()](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/js-libraries/three-ds/index.md) function. It calls the [INITIATE AUTHENTICATION](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#authentication) request of the [Payer Authentication API](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md) and determines the versions of payer authentication available to you for a given card, based on the following: * EMV 3-D Secure versions configured on your merchant profile * Card type * Preferences you have indicated in the request * Version of EMV 3-D Secure the card has been enrolled in * EMV 3-D Secure transaction filtering rules configured by you or your payment service provider (PSP) The function 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()` function. Warning: To allow any ACS call process to complete before you attempt the `authenticatePayer()` function, invoke the initiateAuthentication() function at the earliest opportunity in your checkout process, and act on the response immediately. The earliest opportunity is typically when the payer completes entering their card number on the checkout page, for example, the [onBlur](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/js-libraries/three-ds/index.md) 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 10 seconds for the ACS method call to complete. You can initiate authentication by calling the `initiateAuthentication()` function with the following mandatory arguments: * `transactionId` Unique identifier for this payment authentication. * `orderId` Unique identifier for this order. * `callback` Callback function. * `optionalParams (optional)` Additional fields, such as correlationId. If EMV 3-D Secure authentication of the payer is available, the following fields are returned in the data argument of the callback function. Otherwise, the response includes an error. * `data.restApiResponse` Raw response from the Initiate Authentication REST API call. * `data.correlationId` 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` Recommendation on your next actions, based on the EMV 3-D Secure transaction filtering rules configured by you or your PSP: * **PROCEED** : You can proceed to [Step 4](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md#step-4-authenticate-payer) to authenticate the payer. * **RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS**: Ask the payer for alternative payment details, for example, a new card or another payment method and resubmit the request with the new details. Do not resubmit the same request. * `data.authenticationVersion` Return 3DS2 if authentication is available. ### Initiate authentication request and response example {#initiate-authentication-request-and-response-example} ```js var optionalParams = { sourceOfFunds: { type: "CARD" } }; 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, and so on. 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 "RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS": tryOtherPayment(); // Ask the payer to select a different payment method break; } } }, optionalParams); ``` ```json { "authentication": { "3ds2": { "methodCompleted": false, "methodSupported": "SUPPORTED" }, "redirect": { "customized": { "3DS": { "methodPostData": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9xYTA0LmdhdGV3YXkubWFzdGVyY2FyZC5jb20vY2FsbGJhY2tJbnRlcmZhY2UvZ2F0ZXdheS80ZjNmMGQyMjM5NzQwODE2OWIwMWFiYzg2OTQyZTY5NzBmODA2M2M0MDU4ZjAzNjNlOTFlMmJiOTNkOTA0NzU3IiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhYWY5YjU5ZC0yZTA0LTRjZDUtOTQzOC01OGU4MGEzNzBiNWEifQ==", "methodUrl": "" } } }, "redirectHtml": "
/acs/v2/method\" target=\"methodFrame\">
", "version": "3DS2" }, "order": { "currency": "AUD", "status": "AUTHENTICATION_INITIATED" }, "response": { "gatewayCode": "AUTHENTICATION_IN_PROGRESS", "gatewayRecommendation": "PROCEED" }, "result": "SUCCESS", "sourceOfFunds": { "provided": { "card": { "number": "512345xxxxxx0008" } }, "type": "CARD" }, "transaction": { "authenticationStatus": "AUTHENTICATION_AVAILABLE" }, "version": "72" } ``` ## Step 4: Authenticate payer {#step-4-authenticate-payer} If the INITIATE AUTHENTICATION response has indicated authentication to be available (**transaction.authenticationStatus=AUTHENTICATION_AVAILABLE** ), you can authenticate the payer. Invoke the `authenticatePayer()` function when the payer clicks the Pay Now button on the checkout page. The function calls the [AUTHENTICATE PAYER](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-payer-auth-api/index.md) request of the Payer Authentication API. Invoke the `authenticatePayer()` function by providing the following mandatory arguments: * `orderId` Same order ID as you used in the preceding `initiateAuthentication()` function. * `transactionId` Same transaction ID as you used in the preceding `initiateAuthentication()` function. * `callback` Callback function. * `optionalParams`(Optional) Additional AUTHENTICATE PAYER request fields, such as billing and shipping. The following fields are returned in the data argument of the callback function: * `data.restApiResponse` Raw response from the AUTHENTICATE PAYER request. The returned fields depend on the flow (frictionless or challenge) and the authentication channel defined for the session. For a session-authenticated request, the response is filtered to remove data that is not related to the payer and only whitelisted fields are returned. For more information, see [Session Basics](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-session/integrate-hosted-session/create-payment-session/index.md). * `data.correlationId` Last correlation ID that was used for making the AUTHENTICATE PAYER request. It allows you to match the response to the request. * `data.gatewayRecommendation` Recommendation on your next actions, based on the EMV 3-D Secure transaction filtering rules configured by you or your payment service provider: * **PROCEED**: You can proceed to complete the authentication process (challenge flow) or proceed to complete the payment (frictionless flow). If the authorization for the payment was successful, proceed with capturing the funds, and if applicable, ship the goods. * **DO_NOT_PROCEED_ABANDON_ORDER**: Do not submit the same request again. The PSP, scheme, or issuer requires you to abandon the order. * **RESUBMIT_WITH_ALTERNATIVE_PAYMENT_DETAILS**: Ask the payer for alternative payment details (for example, a new card or another payment method) and resubmit the request with the new details. Do not resubmit the same request. * `data.htmlRedirectCode` Redirect code. If the gatewayRecommendation is PROCEED, insert this code into the page displayed to the payer. If the gateway recommends you to PROCEED: * If the ACS has selected a frictionless flow for the payer, it redirects the payer's browser straight back to your web site, and you can proceed to [Step 5](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md#step-5-use-the-authentication-in-a-payment) to submit a subsequent payment to the gateway. The gateway obtains the authentication data related to the payment and ensures that payments are processed only if all the EMV 3-D Secure transaction filtering rules (configured by you or your payment service provider) have passed. * If the ACS has selected a challenge flow for the payer, redirect the payer to the ACS using the htmlRedirectCode provided in the response. After the challenge is completed, the ACS redirects the payer back to your web site and triggers a callback that contains the orderId, transactionId, gatewayRecommendation, and restApiResponse fields. Determine the outcome of the challenge based on the gatewayRecommendation field. The same rules apply as described above for the authenticatePayer() function response. If the recommendation is PROCEED, continue with [Step 5](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/3ds-js-api/index.md#step-5-use-the-authentication-in-a-payment). ### Authenticate payer request and response example {#authenticate-payer-request-and-response-example} ```js 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)); } ``` ```json { "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.2.0", "requestorId": "test2ID", "requestorName": "test2Name", "transactionStatus": "C" }, "method": "OUT_OF_BAND", "payerInteraction": "REQUIRED", "redirect": { "customized": { "3DS": { "acsUrl": "https:///acs/v2/prompt", "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNhODM1ZDQxLTBlMDktNGI3OC1hNmUyLWQwZjJiNjFlZjBjOCJ9" } }, "domainName": "" }, "redirectHtml": "
/acs/v2/prompt\" target=\"challengeFrame\">
", "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" } ``` ### Advanced integrations {#advanced-integrations} The request submitted by the payer's browser to your web site on completion of the `authenticatePayer()` method is parameterized allowing you to determine the authentication outcome. The individual authentication fields, for example, `authentication.3ds2.transactionStatus.data`, can be useful in an advanced integration or if you need to provide the authentication data in a payment processed through another gateway. For more details, see [How do I implement advanced payment session integrations?](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/authentication/3d-secure-auth/index.md#faqs) ## Step 5: Use the authentication in a payment {#step-5-use-the-authentication-in-a-payment} When the result of the `authenticatePayer()` function indicates that you can proceed with the payment (`gatewayRecommendation=PROCEED`), you can initiate an API [AUTHORIZE](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) or [PAY](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) operation. In addition to the Standard fields, you must provide the following fields: * `order.id` Use the same orderId that you supplied in the `initiateAuthentication()` and `authenticatePayer()` functions. * `authentication.transactionId`: Use the same transactionId that you supplied in the `initiateAuthentication()` and `authenticatePayer()` functions. You do not need to include any of the fields in the authentication object, as the gateway uses the authentication.transactionId to look up the authentication results that it stored when you asked it to perform authentication. The gateway passes the required information to the acquirer. ### Pay request and request example {#pay-request-and-request-example} | HTTP Method | URL | |-------------|-----------------------------------------------------------------------------------------------------------------------------| | PUT | https://{{host}}/api/rest/version/merchant/\/order/\/transaction/\ | ```json { "apiOperation": "PAY", "authentication": { "transactionId": "" }, "session": { "id": "" }, "transaction": { "reference": "" } } ``` ```json { "authentication": { "3ds": { "acsEci": "02", "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=", "transactionId": "39c25b96-7bc3-4586-bee8-056479fed3af" }, "3ds2": { "dsTransactionId": "39c25b96-7bc3-4586-bee8-056479fed3af", "protocolVersion": "2.2.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": "", "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": "", "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" } ```