3D Secure 2 API integration

Support 3D Secure 2 with your online payments integration.

This page describes 3D Secure 2 for /payments API. If you are using a classic integration, see 3D Secure 2 Classic integration.

How it works

A payment eligible for 3D Secure 2 can go through either a frictionless or a challenge authentication flow before the payment is authorised. To simplify your implementation, use our 3D Secure 2 Component in addition to your existing API integration.

The 3D Secure 2 Component will:

  • Handle the device fingerprinting and challenge flows, including the data exchange between your front end and the issuer's Access Control Server (ACS).
  • Return the device fingerprinting and the challenge flow result.

If you do not want to use the 3D Secure 2 Component and want to build the functionality on your own, see Build your own 3D Secure 2 implementation.

3D Secure 2 is supported from v41 and above of /payments and /payments/details endpoints.

If you only want to perform a 3D Secure 2 authentication and then authorise the payment later, see the Authentication only integration page.

Here's a diagram for a 3D Secure 2 browser-based full implementation with the 3D Secure 2 Component:

  • Submit a payment request with the required 3D Secure 2 objects to start the authentication process. Build your implementation depending on the resultCode returned in the response. 
  • Get the 3D Secure 2 device fingerprint. If you receive an IdentifyShopper resultCode, you need to get the shopper's 3D Secure 2 device fingerprint. Initialise the 3D Secure 2 Component for device fingerprinting and submit the result to Adyen. If you get a response with an Authorised resultCode, this indicates that the authentication was frictionless, and the payment was successfully completed.
  • Present a challenge to the shopper. If you receive ChallengeShopper resultCode, this means that the issuer requires further shopper interaction. Depending on the logic on issuer's side, this result code can be returned after you submit a payment request or after you submit the device fingerprint result to Adyen. To handle a challenge flow, initialise the 3D Secure 2 Component for the challenge flow and submit the result to Adyen.

In case the issuer does not support 3D Secure 2, we will initiate a 3D Secure 1 fallback by default, indicated by a RedirectShopper resultCode response. If you do not want to automatically fall back to 3D Secure 1, contact Support Team

For a complete list of resultCode values and the actions that you need to take, see Result codes.

Before you begin

Before you can start accepting 3D Secure 2 transactions, make sure that you:

  1. Sign up for an Adyen test account at https://www.adyen.com/signup
  2. Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.

  3. Read and understand the online payments API integration guide. You should already know how to collect shopper information, either with the Card component or with your own payment form implementation.

Integration steps

  1. Collect the shopper's card details and proceed to submit a payment request
  2. Use the resultCode from the response to determine your next action. For example, to complete a 3D Secure 2 authentication flow, you might need to get the 3D Secure 2 device fingerprint, or present a challenge to the shopper, or both.

To test your integration, see Testing 3D Secure 2.

Submit a payment request 

Submit a payment request with a POST /payments call. Include the following parameters to indicate that you are ready to accept 3D Secure 2 authenticated payments:

  • allow3DS2true

  • channelweb
  • originThe URL of the page where you are loading the 3D Secure 2 Component from.
  • returnURLIn case of a 3D Secure 1 fallback, this is the URL the shopper will be redirected back to after completing 3D Secure 1 authentication.
  • browserInfo: Collect information about your shopper's browser.

In addition to the regular parameters you provide to Adyen, send additional parameters in the following list. We recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorisation rate.

Request

curl https://checkout-test.adyen.com/v41/payments \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod":{
    "type":"scheme",
    "encryptedCardNumber":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode":"adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  },
  "additionalData" : {
     "allow3DS2" : true
  },
  "browserInfo":{     
    "userAgent":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36",
    "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8",
    "language":"nl-NL",
    "colorDepth":24,
    "screenHeight":723,
    "screenWidth":1536,
    "timeZoneOffset":0,
    "javaEnabled": true
  },
  "channel" : "web",
  "origin" : "https://your-company.com/",
  "returnUrl" : "https://your-company.com/checkout/",
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'

Response

You'll receive a response containing:

  • resultCodeIdentifyShopper or ChallengeShopper. Perform the corresponding 3D Secure device fingerprinting or present a challenge flows. If the transaction is exempted from 3D Secure 2, you might get an Authorised resultCode
  • threeds2.fingerprintToken or threeds2.challengeToken: Use this to initiate the 3D Secure 2 Component. If you want to know the contents of the encoded string, see payload structure.

  • paymentData: Use this for your succeeding POST /payments/details request.

In case the issuer does not support 3D Secure 2, we will initiate a 3D Secure 1 fallback by default, indicated by a RedirectShopper resultCode. See 3D Secure fallback for more information.

For other possible resultCode values and the actions that you need to take, see Result codes

Sample response with IdentifyShopper resultCode
{
  "resultCode": "IdentifyShopper",
  "authentication": {
    "threeds2.fingerprintToken": "eyJ0aH..."
  },
  "details": [
    {
      "key": "threeds2.fingerprint",
      "type": "text"
    }
  ],
  "paymentData": "Ab02b4c0!..."
}

Get the 3D Secure 2 device fingerprint

