Search

Are you looking for test card numbers?

Would you like to contact support?

Classic-integration icon

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.

This page is for our classic Direct API (/authorise) integration. If you are integrating using our Checkout APIs, refer to the Native 3D Secure 2 documentation instead.

Even if you don't 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

Migrating to Adyen 3DS2 SDK version 2.2.0 or later

  1. Install the latest versions:

  2. Send the version of the 3DS2 SDK (that can be retrieved by calling the global function ADY3DS2SDKVersion()) 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.

  3. 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.

  4. If you want to use the latest 3D Secure 2 protocol version 2.2.0:

    When the protocol version 2.2.0 is used, you can optionally send 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 you would specify the threeDSRequestorAppURL parameter in iOS and Android:

    Set the threeDSRequestorAppURL in the ADYChallengeParameters .

    Make sure to add the URL should to the app build settings. For more information, refer to the Apple Developer documentation.

    
    NSDictionary *additionalData = ...; // Retrieved from Adyen.
    ADYChallengeParameters *parameters = [ADYChallengeParameters
      ...
                                          threeDSRequestorAppURL: [NSURL URLWithString:@"{YOUR_CUSTOM_SCHEME}://{YOUR_CUSTOM_DOMAIN}"]];

    Set the threeDSRequestorAppURL in the ChallengeParameters . You can also retrieve this from ChallengeParameters.getEmbeddedRequestorAppURL(context).

    Map<String, String> additionalData = ...; // Retrieved from Adyen.
    
    ChallengeParameters challengeParameters = new ChallengeParameters();
    ...
    challengeParameters.setThreeDSRequestorAppURL(ChallengeParameters.getEmbeddedRequestorAppURL(this));
  5. If you want to use an earlier 3D Secure 2 protocol version:

    1. 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.
    2. 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