Migrating to Adyen 3D Secure 2 SDK version 2.2.0 or later

Find out how you can update your integration to the latest Android and iOS 3D Secure 2 SDKs.

Adyen is no longer developing the Classic API integration

This page is for the Classic API (/authorise) integration, which we no longer accept new integrations with.

We strongly recommend migrating to the newer Native 3D Secure 2 integration. To use this newer integration, you must also migrate to the Checkout API.

Even if you do not need the features of the newest Adyen 3D Secure 2 SDK version, we strongly recommend that you still upgrade to the newest version to get the latest updates, security patches, and fixes.

Changes in the new Adyen 3D Secure 2 SDK version 2.2.0 or later

These changes apply to version 2.2.0 or later for iOS and Android.

Supported

3D Secure protocol version 2.2.0 in addition to 2.1.0.
Support for new 3DS2 Directory Servers (e.g. card networks Cartes Bancaires, Diners, Discover, and Elo)
Sending your app URL in the threeDSRequestorAppURL parameter for out-of-band (OOB) authentication in in-app transactions.

In an OOB authentication, the cardholder performs the challenge flow outside of the 3DS2 SDK. The authenticating app uses the threeDSRequestorAppURL to call your app after an OOB authentication occurs.

Required

The additionalData.threeds2.threeDS2ResponseData.messageVersion from the /authorise response must be used to create a transaction in the iOS SDK or create a transaction in the Android SDK.

Migrating to Adyen 3D Secure 2 SDK version 2.2.0 or later

Install the latest versions:
- Adyen 3DS2 iOS SDK version 2.2.0 or later
- Adyen 3DS2 Android SDK version 2.2.0 or later
Send the version of the 3DS2 SDK in the threeDS2RequestData.sdkVersion field in the initial request; this will inform the Adyen 3DS2 Server that the newer SDK features can be used such as 3D Secure protocol 2.2.0 and 3DS2 over the newly added card networks.
- For iOS, call ADY3DS2SDKVersion() to get the version.
- For Android, call ThreeDS2Service.INSTANCE.sdkVersion to get the version.
To make sure you use a protocol version that the issuing bank supports, you must get the additionalData.threeds2.threeDS2ResponseData.messageVersion from the /authorise response and pass it on to your SDK when you create a transaction. Otherwise, the transaction can fail due to a version mismatch.

Using 3D Secure 2 protocol version 2.2.0 and later

If you want to use the latest 3D Secure 2 protocol version 2.2.0, include the threeDSRequestorAppURL parameter during the challenge flow. This parameter is used in an OOB authentication. If you specify a previous protocol version, the threeDSRequestorAppURL parameter is ignored.

The examples in the tabs below show how to specify the threeDSRequestorAppURL parameter in iOS and Android:

Using 3D Secure 2 protocol version earlier than 2.2.0

If you want to use an earlier 3D Secure 2 protocol version:

The additionalData.threeds2.threeDS2ResponseData.messageVersion from the /authorise response must be used to create a transaction in the iOS SDK or create a transaction in the Android SDK.
You need to include threeDS2RequestData.messageVersion in your POST /authorise request. For example, set this parameter to 2.1.0.

The threeDS2RequestData.messageVersion that you send in the request will be used to guide the Adyen 3D Secure 2 Server in the protocol version to use in the transaction. But a different version than requested can still be returned if, for example, the issuing bank does not support the requested version. Because of this, the additionalData.threeds2.threeDS2ResponseData.messageVersion must still be the one used to initialize the 3D Secure 2 SDK; otherwise the transaction will fail.

See also