If your server receives an IdentifyShopper resultCode, perform the 3D Secure 2 device fingerprinting with the 3D Secure 2 Component. 

  1. Include the 3D Secure 2 Component script in the <body> above any other JavaScript in your payments page.

    <script src="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/2.2.0/adyen.js"></script>
  2. Create a checkout instance.

    const checkout = new AdyenCheckout();
  3. Create a DOM element.

    <div id="threeDS2"></div>
  4. Initiate the 3D Secure 2 Component with the threeds2.fingerprintToken you received from the /payments response, assign a function to handle the onComplete and onError events, and mount the 3D Secure 2 Component.

    const threeDS2IdentifyShopper = checkout
            .create('threeDS2DeviceFingerprint', {
                fingerprintToken: resultObject.authentication['threeds2.fingerprintToken'],
                onComplete: function() {}, // Gets triggered whenever the ThreeDS2 Component has a result
                onError: function() {} // Gets triggered on error
            })
            .mount('#threeDS2');
  5. Get the result from the onComplete event handler.

    Sample onComplete result after device fingerprinting
    eyJ0aHJlZURTQ29tcEluZCI6ICJZIn0=
  6. Make a POST  /payments/details request from your server with the details object and the paymentData as parameters.
    • threeds2.fingerprint: Pass the result from the onComplete event handler. 
    • paymentData: Pass the paymentData from the initial payment response.

Request

{
  "details": {
    "threeds2.fingerprint": "eyJ0aHJlZURTQ29tcEluZCI6ICJZIn0="
  },
  "paymentData": "YOUR_PAYMENT_DATA..."
}

Response

You'll receive a response containing a resultCode:

  • Authorised – Indicates that the 3D Secure 2 authentication was frictionless, and the payment was successfully completed. This state serves as an indicator to proceed with the delivery of goods and services. 
  • ChallengeShopper – The issuer has requested further shopper interaction. You will also get the threeds2.challengeToken and the paymentData which you will need in the challenge flow. If you want to know the contents of the encoded threeds2.challengeToken string, see payload structure.

For other possible resultCode values and the actions that you need to take, see Result codes.

{
  "resultCode": "ChallengeShopper",
  "authentication": {
    "threeds2.challengeToken": "eyJ0aH..."
  },
  "details": [
    {
      "key": "threeds2.challengeResult",
      "type": "text"
    }
  ],
  "paymentData": "Ab02b4c0!..."
}

Present a challenge

If your server receives a ChallengeShopper resultCode, this means that the issuer would like to perform additional checks in order to verify that the shopper is indeed the cardholder. Use the 3D Secure 2 Component to start the challenge flow. 

  1. Include the 3D Secure 2 Component script in the <body> above any other JavaScript in your payments page.

    <script src="https://checkoutshopper-test.adyen.com/checkoutshopper/sdk/2.2.0/adyen.js"></script>
  2. Create a checkout instance.

    const checkout = new AdyenCheckout();
  3. Create a DOM element.

    <div id="threeDS2"></div>
  4. Initiate the 3D Secure 2 Component with the threeds2.challengeToken you received from /payments response or from /payments/details if you are proceeding from the device fingerprinting flow. Assign a function to handle the onComplete and onError events, set the challenge window size, and then mount the 3D Secure 2 Component.

     const threeDS2Challenge = checkout
            .create('threeDS2Challenge', {
                challengeToken: resultObject.authentication['threeds2.challengeToken'],
                onComplete: function() {}, // Gets triggered whenever the ThreeDS2 Component has a result
                onError: function() {} // Gets triggered on error
                size: '05' // Defaults to '01'
            })
            .mount('#threeDS2');

    Set the size to any of the following identifiers:

    identifier size
    01 250px x 400px
    02 390px x 400px
    03 500px x 600px
    04 600px x 400px
    05 100% x 100%
  5. Get the results from the onComplete handler. 

    Sample onComplete result after a challenge
    eyJ0cmFuc1N0YXR1cyI6IlkifQ==
  6. After you get the result, make a POST  /payments/details request from your server and include details and the paymentData as parameters.

    • threeds2.challengeResult: This is the result from the onComplete event. 
    • paymentData: This is the paymentData from the latest API response, either from the /payments or from the /payments/details response if you are proceeding from the device fingerprinting flow.

Request

{
  "details": {
    "threeds2.challengeResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
  },
  "paymentData": "YOUR_PAYMENT_DATA"
}

Response

You'll receive Authorised as the resultCode if the payment was successful.

{
    "pspReference": "8825495331860022",
    "resultCode": "Authorised"
}

Testing 3D Secure 2

Here are some resources for testing 3D Secure 2 transactions:

  • Test cards:
    • 4212 3456 7890 1245
    • 5212 3456 7890 1242
    • 4212 3456 7891 0006: Only for a browser-based flow. You will get a ChallengeShopper resultCode right after the /payments request, unless if you specified the amount for testing a frictionless scenario.
  • To test specific scenarios, use the following amounts in minor units:
Amount
Authentication scenario
12002 Frictionless
12100 Basic text authentication
12110 Basic single select
12120 Basic multi select
12130 Basic OOB authentication
12140 Basic HTML
12141 HTML OOB authentication
12150 App single select then text
  • For text challenges in an app-based integration, use 1234 for the password
  • For text challenges in a browser-based integration, use password.