3DS Android SDK

Last updated: March 26, 2025

Use our 3D Secure (3DS) Android SDK to seamlessly handle the end-to-end 3DS authentication flow.

With a single method call, the SDK handles:

collecting required device data
communicating with the customer's bank
presenting 3DS challenges when required

When used alongside our non-hosted sessions authentication solution, the 3DS SDK allows you to authenticate within the payment authorization flow. Alternatively, you can use the authentication result to complete the payment manually at a later time.

Additionally, the SDK is fully EMVCo and PCI-compliant, ensuring interoperability with card issuers and secure handling of your customers' data.

Information

The SDK only collects data which your app already has permission to collect – the customer will never be prompted to grant new permissions. The device data collected is encrypted throughout the authentication process but is never stored, and the SDK does not retain any personal information about the customer.

3DS allows you and your payment provider to share additional data with the customer's bank. For example, the customer's device ID and payment history.

This data allows the bank to assess the risk of the transaction more accurately, and determine which flow the customer will be required to go through:

frictionless flow
challenge flow

If the customer's bank is satisfied with the data and trusts that the cardholder making the payment is genuine, the transaction will be authenticated without interrupting the customer.

The customer is only shown a brief Processing UI, with their card scheme's branding.

If the bank requires additional evidence to authenticate the cardholder, they will prompt the customer to verify their identity.

To do this, the bank may use any of the following methods:

one-time password – the customer is sent a single-use password or code via text or email, which they must enter
single-select or multi-select – the customer is asked a multiple-choice question, with one or more selections allowed
out-of-band – the customer is asked to confirm the transaction through another channel, typically their banking app
HTML – the bank explicitly defines the view that should be presented to the customer via HTML, which can be that of any of the previous methods, or a custom approach

Information

To provide a consistent experience across different devices and schemes, there are standard templates and rules that the 3DS challenge screens adhere to. However, there is some leeway around styling. Our SDK gives you control over the display of the native challenges in your app, while ensuring that the rules are followed.

Add the SDK as a project dependency.
Initialize the SDK.
Configure authentication parameters.
Handle authentication results.
Customize the 3DS Challenge UI.

Make sure you have a test account with Checkout.com. To use the SDK, you'll also need to have onboarded with our non-hosted sessions authentication solution.

You'll also need the following:

a public key, to initialize the SDK and authenticate your payment request
a secret key or OAuth 2.0 client credentials, to use as an authentication mechanism

To get started, download the 3DS SDK for Android from GitHub.

Information

You can subscribe to the GitHub repository to be notified about updates to the SDK.

The minimum requirements to use the Android SDK are:

Kotlin 1.8.10 or higher
JDK 17 or higher
Gradle 8.0.2 or higher
Android Gradle Plugin 8.0
Android API level 21 (Android 5.0) or higher as a build target

Information

The SDK makes use of Java 8+ language features. To run on Android level 25 (Android 7) or lower, you must enable desugaring.

Declare the 3DS SDK as an application or library dependency in your build.gradle file, using Maven Repository or GitHub Packages.


1// Option 1: add the following to your project’s top-level Gradle file
2allprojects {
3  repositories {
4    mavenCentral()
5  }
6}
7
8// Option 2: add the following to your project’s Gradle settings file
9dependencyResolutionManagement {
10  repositories {
11    mavenCentral()
12  }
13}
14
15// Add the following to your application or library's Gradle file
16dependencies {
17  implementation("com.checkout:checkout-sdk-3ds-android:3.x.x")
18}


1// Option 1: add the following to your project’s top-level Gradle file
2allprojects {
3  repositories {
4    maven {
5      url = uri("https://maven.pkg.github.com/checkout/checkout-3ds-sdk-android")
6      credentials {
7        username = "Add your GitHub Username"
8        password = "Add your GitHub Token"
9      }
10    }
11  }
12}
13
14// Option 2: add the following to your project’s Gradle setting file
15dependencyResolutionManagement {
16  repositories {
17    maven {
18      url = uri("https://maven.pkg.github.com/checkout/checkout-3ds-sdk-android")
19      credentials {
20        username = "Add your GitHub Username"
21        password = "Add your GitHub Token"
22      }
23    }
24  }
25}
26
27// Add the following to your application or library's Gradle file.
28dependencies {
29  implementation("com.checkout:checkout-sdk-3ds-android:3.X.X")
30}

Initialize the SDK and set the:

