This guide is for integrations using the Action Component v5.0.0 with the Advanced flow. For an API only integration, we recommend that you use the Action Component to handle 3D Secure 2 authentication. If you have a Components integration that uses the Card Component, the Card Component can handle 3D Secure 2 authentication without additional 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).
For v4.13.3 or earlier, use the guide for earlier versions.
Before you begin
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 cardholder name in your payment form.
To collect the cardholder name using our Card Component, specify the following when adding the Card Component:
setHolderNameRequired(true)
val checkoutConfiguration = CheckoutConfiguration(
environment = environment,
clientKey = clientKey,
) {
card {
setHolderNameRequired(true)
}
}
We also recommend that you collect the shopper's billing address and email address in advance in your payment form. Deliver these parameters to your backend when making a payment as it is required by the card schemes.
Make a payment
Parameter name | Required | Description |
---|---|---|
paymentMethod | ![]() |
If using the Card Component, pass the data.paymentMethod object from the didSubmit event from your client app. If submitting raw card data, refer to Raw card data for the fields that you need to pass. |
paymentMethod.holderName |
Required for Visa | The cardholder's name. |
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 | ![]() |
In case of a 3D Secure 2 redirect flow, this is the URL where the shopper will be redirected back to after completing authentication. Use the custom URL for your app, for example, my-app://adyen . For more information on setting custom URL schemes, refer to the Apple Developer documentation. |
billingAddress | 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 threeDS2RequestData.mobilePhone |
Required for Visa | A phone number for the shopper, include one of these fields. 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.
Depending on the response, you do the following:
action.type |
Description | Next steps |
---|---|---|
No action object |
The transaction was either exempted or out-of-scope for 3D Secure 2 authentication. | Use the resultCode to present the payment result to your shopper. |
threeDS2 | The payment qualifies for 3D Secure 2, and will go through the authentication flow. | 1. Pass the action object to your client app to perform the authentication flow. 2. Submit the challenge result. |
redirect | The payment is routed to the 3D Secure 2 redirect flow. |
1. Pass the action object to your client app 2. Handle the redirect result. |
The following example shows a /payments response with action.type
: threeDS2
Use the Action Component
-
When you import the library, import the Action Component:
-
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:
-
Add
AdyenComponentView
to your layout .xml file. For example: -
Create the Action Component by calling
PROVIDER.get
from your Component class: -
Attach your Component to your activity or fragment. For example to attach your Component to your view with the identifier
adyenComponentView
: -
When you get a response with an action, call
handleAction
: -
The Component calls the
onAdditionalDetails
method in yourComponentCallback
class and passes theactionComponentJson
object. Pass the object to your backend server. -
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:
-
Add an
IntentFilter
to theActivity
that will handle thereturnUrl
specified in your /payments request.The
android:host
value is your package name at build time. -
Get the result of the redirect from the
Activity
. Pass theintent
back to the Component. Depending on your activity'slaunchMode
, you can get this intent in eitheronCreate
oronNewIntent
.
The onAdditionalDetails
callback gets triggered.
Continue and complete your payment flow.
Handling your Android App link for 3D Secure 2
-
Add the following to your
AndroidManifest.xml
, specifying your Android App Link as yourandroid:host
:
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 callingThreeDS2Service.INSTANCE.sdkVersion
.channel
is set to Android.