3D Secure mobile SDKs
Last updated: April 29, 2022
Our 3D Secure (3DS) mobile SDKs allow you to provide a native 3DS2 experience in your Android and iOS apps, with visual styling that you can control.
They work with our non-hosted authentication solution, so you can authenticate within the payment authorization flow, or perform only authentication and complete the payment later.
Once you've initiated the authentication, the SDK handles the tasks of collecting device data, exchanging information with the customer's bank, and, if necessary, presenting a challenge to the customer. You can then use the authentication result to authorize the payment.
Your customers' data
Our SDKs collect only data which your app has permission to collect, and it is encrypted throughout authentication. The customer will never be prompted to grant new permissions. We don't store any of the device data collected during authentication, and our SDKs do not retain any personal information about the user.
Tip
Our 3D Secure SDK supports 3DS2 (version 2.1.0 and, if your configuration supports it, 2.2.0). It also supports 3DS1 in cases where 3DS2 is not available. However, this feature must be enabled for your account. The SDK handles the version complexity for you, and passes a simple authentication result back to your app, regardless of the 3D Secure version used.
3DS2 allows you and your payment provider to share more data (like the customer's device ID and payment history) with the customer's bank so they can better assess the risk of the transaction and select the appropriate response: either the "frictionless flow" or "challenge flow".
If the customer's bank is satisfied with the data and trusts that it is the cardholder making the payment, the transaction will be authenticated without interrupting the customer. All the customer will see of the 3DS process is a short "processing" overlay, with branding from their card scheme.

If, however, the bank decides it needs further proof, they will prompt the customer to verify their identity. This can take one of the following forms:
One-time password. The customer's bank sends a single use password or code to the customer, usually as a text message or email, and asks them to enter it.
Single-select or multi-select. The bank asks the customer a multiple choice question, with either a single or multiple selections allowed.
Out-of-band. The customer is asked to confirm the transaction through another channel, typically their banking app. (See example below.)
HTML. The customer's bank defines the exact view to be presented to the customer, using HTML formatting. The challenge may take one of the above forms, or the bank may devise their own approach.

Customize the challenge UI
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 SDKs give you control over the display of the native challenges in your app, while ensuring that the rules are followed.
To use one of our 3DS mobile SDKs, first integrate the library into your project. Then, configure your iOS or Android app to:
- Initialize the SDK with your preferred user interface options.
- Configure the parameters for an authentication.
- Request authentication and handle the result to continue your payment flow.
Below are some code examples for each platform.
- Download the relevant 3D Secure mobile SDK from GitHub:
- Install the SDK:
- For iOS, install the library in your app project using CocoaPods.
- For Android, add the library to your app as a Gradle dependency.
1// Add the following to your project’s top-level build.gradle.kts file.2allprojects {3repositories {4maven {5url = uri("https://maven.pkg.github.com/checkout/checkout-3ds-sdk-android")6credentials {7username = ""8password = ""9}10}11}12}1314// Add the following to the module level build.gradle.kts file.15dependencies {16implementation("com.checkout:checkout-sdk-3ds-android:")17}
Initialize the SDK, setting the environment (production or sandbox), the locale, and your preferred challenge user interface options.
1// 1a. Initialize with default arguments2let checkout3DS = Checkout3DSService()34// 1b. Alternatively, initialize with explicit arguments5let checkout3DS = Checkout3DSService(6environment: .production,7locale: Locale(identifier: "en_GB"),8uiCustomization: uiCustomization,9appURL: URL(string: "https://my-app-url.com")!10)
After your backend has requested an authentication session with our Sessions API, you will receive a response.
Use the authenticate
method to start the authentication, passing the values you received in the Sessions API response into authenticationParameters
.
The SDK will then gather the device data, share the information with the customer's bank, and, if necessary, present a challenge to the customer.
1let authenticationParameters = AuthenticationParameters(2sessionID: sessionID,3sessionSecret: sessionSecret,4scheme: scheme)
Once the authentication is completed, the SDK returns a result.
- On Android, the result is either
Successful
,Failed
, orError
. - On iOS, the SDK returns an optional
AuthenticationError
. If the attempt was unsuccessful, this indicates the failure reason, otherwise this value isnil
.
If successful, you can use our Payments API to complete the payment, or use another payment services provider to do so.
1checkout3DS.authenticate(authenticationParameters: authenticationParameters) { error in2if let error = error {3// Handle error.4} else {5// Continue with payment.6}7}
We’ve built a simple, clean default style for the native challenge user interfaces, so you can quickly get going without defining your own style. But if you want to tailor the challenge screens in your app, our SDKs let you control:
- Fonts and font colors.
- The background color of the navigation bar and footer.
- The background color, opacity, shadows, and corner radiuses of the action buttons.
Our SDKs also handle different screen sizes and orientations, and allow you to address different user needs with dynamic text sizing, TalkBack and VoiceOver assistance, and support for 37 languages (though the body of the challenge screens is always presented in the language provided by the customer's bank).
To apply your own style, simply include a UI Customization object when you initialize the SDK. We've included some code examples below to show you how you might build the object.
1final class Customization1: UICustomization {2let toolbarCustomization: ToolbarCustomization = DefaultToolbarCustomization(3backgroundColor: .blue,4headerTitle: "3DS Check",5buttonTitle: "Cancel",6font: UIFont(name: "Optima-Bold", size: 20)!,7textColor: .black)8let labelCustomization: LabelCustomization = DefaultLabelCustomization(9headingTextColor: .purple,10headingFont: UIFont(name: "Optima-Bold", size: 16)!,11font: UIFont(name: "Optima-Regular", size: 16)!,12textColor: .orange)13let buttonCustomizations: ButtonCustomizations = DefaultButtonCustomizations(14verifyButtonCustomization: DefaultButtonCustomization(15backgroundColor: .red,16cornerRadius: 24,17cornerCurve: .circular,18font: UIFont(name: "Optima-Regular", size: 14)!,19textColor: .white,20borderWidth: 0,21borderColor: UIColor.clear.cgColor),22continueFlowButtonCustomization: DefaultButtonCustomization(23backgroundColor: UIColor.blue,24cornerRadius: 24,25cornerCurve: .circular,26font: UIFont(name: "Optima", size: 14)!,27textColor: .white,28borderWidth: 0,29borderColor: UIColor.clear.cgColor))30let whitelistCustomization: WhitelistCustomization = DefaultWhitelistCustomization(31font: UIFont(name: "Optima-Regular", size: 16)!,32textColor: .black,33switchTintColor: .green)34let footerCustomization: FooterCustomization = DefaultFooterCustomization(35backgroundColor: .clear,36font: UIFont(name: "Optima-Bold", size: 16)!,37textColor: .black,38labelFont: UIFont(name: "Optima-Regular", size: 16)!,39labelTextColor: .blue,40expandIndicatorColor: .green)41let entrySelectionCustomization: EntrySelectionCustomization = DefaultEntrySelectionCustomization(42borderWidth: 1,43borderColor: UIColor.blue.cgColor,44cornerRadius: 4,45cornerCurve: .continuous,46font: .systemFont(ofSize: 16),47textColor: .black,48borderStyle: .line,49backgroundColor: .white,50unselectedColor: .white,51selectedColor: .blue)52}
The 3DS mobile SDK implements security approaches in compliance with PCI and EMVCo standards to ensure your customers' data is secure.
Below you can find guidelines on how to configure your app to maximize the security of the 3D Secure process.
The 3D Secure SDK uses the following security approaches:
The SDK checks if the app was installed from a trusted app store and sends this information to the card issuer.
The SDK is an encrypted binary which provides increased protection from a number of threats including tampering and reverse engineering.
The SDK checks the environment on which it's running. If it detects threat indicators, it sends warnings to your app and the card issuer. Possible indicators are:
the device has been jailbroken, which means it has been modified to 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.
Security warnings
We recommend that your app uses the SDK warnings to check for security issues before continuing with a transaction. This should be done after initializing the SDK and before proceeding with an authentication request. To get a list of the warnings, see the "Check for security warnings" section under "Add the 3D Secure SDK to your app's payment flow".
The 3D Secure SDK uses the following approaches to keep your customers' data secure and protect the 3D Secure process:
The SDK only collects sensitive data where it is essential for the authentication process and uses it for this purpose only. Sensitive data are not disclosed to channels outside of the 3D Secure process, and are not hardcoded into the SDK except where necessary and permitted. All sensitive data elements are deleted once the 3D Secure transaction is complete.
The user interface is secured, to prevent access from outside the SDK.
The SDK employs run-time data protection techniques to prevent access by unauthorized services.
The SDK intercepts and handles any external URL requests contained within 3D Secure 2 HTML. During 3DS2 processing, the SDK prevents the injection and execution of any JavaScript code by 3D Secure HTML or any other process outside the 3D Secure SDK.
Reference data required by the SDK to operate is securely stored to prevent unauthorized modification.
All cryptography handled by the 3D Secure SDK uses EMVCo-approved cryptographic algorithms and methods, as well as cryptographically strong random number generation.
We use third-party services to help maintain security. See the reference documents for more details.
The 3DS SDK communicates with different systems managed by the 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 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.
Disabling certificate transparency checks
Do not disable certificate transparency checks by using a wildcard domain in your iOS app’s .plist
file. This interferes with the SDK operations and may result in a failure. For more information, see the Apple documentation on NSAppTransportSecurity and NSExceptionDomains.
Certificate transparency and SSL proxy servers
As a system that uses Certificate Transparency, the 3DS SDK may not be able to establish a secure connection on devices that are connected to some SSL Proxy Servers.
In these scenarios, the 3DS SDK returns a connectivity error. You may want to consider communicating this to your customer. We recommend that they switch to a mobile data connection where available.
We regularly update our 3D Secure SDK and review our security guidance. For full details of the changes included in each SDK update, see the release notes.