Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

3D Secure 2 API integration

Support 3D Secure 2 authentication for web and in-app transactions with your online payments integration.

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

How it works

If you are using 3D Secure for PSD2 compliance, read our comprehensive PSD2 SCA guide.

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

Components are our pre-built modules that you can use to perform specific functions such as 3D Secure 2 authentication. To implement, submit API requests from your backend and then use our 3D Secure 2 Component to:

  • Handle the device fingerprinting and challenge flows, including the data exchange between your front end or client 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 web-based implementation on your own, see Build your own 3D Secure 2 implementation. You can also choose to prefetch 3D Secure 2 device fingerprinting keys to reduce the number of calls for each transaction.

For an app-based implementation, we recommend that you use our 3D Secure 2 Android or iOS Component. Both our Android and iOS 3D Secure 2 Component implementations are approved and certified by EMVCo. If you want to build your own 3D Secure 2 mobile implementation, you will need to get an EMVCo certification.

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 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. Initialize the 3D Secure 2 Component for device fingerprinting and submit the result to Adyen. If after submitting the result you get a response with an Authorised resultCode, this indicates that the transaction was authenticated in a frictionless flow, 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 and is initiating a challenge flow. In a web-based integration, this result code can be returned after you submit a payment request or after you submit the device fingerprint result to Adyen, depending on the logic on the issuer's side. To handle a challenge flow, initialize 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 Components integration guide. You should already know how to collect shopper information, either with the Card component or with your own payment form implementation.
  4. Install iOS or Android 3D Secure 2 Component for app-based integration.

Install iOS 3D Secure 2 Component

3D Secure 2 is supported from Adyen iOS version 2.6.0 and later.

Import the iOS 3D Secure 2 Component to your project using either CocoaPods or Carthage:

CocoaPods

  1. Add pod 'Adyen' to your Podfile.
  2. Run pod install.

Carthage

  1. Add github "adyen/adyen-ios" to your Cartfile.
  2. Run carthage update.
  3. Link the framework with your target as described in Carthage Readme.

Install Android 3D Secure 2 Component

3D Secure 2 is supported from Adyen Android version 2.4.0 and later.

 Import the Android 3D Secure 2 Component by adding this line to your build.gradle file.

implementation "com.adyen.checkout:threeds:<latest-version>"

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. Choose the integration steps for web, Android, or iOS.
  3. Submit the 3D Secure device fingerprinting result and in case of a challenge flow, submit the challenge result.

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

Step 1: 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:

  • allow3DS2: Set this to true. This indicates that you support 3D Secure 2 on your payments page.
  • channel: The platform that you are using. Use WebiOS, or Android.
  • origin: Required for channel Web. The URL of the page where you are loading the 3D Secure 2 Component from.
  • returnURL: In case of a 3D Secure 1 fallback, this is the URL where the shopper will be redirected back to after completing 3D Secure 1 authentication.
  • browserInfo: Required for channel Web. Collect information about your shopper's browser.
We recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorisation rate. In addition to the regular parameters you provide to Adyen, send additional parameters in this list.

Request

curl https://checkout-test.adyen.com/v46/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 next 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

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

Step 2: Get the 3D Secure 2 device fingerprint

If your server receives an IdentifyShopper resultCode, perform the 3D Secure 2 device fingerprinting. Follow the 3D Secure device fingerprinting procedure for webiOS, or Android.

Collect the 3D Secure 2 device fingerprint from the browser

  1. Make sure that you have already added the Components JavaScript file and the required configuration on your payments page.

  2. Create a DOM element.

    <div id="threeDS2"></div>
  3. 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() {}, // Called whenever a result is available, regardless if the outcome is successful or not.
                onError: function() {} // Gets triggered on error.
            })
            .mount('#threeDS2');
  4. When the onComplete event is triggered, get the result and proceed to submit the 3D Secure 2 device fingerprinting result.

    If the 3D Secure 2 device fingerprinting failed, both onComplete and onError will be called.

    function onComplete(fingerprintData) {
        fingerprintResult = fingerprintData.data.details["threeds2.fingerprint"];
    }

Collect the 3D Secure 2 device fingerprint from an iOS app

  1. Create a Card3DS2Authenticator instance. 

    let authenticator = Card3DS2Authenticator()
  2. Create a fingerprint with the threeds2.fingerprintToken you received from the  /payments response. 

    authenticator.createFingerprint(usingToken: fingerprintToken) { result in
         switch result {
         case let .success(fingerprint):
              // Submit fingerprint
         case let .failure(error):
              // Handle error
         }
    }
  3. If the success event is triggered, proceed to submit the 3D Secure 2 device fingerprinting result with the value passed in success. Otherwise, handle the failure event. The failure event will be triggered in case of a timeout, user cancellation, or system failures such as a certificate validation error or an invalid response from the issuer. 

