What is 3DS?

Strong Customer Authentication (SCA) regulation in Europe requires the use of 3D Secure (3DS) for card payments.

3DS requires customers to complete an additional verification step with the card issuer when paying. If challenged, we direct the customer to an authentication page served by their bank, and they enter a password associated with the card or a code sent to their phone.

Configure 3D Secure for your Primer account

At Primer, we've decoupled 3D Secure from any underlying processor. Configure 3D Secure in your workflow, and Universal Checkout will handle the rest, presenting a fully in-context and optimized 3D Secure flow to your customer on web and mobile. Now you're SCA-ready with a unified checkout across all your payments services including 3D Secure 2.0.

Primer supports Dynamic 3DS to improve conversion, enabling you to present 3D Secure to customers only when it's absolutely required.

If your card processor does not support third-party 3D Secure, Primer seamlessly redirects the user to the processor's 3DS challenge page instead.

Set up the workflow for 3D Secure

Configuring 3DS settings for your payments takes place within the "Authorize payment" Action. Learn more here about how to set up a workflow to process payments.

Example of setting up a workflow

In the configuration panel, you need to choose which 3DS option you want for all payments processed by this Action block:


No 3DS

3D Secure will not be used for any payments processed by this block. Payments will be declined when the Issuer requires authentication.


Adaptive 3DS

Use Primer’s proprietary Adaptive 3DS which will only carry out 3DS authentication if the payment would be declined without it.


Primer 3DS

3D Secure authentication will be handled by Primer's agnostic 3D Secure solution for payments processed by this block. This could either be a challenge or frictionless.


Processor 3DS

Your processor will present a 3DS challenge according to their configuration. This isn't compatible with Fallbacks as Primer is not involved in the flow.

Configure your Client Session

To improve 3DS success rates, it is recommended to pass the following elements in the Client Session:

  1. customer
The customer's email address
  1. customer
The customer's billing address

In Sandbox, the email address and billing address must be provided to trigger 3DS.

Handle 3D Secure in Universal Checkout

Install 3DS SDK

3D Secure on React Native requires the addition of the 3DS SDK on iOS and Android.

On iOS

Adding 3D Secure to iOS via React Native requires the addition of the Primer3DS Cocoapod dependency.

Open Podfile inside the ./ios directory of your React Native project. Then add the following:

target 'MyApp' do   # add the pod  pod 'Primer3DS'   # if you don't use use_frameworks! add the snippet below  post_install do |installer|    installer.pods_project.targets.each do |target|      if target.name == "primer-io-react-native" || target.name == "PrimerSDK"        target.build_configurations.each do |config|          config.build_settings['FRAMEWORK_SEARCH_PATHS'] = "$(inherited) ${PODS_CONFIGURATION_BUILD_DIR}/Primer3DS"          config.build_settings['LIBRARY_SEARCH_PATHS'] = "$(inherited) ${PODS_CONFIGURATION_BUILD_DIR}/Primer3DS"          config.build_settings['SWIFT_INCLUDE_PATHS'] = "$(inherited) ${PODS_CONFIGURATION_BUILD_DIR}/Primer3DS"          config.build_settings['OTHER_SWIFT_FLAGS'] = '$(inherited) -Xcc -fmodule-map-file="${PODS_CONFIGURATION_BUILD_DIR}/Primer3DS/Primer3DS.modulemap"'          config.build_settings['OTHER_LDFLAGS'] = '$(inherited) -weak_library -l"Primer3DS"'        end      end    end  end end
On Android

3D Secure on Android requires the addition of the io.primer:3ds-android library to your project.

  1. 1

    Navigate to the ./android directory in your React Native project.

  2. 2

    Add the URL to the Primer 3DS artifactory to ./gradle.properties.

  3. 3

    Amend the repositories section of ./app/build.gradle to include the artifactory location

    repositories {        /* Other repositories... */     maven {        url "${PRIMER_ANDROID_ARTIFACTORY_URL}"    }}
  4. 4

    Finally, amend the dependencies section of your app's build.gradle to include the 3ds-android library. Paste this code, make sure to replace supported-3ds-sdk-version with the right value. See the table below to get the correct one:

    dependencies {  /* Other dependencies... */   implementation "io.primer:3ds-android:{supported-3ds-sdk-version}"}

Interoperability matrix

Primer SDK internally uses Primer 3DS SDK as a compile time dependency. In order for the SDKs to work properly, the versions used internally and the one imported to your code must match.

Here is a breakdown of supported interoperable versions:

Primer SDK versionPrimer 3DS SDK version
2.15.0 -
2.0.0 -

Handle Out-of-Band (OOB) redirects (Optional)

Starting from 3D Secure protocol version 2.2.0, you can enhance the user experience by implementing an automatic redirect from another (authentication) application during an OOB challenge to your application once the challenge is successfully completed. This feature allows for a seamless transition and improved user flow.


If this feature is not implemented, the user will have to come back to your application manually to complete their payment, which adds significant friction.

To enable this feature, ensure that you include the threeDsAppRequestorUrl parameter when configuring the threeDsOptions property of your settings for each platform.

Please note that the ios.threeDsAppRequestorUrl value must be an iOS Universal Link and the android.threeDsAppRequestorUrl value must be an Android App Link in order to facilitate the redirection.

To configure the Universal Link correctly using Universal Checkout, follow these steps:

  1. 1

    Pass your iOS Universal Link (e.g. https://{UNIVERSAL_LINK}) as threeDsAppRequestorUrl, and your Android App Link (e.g. https://{yourdomain.com}/3ds) in the threeDsOptions object of your settings.

    const settings: PrimerSettings = {  // ...  paymentMethodOptions: {    threeDsOptions: {      iOS?: {        threeDsAppRequestorUrl?: string;      }      android?: {        threeDsAppRequestorUrl?: string;      }    },    // ...  }}
  2. 2

    Follow Step 2 & 3 from the iOS guide.

  3. 3

    Follow Steps 1 to 3 from the Android guide.

Execute 3D Secure

Universal Checkout drop-in and headless automatically render the 3DS challenge when required by your workflow.

If this application is not installed from a trusted source (e.g. a debug version, not installed from store, or used on an emulator), try to set PrimerDebugOptions.is3DSSanityCheckEnabled to false. Otherwise 3D Secure library initialization will fail due to security checks being performed.


is3DSSanityCheckEnabled flag should only be used in development mode, and not in production release of your app.

const settings: PrimerSettings = {    // ...    debugOptions: {        is3DSSanityCheckEnabled: true,    },}

Test 3D Secure

Go Live

Before going live with 3D Secure, your account has to be configured for each of your processor.

To do so, please get in touch with your contact at Primer with the following information:

  • Acquirer Merchant ID
  • ARN (Acquirer reference number) - per card scheme
    For Amex - this is referred to as the Amex SE number (Service entity)
  • Merchant Category Code