environment – for example, production or sandbox
locale
3DS challenge UI configuration


1// Option 1: initialize with default configuration
2val checkout3DS = Checkout3DSService(context)
3
4// Option 2: initialize with custom configuration
5val checkout3DS = Checkout3DSService(
6  context,
7  Environment.PRODUCTION,
8  Locale.UK,
9  uiCustomization,
10  Uri.parse("https://sampleAppName.com/3ds_authentication")
11)


1// Option 1: initialize with default configuration
2Checkout3DSService checkout3DS = new Checkout3DSService(context);
3
4// Option 2: initialize with custom configuration
5Checkout3DSService checkout3DS = new Checkout3DSService(
6  context,
7  Environment.PRODUCTION.INSTANCE,
8  Locale.UK,
9  uiCustomisation,
10  Uri.parse("sampleAppScheme://sampleAppName/3ds_authentication")
11);

The SDK's Checkout3DSService class provides the core functionality to perform payment authentication via the authenticate() method.

You only need to initialize the class once for the lifetime of the application.

You must specify an app context when you initialize the SDK. All other configuration options are optional.

When you initialize, you can specify any of the following configuration options:

Parameter	Type	Description
`environment`	`Environment`	The environment the SDK will connect to. For example, `PRODUCTION` or `SANDBOX`. If no value is specified, `PRODUCTION` is used by default.
`locale`	`Locale`	The customer's locale and preferred language. If no value is specified, the device locale is used by default.
`uiCustomization`	`UICustomization`	The UI customization options for the 3DS challenge presented to the customer.
`context`	`Context`	The app context. You must specify an app `context` during initialization, as Android requires this in order to access app resources.
`appUrl`	`URL`	The application URL used to open and move your application to the foreground, as a value of up to 211 characters. Providing this URL can provide a smoother out-of-band challenge experience to the customer as they'll be automatically redirected to your app after their banking app authorizes the transaction, if the card issuer also supports this feature. If your app uses a deep link scheme, ensure the `appURL` links to the current 3DS transaction or app page.

You can use the getWarnings() method to check for any security warnings when you initialize the SDK, or at any time after initialization.

The method returns the following values:

Value Type Description

Value	Type	Description
`id`	`string`	An identifier for the warning. Security warnings IDs are prefixed with `SW`, while initialization warning IDs are prefixed with `CW`.
`message`	`string`	A description of the warning.
`severity`	`string`	The severity of the warning, as a value of either `LOW`, `MEDIUM`, or `HIGH`.

id

string

An identifier for the warning.

Security warnings IDs are prefixed with SW, while initialization warning IDs are prefixed with CW.

message

string

A description of the warning.

severity

string

The severity of the warning, as a value of either LOW, MEDIUM, or HIGH.

The following table outlines the possible id values returned by the getWarnings() method:

Warning ID	Severity	Description
`SW01`	`high`	The app is running on a jailbroken device
`SW02`	`high`	The SDK has been tempered with
`SW03`	`high`	The app is running within an emulator
`SW04`	`medium`	A debugger is attached to the app
`SW05`	`high`	The app is running on an unsupported OS version
`CW01`	`low`	The `appUrl` provided exceeds the 211-character limit and has been ignored
`CW03`	`low`	The `appUrl` provided is not in a recognized Universal App Link format and has been ignored

Before you can begin authentication using the SDK, your back end must first request an authentication session using the Sessions API's

post

Request a session endpoint. See our API reference for all required and optional fields.

In your application code, create an instance of AuthenticationParameters and populate it with the values returned in the Session API response.


1val authenticationParameters = AuthenticationParameters(
2  sessionId = "sessionId",
3  sessionSecret = "sessionSecret",
4  scheme = "scheme"
5)


1AuthenticationParameters authenticationParameters = new AuthenticationParameters(
2  "sessionId", 
3  "sessionSecret", 
4  "scheme");

Parameter Type Description

Parameter	Type	Description
`sessionID`	`string`	The unique ID of the authentication session.
`sessionSecret`	`string`	The session secret.
`scheme`	`string`	The customer's card scheme, as a value of either `Visa`, `Mastercard`, `Jcb`, `Amex`, or `Diners`. The value provided determines which card scheme logo will be displayed to the customer.

sessionID

string

The unique ID of the authentication session.

sessionSecret

string

The session secret.

scheme

string

The customer's card scheme, as a value of either Visa, Mastercard, Jcb, Amex, or Diners.

