Native 3D Secure 2 authentication

This page explains how to implement native 3D Secure 2 authentication with your existing Android Drop-in integration.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

How it works

For a Drop-in integration, you must implement the following parts:

The parts of your integration work together to complete the payment flow:

1. From your server, submit a request to get a list of payment methods available to the shopper.
2. Configure and launch Drop-in to collect the shopper's details.
3. From your server, make a payment request with data that you receive from Drop-in.
4. Handle additional client-side actions, if required.
5. From your server, send additional payment details with data you receive from Drop-in, if required.
6. Get the payment outcome to inform the shopper and update your order management system.

If you are integrating these parts separately, you can start at the corresponding part of this integration guide:

Collect additional parameters in your payment form

For higher authentication rates, we strongly recommend that you collect the shopper's billing address and email address. Send these parameters to your server when making a payment, because they are required by the card schemes.

Optional configuration

When you configure the Drop-in, you can include the following functions:

For example:

// Create a configuration object.
val checkoutConfiguration = CheckoutConfiguration(
    environment = environment,
    clientKey = clientKey,
) {
    // Configure 3D Secure 2.
    adyen3DS2 {
        setThreeDSRequestorAppURL("https://your.app.com/adyen3ds2") // Strongly recommended.
    }
}

After configuring Drop-in, continue to launch and show Drop-in and make the payment request.

Make a payment

When you make a payment request, include additional parameters for 3D Secure 2 in the /payments request from your server:

Parameter name	Required	Description
paymentMethod		If submitting raw card data, send the required payment method parameters.
paymentMethod.holderName	Required for Visa	The cardholder's name.
paymentMethod.threeDS2SdkVersion		Required to trigger in-app native. See how to get the SDK version.
browserInfo		The shopper's browser information. Include the following fields to handle cases where the payment is routed to 3D Secure 2 redirect. acceptHeader: The accept header value of the shopper's browser. You can use a dummy value. userAgent: Get it using WebSettings.getDefaultUserAgent(Context); .
channel		Set to Android.
authenticationData.threeDSRequestData.nativeThreeDS		Set to preferred. Indicates that your payment page can handle 3D Secure 2 transactions natively.
returnUrl		The URL that the shopper will be redirected to after they complete the payment. We strongly recommend to redirect the shopper to your app by configuring a threeDSRequestorAppURL, because this improves conversion.
billingAddress	Strongly recommended	The cardholder's billing address.
shopperEmail	Required for Visa	The cardholder's email address. shopperEmail or a phone number is required for Visa.
threeDS2requestData.homePhone, threeDS2RequestData.workPhone or threeDS2RequestData.mobilePhone	Required for Visa	A phone number for the shopper. shopperEmail or a phone number is required for Visa.

Get the SDK version

Use the ThreeDS2Service.INSTANCE.getSDKVersion() function to determine your 3D Secure 2 sdkVersion. You can also get the sdkVersion from Github. We recommend not to hardcode the SDK version.

curl https://checkout-test.adyen.com/checkout/v69/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
   "amount":{
      "currency":"EUR",
      "value":1000
   },
   "reference":"YOUR_ORDER_NUMBER",
   "shopperReference":"YOUR_UNIQUE_SHOPPER_ID",
   "paymentMethod": STATE_DATApaymentMethod field of an object passed from the client app. Return the fields as they are, sdkVersion is required to trigger native.,
   "authenticationData": {
      "threeDSRequestData": {
    	"nativeThreeDS": "preferred"
      }
   },
   "billingAddressstate.data.billingAddress from onSubmit": {
      "street": "Infinite Loop",
      "houseNumberOrName": "1",
      "postalCode": "1011DJ",
      "city": "Amsterdam",
      "country": "NL"
   },
   "browserInfoRequired for 3D Secure 1: {
      "userAgent":"Mozilla/5.0 (Linux; Android 6.0.1; Nexus 6P Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/47.0.2526.83 Mobile Safari/537.36",
      "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8"
   },
   "shopperEmail":"s.hopper@example.com",
   "channel":"Android",
   "returnUrl":"adyencheckout://your.package.name",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'

Your next steps depend on whether the /payments response contains an action object, and on the action.type:

{
    "action":{
        "type":"threeDS2",
        "subtype": "fingerprint",
        "paymentData":"Ab02b4c0!BQABAgCuZFJrQOjSsl\/zt+...",
        "paymentMethodType":"scheme",
        "authorisationToken" : "Ab02b4c0!BQABAgAvrX03p...",
        "token":"eyJ0aHJlZURTTWV0aG9kTm90aWZpY..."
    },
    "resultCode":"IdentifyShopper",
    ...
}

Submit additional 3D Secure 2 authentication details

When you send additional details, send the 3D Secure 2 authentication data from your server:

1. Drop-in calls the onAdditionalDetails method in your DropInService class passing, the actionComponentJson object. Pass the object to your backend server.

2. From your server, make a POST /payments/details request, including actionComponentJson object:

curl https://checkout-test.adyen.com/checkout/v70/payments/details \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d 'STATE_DATAobject passed from the front end or client app'

3. Pass the /payments/details response from your server to your client-side app.

Continue and complete your payment flow.

Present the payment result

Use the  resultCode from the /payments or /payments/details response to present the payment result to your shopper. You will also receive the outcome of the payment asynchronously in a webhook.

For card payments, you can receive the following resultCode values:

Handle your Android App Link

If you have configured the setThreeDSRequestorAppURL when you configured Drop-in, you have to handle this Android App link.

1. Add the following to your AndroidManifest.xml, specifying your Android App Link as your android:host:

   Copy to your app Manifest file

   Expand view

   Copy link to code block

   Copy code

   Copy code

   <activity
       android:name="com.adyen.threeds2.internal.ui.activity.ChallengeActivity"
           android:exported="true"
           tools:node="merge">
           <intent-filter
               android:autoVerify="true"
               tools:targetApi="m">
               <action android:name="android.intent.action.VIEW" />
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE" />
               <data
                   android:host="{your.app.com}"
                   android:pathPrefix="/adyen3ds2"
                   android:scheme="https" />
           </intent-filter>
   </activity>

2. Verify the App Link.

Testing

Use our test card numbers to test how your integration handles different 3D Secure authentication scenarios.

Troubleshooting

If native 3D Secure 2 is not triggered, check that:

• Your Component version is 4.9.1 or later.
• paymentMethod.threeDS2SdkVersion is populated and sent in payment request.
• channel is set to Android.
• authenticationData.threeDSRequestData.nativeThreeDS is set to preferred if you use Checkout API v69 or later OR additionalData.allow3DS2 is set to true if you use Checkout API v68 or earlier.

See also