Collect the 3D Secure 2 device fingerprint from an Android app

  1. Create a Card3DS2Authenticator instance and pass the current context.

    mCard3DS2Authenticator = new Card3DS2Authenticator(/* Activity */ this);
  2. Create a fingerprint with the threeds2.fingerprintToken you received from the /payments response.

    mCard3DS2Authenticator.createFingerprint(fingerprintToken, new Card3DS2Authenticator.FingerprintListener() {
    @Override
    public void onSuccess(@NonNull String fingerprint) {
        // Submit fingerprint
    }
    
    @Override
    public void onFailure(@NonNull ThreeDS2Exception e) {
        mCard3DS2Authenticator.release();
        // Handle error
    }
    });
  3. If the onSuccess event is triggered, proceed to submit the 3D Secure 2 device fingerprinting result. Otherwise, handle the onFailure event. The onFailure event will be triggered in case of a timeout, user cancellation, or system failures such as a certificate validation error or an invalid response from the issuer.

Step 3: Submit the 3D Secure 2 device fingerprinting result

Make a POST  /payments/details request from your server with the details object and the paymentData as parameters.

  • threeds2.fingerprint: Pass the fingerprintResult from the onComplete event handler for web, success from iOS, or onSuccess for Android 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 any of the following resultCode:

  • Authorised – This indicates that the transaction was authenticated in a frictionless flow, 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 and is initiating a challenge flow. 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!..."
}

Step 4: 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. Follow the challenge flow procedure for webAndroid, or iOS.

Present a challenge in the browser

  1. Make sure that you have already added the Components JavaScript file and the required configuration on your payments page.

  2. Create a DOM element, or reuse the existing one if you are proceeding from the device fingerprinting flow.

    <div id="threeDS2"></div>
  3. 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() {}, // Called whenever a result is available, regardless if the outcome is successful or not.
                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%
  4. When the onComplete event is triggered, always get the result and proceed to submit the challenge result.

    If the challenge flow failed, both onComplete and onError will be called.

    function onComplete(challengeData) {
        challengeResult = challengeData.data.details["threeds2.challengeResult"];
    }

Present a challenge in an iOS app

  1. Use the same Card3DS2Authenticator instance from the 3D Secure device fingerprinting flow. Pass the threeds2.challengeToken you received from /payments/details to the presentChallenge() function. 

    authenticator.presentChallenge(usingToken: challengeToken) { result in
         switch result {
         case let .success(challengeResult):
              let payload = challengeResult.payload
              // Submit challenge result payload
         case let .failure(error):
              // Handle error
         }
    }
  2. If the success event is triggered, proceed to submit the challenge result with the payload value passed in the challengeResult of the success event. Otherwise, handle the failure event. The failure event will be triggered in case of a timeout, user cancellation, or system failures such as a certificate validation error or an invalid response from the issuer. 

Present a challenge in an Android app

  1. Pass the threeds2.challengeToken you received from the /payments/details to the Card3DS2Authenticator

    mCard3DS2Authenticator.presentChallenge(challengeToken, new Card3DS2Authenticator.SimpleChallengeListener() {
    @Override
    public void onSuccess(@NonNull ChallengeResult challengeResult) {
        mCard3DS2Authenticator.release();
        String payload = challengeResult.getPayload();
        // Pass the challenge result payload
    }
    
    @Override
    public void onFailure(@NonNull ThreeDS2Exception e) {
        mCard3DS2Authenticator.release();
        // Handle error
    }
    });
  2. If the onSuccess event is triggered, proceed to submit the challenge result with the payload value passed in the challengeResult of the onSuccess event. Otherwise, handle the onFailure event. The onFailure event will be triggered in case of a timeout, user cancellation, or system failures such as a certificate validation error or an invalid response from the issuer.

Step 5: Submit the challenge result

Make a POST  /payments/details request from your server and include details and the paymentData as parameters.

  • threeds2.challengeResult: Pass the result from the challengeResult from the onComplete event handler for web, onSuccess for Android, or the payload value in the challengeResult of the success iOS event handler. 
  • 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

Use the following test cards along with the amounts in the next table to test 3D Secure 2 authentication scenarios.

Card Type Card Number Expiry Month Expiry Year Security Code (CVC/CVV) When to use this card
Visa 4212 3456 7890 1245 10 2020 737 To test any 3D Secure 2 authentication scenario for Visa.
Mastercard 5212 3456 7890 1242 10 2020 737 To test any 3D Secure 2 authentication scenario for Mastercard.
Visa 4212 3456 7891 0006 10 2020 737 To test the web-based authentication flow where you immediately get a ChallengeShopper resultCode right after the /payments request.

Specific authentication scenario

Amount Authentication scenario
12002 Frictionless
12100 Basic text authentication
12110 Basic single select
12120 Basic multi select
12130 Basic out-of-band (OOB) authentication
12140 HTML OOB authentication
12150 App single select then text authentication

When prompted for 3D Secure 2 text challenges, use the following credentials:

  • For mobile, use password: 1234
  • For web, use password: password

See also