The value provided determines which card scheme logo will be displayed to the customer.

With the authentication information, the SDK will take care of:

gathering the necessary device data
sharing the information with the customer's bank
if necessary, presenting a native challenge screen to the customer

The type of challenge presented to the customer depends on the configuration of the customer’s bank.

When the authentication process is completed after you call the authenticate() method, the SDK will return the authentication results:

if authentication was successful, the SDK will return a AuthenticationCompleted object – you can then complete the payment with the Payments API, or via an alternative payments service provider
if authentication was unsuccessful, the SDK will return an AuthenticationError object, which you must handle before proceeding

Note

In rare circumstances, there may be inconsistencies between the SDK output and the authentication status. This can be due to timing differences between the SDK, back end, Access Control Server (ACS), and card scheme during the flow.

To ensure that you receive the accurate authentication status (session status), we recommend that you implement one of the following at the end of every authentication flow:

perform a GET session request, referencing the session status
use the authentication_approved, authentication_expired, or authentication_failed webhooks to understand the true session status of the flow


1checkout3DS.authenticate(authenticationParameters, context) { result: AuthenticationResult ->
2  when (result.resultType) {
3    ResultType.Completed -> {
4      // Handle authentication result - continue with the payment based on transaction status
5      val authenticationCompleted: AuthenticationCompleted = (authResult as AuthenticationCompleted)
6      val sdkTransactionId = authenticationCompleted.sdkTransactionId 
7      val transactionStatus = authenticationCompleted.transactionStatus         
8    }
9       
10    ResultTypeError -> {
11      // Handle error (result as AuthenticationError)
12  
13      // Handle error based on error type category
14      val errorType: AuthenticationErrorType = (result as AuthenticationError).errorType
15
16      // Handle error based on fine grained error code or simply log the error
17      val errorCode: String = (result as AuthenticationError).errorCode
18    }
19  }
20}


1checkout3DS.authenticate(authenticationParameters, result -> {
2  switch (result.getEventType()) {
3    case Completed:
4      AuthenticationCompleted authenticationCompleted = (AuthenticationCompleted) result;
5      String sdkTransactionId = authenticationCompleted.getSdkTransactionId();
6      String transactionStatus = authenticationCompleted.getTransactionStatus();
7      // Handle authentication result and continue with payment based on transaction status
8      break;
9
10    case Error:
11      // Handle error
12      AuthenticationError authenticationError = (AuthenticationError) result;
13
14      // Handle error based on error type category
15      AuthenticationErrorType errorType = authenticationError.getErrorType();
16
17      // Handle error based on error code
18      String errorCode = authenticationError.getErrorCode();
19      break;
20  }
21});

Parameter	Type	Description
`authenticationParameters`	`AuthenticationParameters`	The object containing the authentication parameters.
`callback`	`AuthenticationCallback`	The listener to invoke with the result of the authentication process.

Parameter Type Description

Parameter	Type	Description
`resultType`	`ResultType`	Returns the outcome of the authentication. If the value returned is `Completed`, you can proceed with the payment. If the value returned is `Error`, you must handle the error that occurred during authentication.

resultType

ResultType

Returns the outcome of the authentication.

If the value returned is Completed, you can proceed with the payment.

If the value returned is Error, you must handle the error that occurred during authentication.

Parameter Type Description

Parameter	Type	Description
`resultType`	`ResultType`	Returns the outcome of the authentication. In an `AuthenticationCompleted` object, this value will always be `Completed`.
`sdkTransactionID`	`string`	The SDK transaction ID that was received by the 3DS SDK in the final Challenge Response
`transactionStatus`	`string`	The transaction status that was received in the Challenge Response

resultType

ResultType

Returns the outcome of the authentication.

In an AuthenticationCompleted object, this value will always be Completed.

sdkTransactionID

string

The SDK transaction ID that was received by the 3DS SDK in the final Challenge Response

transactionStatus

string

The transaction status that was received in the Challenge Response

Parameter Type Description

Parameter	Type	Description
`resultType`	`ResultType`	Returns the outcome of the authentication. In an `AuthenticationError` object, this value will always be `Error`.
`errorType`	`AuthenticationErrorType`	The type of error that occurred during authentication
`errorCode`	`string`	The transaction status that was received in the Challenge Response

resultType

ResultType

Returns the outcome of the authentication.

In an AuthenticationError object, this value will always be Error.

