Checkout icon

Native 3DS2 Drop-in integration

Add native 3D Secure 2 authentication to your existing Drop-in integration.

Drop-in handles 3D Secure 2 device fingerprinting and challenge flows, including the data exchange between your client-side and the card issuer's Access Control Server (ACS).

This guide is for integrations using Drop-in v5.0.0 with the Advanced flow.
For v4.13.3 or earlier, use the guide for earlier verions.

Requirements

Make sure that you have set up your Drop-in v5.0.0 with Advanced flow integration.

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:

Configuration function Description Parameter
setThreeDSRequestorAppURL Strongly recommended. An Android App link to call your app after an out-of-band (OOB) authentication occurs. When set, your app must also handle this Android App link. threeDSRequestorAppURL: String.
Default: null.
setUiCustomization Customization for the 3D Secure 2 authentication UI. A UiCustomization object.

For example:

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

Include additional parameters in your payment request

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 -white_check_mark- If submitting raw card data, send the required payment method parameters.
paymentMethod.holderName Required for Visa The cardholder's name.
paymentMethod.threeDS2SdkVersion -white_check_mark- Required to trigger in-app native.
channel -white_check_mark- Set to Android.
authenticationData.threeDSRequestData.nativeThreeDS -white_check_mark- Set to preferred. Indicates that your payment page can handle 3D Secure 2 transactions natively.
returnUrl -white_check_mark- Used to redirect the shopper back to a webpage for redirect and other payment flows. If you want to redirect the shopper to your app, configure a threeDSRequestorAppURL.
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.

For higher authorization rates, we strongly recommend including the optional parameters.

Example /payments request:

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:

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

Continue and complete your payment flow.

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

  2. Verify the App Link.

Troubleshooting

If native 3D Secure 2 is not triggered, check that, in your /payments request:

  • authenticationData.threeDSRequestData.nativeThreeDS is set to preferred.
  • paymentMethod.threeDS2SdkVersion is set. You can get this value by calling ThreeDS2Service.INSTANCE.sdkVersion.
  • channel is set to Android.

See also