3D Secure 2 Component

You can use the 3D Secure 2 Component if you have an API-only integration. The Component 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).

If you have a Components integration that uses the Card Component, the Card Component can handle 3D Secure 2 authentication without additional integration. You don't need to use the 3D Secure 2 Component in this case.

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 in your payment form. Send these parameters to your server when making a payment, because they are required by the card schemes.

Import the 3D Secure 2 Component

When you import the library, import the 3D Secure 2 Component:

Optional configuration

When you configure the Component, 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 the Component, continue to launch and show the Component.

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		If submitting raw card data, send the required payment method parameters.
paymentMethod.threeDS2SdkVersion		Required to trigger in-app native. See how to get the SDK version.
channel		Set to Android.
authenticationData.threeDSRequestData.nativeThreeDS		Set to preferred. Indicates that your payment page can handle 3D Secure 2 transactions natively.
returnUrl		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	Strongly recommended	The cardholder's email address.
shopperIP	Strongly recommended	The shopper's IP address.

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

Example /payments request:

Depending on the response, you do the following:

Response	What to do
Doesn't include action object	Submit additional 3D Secure 2 authentication details.
Includes action object	Handle a redirect.

Submit additional 3D Secure 2 authentication details

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

1. The Component calls the onAdditionalDetails method in your ComponentCallback 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 backend server to your frontend app.

Continue and complete your payment flow.

Handle a redirect

In some cases, your shopper is routed to perform 3D Secure redirect authentication instead. When this happens, handle the redirect:

1. Add an IntentFilter to the Activity that will handle the returnUrl specified in your /payments request.

   The android:host value is your package name at build time.

2. Get the result of the redirect from the Activity. Pass the intent back to the Component. Depending on your activity's launchMode, you can get this intent in either onCreate or onNewIntent.

   The onAdditionalDetails callback gets triggered.

Continue and complete your payment flow.

Handling your Android App link for 3D Secure 2

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