errorType

AuthenticationErrorType

The type of error that occurred during authentication

errorCode

string

The transaction status that was received in the Challenge Response

Enum value	Description	Retry available
`AuthenticationProcessError`	Authentication did not complete due to the SDK's business rules.
`ConnectivityError`	Communication between the SDK and the remote server could not be established. Retry the authentication.
`ThreeDS2ProtocolError`	The SDK encountered an error specified in the 3DS2 protocol.
`InternalError`	The SDK encountered an error related to the implementation of the SDK.

The value of transactionStatus returned in the AuthenticationResult object determines whether you can proceed with requesting a payment authorization:

Value	Description	Proceed to payment authorization
`A`	Attempt at processing performed
`I`	Informational only
`N`	Not authenticated or account not verified
`R`	Authentication or account verification rejected
`U`	Authentication or account verification could not be performed
`Y`	Authentication verification successful

Information

You can view a transaction's status from the Payments > Processing > All Payments section of the Dashboard.

With the default SDK implementation, the 3DS challenge screens presented to your customers are displayed with a clean, minimalist UI.

The SDK also provides built-in display and accessibility features:

support for different screen sizes and orientations
dynamic text sizing
support for screen-reading technologies, including VoiceOver on iOS and TalkBack on Android
support for 37 languages

If you want to customize the screen to match your app's visual design, you can use the SDK's customization options to change the following properties:

fonts and font colors
navigation bar and footer background colors
action button background colors, opacity, shadows, and corner shapes

To customize the UI, create a new UICustomization instance and include it as an argument when you initialize Checkout3DSService.

The following example demonstrates the customization options available:


1uiCustomization {
2  all {
3    textColor = R.color.styleGreenColor
4    textFont = R.font.raleway
5    tint = R.color.styleGreenColor
6  }
7}


1uiCustomization {
2  navigationBar {
3    backgroundColor = R.color.customStyle1Color1
4    panelElevation = R.dimen.navigationBarElevation1
5
6    heading {
7      textColor = R.color.customStyle1Color6
8      text = R.string.navigationBarHeadingText1
9      textFont = R.font.raleway
10    }
11
12    button {
13      textColor = R.color.customStyle1Color2
14      text = R.string.navigationBarButtonText1
15      textFont = R.font.raleway
16    }
17  }
18
19  informationHeader {
20    textColor = R.color.customStyle1Color1
21    textFont = R.font.raleway
22  }
23
24  informationText {
25    textColor = R.color.customStyle1Color1
26    textFont = R.font.raleway
27  }
28
29  entryLabel {
30    textColor = R.color.customStyle1Color1
31    textFont = R.font.raleway
32  }
33
34  whitelistLabel {
35    thumbColor = R.color.customStyle1Color2
36    textColor = R.color.customStyle1Color5
37    textFont = R.font.raleway
38  }
39
40  actionButton {
41    label {
42      textColor = R.color.customStyle1Color6
43      textFont = R.font.raleway
44    }
45
46    background {
47      backgroundColor = R.color.customStyle1Color1
48      cornerRadius = R.dimen.buttonCornerRadius1
49      bgElevation = R.dimen.buttonElevation1
50    }
51  }
52
53  alternativeButton {
54    label {
55      textColor = R.color.customStyle1Color3
56      textFont = R.font.raleway
57    }
58
59    background {
60      backgroundColor = R.color.customStyle1Color4
61      borderColor = R.color.customStyle1Color3
62      borderWidth = R.dimen.buttonBorderWidth1
63      cornerRadius = R.dimen.buttonCornerRadius1
64      bgElevation = R.dimen.buttonElevation1
65    }
66  }
67
68  entryBox {
69    input {
70      textColor = R.color.customStyle1Color1
71      textFont = R.font.raleway
72    }
73    background {
74      backgroundColor = R.color.customStyle1Color6
75      borderColor = R.color.customStyle1Color2
76      borderWidth = R.dimen.buttonBorderWidth1
77      cornerRadius = R.dimen.buttonCornerRadius1
78      bgElevation = R.dimen.buttonElevation1
79    }
80  }
81
82  entrySelector {
83    selectorColor = R.color.customStyle1Color2
84
85    label {
86      textColor = R.color.customStyle1Color1
87      textFont = R.font.raleway
88    }
89  }
90
91  footer {
92    expandIndicatorColor = R.color.customStyle1Color2
93
94    label {
95      textColor = R.color.customStyle1Color5
96      textFont = R.font.raleway
97    }
98
99    text {
100      textColor = R.color.customStyle1Color5
101      textFont = R.font.raleway
102    }
103  }
104}


