3DS 2.0 Web SDK

Embed the 3DS 2.0 Web SDK into the payments page of your website.

The 3D Secure 2.0 authentication process is initiated and completed by your server. The Web SDK fingerprints the shopper's device and requests additional verification from the shopper.

To use 3D Secure 2.0 on your website, you need to:

  1. Embed the 3D Secure 2.0 SDK.
  2. Initialize the SDK and fingerprint the device.
  3. Submit authentication data to issuer.
  4. Handle additional verification request.
  5. Present the challenge.
  6. Complete the payment after the challenge.

For more information on the SDK, check out our Web SDK reference.

Before you begin

  • Have the following parameters ready before initializing the SDK:

    • YOUR_NOTIFICATION_ENDPOINT - Absolute URL for the page that receives a webhook if the fingerprint has been successfully completed. This is the 3DS Method Notification URL in 3D Secure 2.0 specifications. 
    • CONTAINER - A pointer to an HTML DOM element to hold the challenge <iframe>When the shopper adds their credit card details, the issuer uses this 1x1 iframe to fingerprint the shopper's device by making a POST request to the threeDSMethodURL

Step 1: Embed 3D Secure 2.0 SDK

To install the SDK, perform the following:

  1. Clone our 3DS 2.0 Web SDK repo from https://github.com/Adyen/adyen-3ds2-js.
  2. At the command prompt, navigate to the cloned directory.
  3. Run the command npm install
  4. Add the SDK in the browser either by:
  • Running the command npm run build to create a minified version of the SDK. The file is created in the dist directory of the cloned repo with a filename based on the current version of the SDK. For example, threedsSDK.0.9.6.min.js

    To use the SDK in your browser, add it in a <script> tag:

    <script src="..path-to-SDK/threedsSDK.0.9.6.js"></script>

    A global variable window.threedsSDK will be available, allowing access to the SDK methods.

  • Or by importing it directly from the cloned repo:

     import threedsSDK from 'adyen-3ds2-js';

Step 2: Initialize the SDK and fingerprint the device

Proceed with initializing the SDK using the parameters described earlier:

threedsSDK.get3DSMethodStatus(threeDSServerTransID, threeDSMethodURL, YOUR_NOTIFICATION_ENDPOINT, CONTAINER)

The <iframe> then makes a POST request to the threeDSMethodURL to generate the fingerprint. 

The SDK assumes that there is no data that needs to be extracted from the form that the Access Control Server (ACS) POSTs to this URL. 

The get3DSMethodStatus function returns a promise object that either resolves or rejects. It includes the property threeDSCompIndwhich indicates the outcome of the 3DS Method URL call (YN or U):

  • Y: An iframe has been created, device fingerprinting has happened, and the iframe has been redirected to the 3DS Method Notification URL.
  • N: The creation of the iframe or the call to the threeDSMethodURL has timed out.
  • U: Undefined or no fingerprinting has to be done such as in cases where no threeDSMethodURL was specified.

If device fingerprinting was successful, the iframe makes a POST request to YOUR_NOTIFICATION_ENDPOINT. The front end can target the iframe and tell whether fingerprinting was successful.

Step 3: Submit authentication data to issuer

Collect the threeDSCompInd value and send it to your server. Proceed to make a /authorise3ds2 call. For more information, see Submit 3D Secure 2.0 authentication data to the issuer.

If your server receives an /authorise3ds2 response with a resultCode of ChallengeShopper, the issuer requires additional verification. 

Step 4: Handle additional verification request

In a challenge flow, the issuer generates an additional authentication request. This is presented to the shopper through the iframe.

The shopper must complete this verification before the payment can be authorised.

Get the following from the response: 

  • threeds2.threeDS2ResponseData.acsURL
  • threeds2.threeDS2ResponseData.threeDSServerTransID
  • threeds2.threeDS2ResponseData.acsTransID
  • threeds2.threeDS2ResponseData.messageVersion

Next, create the following parameter and objects:

const acsURL = threeDS2ResponseData.acsURL
const cReqData = {
challengeWindowSize: iframeConfig.size,
threeDSServerTransID : pResp.additionalData['threeds2.threeDS2ResponseData.threeDSServerTransID'],
acsTransID : pResp.additionalData['threeds2.threeDS2ResponseData.acsTransID'],
messageVersion : pResp.additionalData['threeds2.threeDS2ResponseData.messageVersion'],
messageType : 'CReq'
const iframeConfig = {
size: '01', // The size you'd like the iframe to be can be '01' - '05' as documented
container: '' // Container to place the generated iframe into OR an actual iframe

See Web SDK reference for more information on iframeConfig size property.

Step 5: Present the challenge

Create the challenge.

threedsSDK.doChallenge(acsURL, cReqData, iframeConfig);

This will create and place an iframe in your specified container, containing a challenge to be completed by the shopper.

The doChallenge function returns a promise object that either resolves or rejects.

If the outcome is resolved, which means that the challenge was successfully completed, the function will return the following:

const resolveObject = {
transStatus: 'Y'

If the outcome is rejected, which means that the challenge failed, the function will return the following:

const rejectObject = {
transStatus: 'N'

Ensure you include the transStatus parameter in the iframe.location.search property. We use this to determine that the challenge has completed.

In a challenge flow, the ACS redirects the challenge iframe to an endpoint running at the notificationURL upon challenge completion. The notificationURL extracts the required properties from the CRes (Challenge Response) and appends them as GET parameters in the URL. 

The notificationURL is initially set in the 3D Secure 2.0 authentication request

Step 6: Complete the payment after the challenge

Collect the transStatus from the challenge outcome and send this to your server for the final /authorise3ds2 call. See Payment completion for more information.

See also