1UICustomization uiCustomization = new UICustomization();
2uiCustomization.navigationBar(navigationBarCustom -> {
3  navigationBarCustom.setBackgroundColor(R.color.colorAccent);
4  navigationBarCustom.setPanelElevation(R.dimen.buy_button_min_width);
5  return Unit.INSTANCE;
6});
7uiCustomization.informationHeader(navigationBarCustom -> {
8  navigationBarCustom.setTextColor(R.color.colorAccent);
9  return Unit.INSTANCE;
10});
11// Add customization options as required

In accordance with PCI and EMVCo standards, the 3DS SDK incorporates several security approaches. This maintains the integrity of the SDK and ensures your customers' data is secure.

The 3DS SDK is an encrypted binary. This provides increased protection from a number of threats including tampering and reverse engineering. Additionally, the SDK checks:

if the app was installed from a trusted app store and sends this information to the card issuer
the environment on which it's running and sends warnings to your app and the card issuer if it detects any threat indicators

For example, the following scenarios would be classed as a threat indicator:

the device has unauthorized modifications (also referred to as a jailbroken device), which could enable unrestricted access to critical files
the SDK is running on an emulator
the SDK source code has been tampered with or its functionality has been modified
a debugging application is attached

Information

After you initialize the SDK, check the security warnings for any potential threat indicators before you proceed with a transaction.

To keep your customers' data secure and protect the 3DS process, the SDK takes the following precautions with sensitive data:

only collects sensitive data where it is essential for the authentication process and uses it solely for this purpose
does not disclose sensitive data to channels outside of the 3D Secure process
does not hardcode sensitive data into the SDK except where necessary and permitted
deletes all sensitive data elements once the 3DS transaction is complete

For additional protection, the SDK also:

secures the UI to prevent access from outside the SDK
employs run-time data protection techniques to prevent access by unauthorized services
intercepts and handles any external URL requests contained within 3D Secure HTML – during the 3DS process, the SDK prevents the injection and execution of any JavaScript code by 3D Secure HTML, or any other process outside the 3DS SDK
securely stores any reference data required for the SDK's operation to prevent unauthorized modifications
uses EMVCo-approved cryptographic algorithms and methods in all cryptography handled by the 3DS SDK, and employs cryptographically strong random number generation
uses third-party services to help maintain security

The 3DS SDK communicates with various systems managed by the multiple parties involved in the 3D Secure process. Each of these communication channels is secure and all data exchanged is encrypted.

Communication with the Checkout.com 3DS Server is secured using the latest versions of Transport Layer Security (TLS). The device data passed to the Checkout.com 3DS Server and forwarded to the card scheme’s Directory Server (DS) is transferred in an encrypted format.

Communication with the card issuer’s Access Control Server (ACS) is done over a secure channel that is encrypted end-to-end.

The 3DS SDK also uses Certificate Transparency to ensure end-to-end security and to prevent a man-in-the-middle attack. For this purpose, it checks that all certificates were issued by a trusted Certificate Authority.

Due to the use of Certificate Transparency, the 3DS SDK may not be able to establish a secure connection on devices that are connected to certain SSL Proxy Servers.

In these scenarios, the 3DS SDK will return a connectivity error, which you can communicate to your customer. We recommend that your customer switches to a mobile data connection where available.

We regularly update our 3DS SDK and review our security guidance.

As with our core Standalone authentication product, you can use the 3DS SDK to authenticate a payment and continue to payment authorization with a different payment services provider.

You can also use the 3DS SDK to authenticate with a different provider as part of a custom solution. Contact your Account Manager or [email protected] to discuss this option.

3DS Android SDK

Information

3DS flows

Frictionless flow

Challenge flow

Information

Integrate the 3DS SDK

Before you start

Step 1: Add the SDK as a project dependency

Information

Minimum requirements

Information

Add the SDK dependency

Step 2: Initialize the SDK

Checkout3DSService

Check for security warnings

Warning IDs

Step 3: Configure authentication parameters

Step 4: Handle authentication results

Note

Information

Step 5: Customize the 3DS Challenge UI

Simplified customization

Full customization

Security

SDK integrity protection

Information

Sensitive data protection

Communication security

Compatibility with third-parties