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.


1// 1. Init with defaults
2let checkout3DS = Checkout3DSService()
3
4// 2. Init with explicit arguments
5let checkout3DS = Checkout3DSService(
6    environment: .production,
7    locale: Locale(identifier: "en_GB"),
8    uiCustomization: uiCustomization,
9    appURL: URL(string: "myapp://my-app-url")!
10)
11
12let authenticationParameters = AuthenticationParameters(
13    sessionID: sessionID,
14    sessionSecret: sessionSecret,
15    scheme: scheme)
16
17checkout3DS.authenticate(authenticationParameters: authenticationParameters) { error in
18    if let error = error {
19        // Handle error.
20    } else {
21        // Continue with payment.
22    }
23}


1// 1. Init with defaults
2CKOCheckout3DSService *checkout3DS2 = [[CKOCheckout3DSService alloc] init];
3
4// 2. Init with explicit arguments
5CKOCheckout3DSService *checkout3DS2 = [[CKOCheckout3DSService alloc] initWithEnvironment:CKOEnvironmentProduction
6                                                                                    locale:[NSLocale localeWithLocaleIdentifier:@"en_GB"]
7                                                                           uiCustomization:uiCustomization
8                                                                                    appURL:[NSURL URLWithString:@"myapp://my-app-url"]];
9
10CKOAuthenticationParameters *authenticationParameters = [[CKOAuthenticationParameters alloc] initWithSessionID:sessionID
11                                                                                                 sessionSecret:sessionSecret
12                                                                                                        scheme:scheme];
13
14[checkout3DS2 authenticateWithAuthenticationParameters:authenticationParameters
15                                     completionHandler:^(NSError * _Nullable error) {
16    if (error) {
17        // Handle error.
18    } else {
19       // Continue with payment.
20    }
21}];


1// 1. Init with defaults
2val checkout3DS = Checkout3DSService(context)
3
4// 2. Init with explicit arguments
5val checkout3DS = Checkout3DSService(
6        context,
7        Environment.PRODUCTION,
8        Locale.UK,
9        uiCustomization,
10        Uri.parse("sampleAppScheme://sampleAppName/3ds_authentication")
11)
12
13val authenticationParameters = AuthenticationParameters(
14    sessionId,
15    sessionSecret,
16    scheme)
17
18checkout3DS.authenticate(authenticationParameters, context) { result: AuthenticationResult ->
19    when (result.eventType) {
20        Successful -> {
21            // continue with payment, show √
22        }
23        Failed -> {
24            // terminate payment, show X
25        }
26        Error -> {
27            // handle error (result as AuthenticationError)
28
29            // handle error based on error type category
30            val errorType: AuthenticationErrorType = (result as AuthenticationError).errorType
31
32            // Handle error based on fine grained error code or simply log the error
33            val errorCode: String = (result as AuthenticationError).errorCode
34        }
35    }
36}


1// 1. Init with defaults
2Checkout3DSService checkout3DS = new Checkout3DSService(context);
3
4// 2. Init with explicit arguments
5Checkout3DSService checkout3DS = new Checkout3DSService(
6        context,
7        Environment.PRODUCTION.INSTANCE,
8        Locale.UK,
9        uiCustomization,
10        Uri.parse("sampleAppScheme://sampleAppName/3ds_authentication")
11);
12
13AuthenticationParameters authenticationParameters = AuthenticationParameters(
14    sessionId,
15    sessionSecret,
16    scheme)
17
18checkout3DS.authenticate(authenticationParameters, result -> {
19    switch (result.getEventType()) {
20        case Successful:
21            // continue with payment, show √
22            break;
23        case Failed:
24            // terminate payment, show X
25            break;
26        case Error:
27            // handle error
28            AuthenticationError authenticationError = (AuthenticationError) result;
29
30            // handle error based on error type category
31            AuthenticationErrorType errorType = authenticationError.getErrorType();
32
33            // Handle error based on fine grained error code.
34            String errorCode = authenticationError.getErrorCode();
35            break;
36    }
37});

Download the relevant 3D Secure mobile SDK from GitHub:
- iOS 3D Secure mobile SDK
- Android 3D Secure mobile SDK
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 {
3    repositories {
4        maven {
5           url = uri("https://maven.pkg.github.com/checkout/checkout-3ds-sdk-android")
6           credentials {
7               username = ""
8               password = ""
9           }
10        }
11    }
12}
13
14// Add the following to the module level build.gradle.kts file.
15dependencies {
16    implementation("com.checkout:checkout-sdk-3ds-android:")
17}


1// Add the following to your project’s top-level build.gradle file.
2allprojects {
3    repositories {
4        maven {
5            url 'https://maven.pkg.github.com/checkout/checkout-3ds-sdk-android'
6            credentials {
7                username ''
8                password ''
9            }
10        }
11    }
12}
13
14// Add the following to the module level build.gradle file.
15dependencies {
16    implementation 'com.checkout:checkout-sdk-3ds-android:'
17}


1pod 'Checkout3DS', :git => 'git@github.com:checkout/checkout-3ds-sdk-ios.git', :tag => ''

Initialize the SDK, setting the environment (production or sandbox), the locale, and your preferred challenge user interface options.


1// 1a. Initialize with default arguments
2let checkout3DS = Checkout3DSService()
3
4// 1b. Alternatively, initialize with explicit arguments
5let checkout3DS = Checkout3DSService(
6   environment: .production,
7   locale: Locale(identifier: "en_GB"),
8   uiCustomization: uiCustomization,
9   appURL: URL(string: "https://my-app-url.com")!
10)


1// 1a. Initialize with default arguments
2CKOCheckout3DSService *checkout3DS2 = [[CKOCheckout3DSService alloc] init];
3
4// 1b. Alternatively, initialize with explicit arguments
5CKOCheckout3DSService *checkout3DS2 = [[CKOCheckout3DSService alloc] initWithEnvironment:CKOEnvironmentProduction
6                                                                                  locale:[NSLocale localeWithLocaleIdentifier:@"en_GB"]
7                                                                         uiCustomization:uiCustomization
8                                                                                  appURL:[NSURL URLWithString:@"https://my-app-url.com"]];


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


1// 1a. Initialize with default arguments
2Checkout3DSService checkout3DS = new Checkout3DSService(context);
3
4// 1b. Alternatively, initialize with explicit arguments
5Checkout3DSService checkout3DS = new Checkout3DSService(
6        context,
7        Environment.PRODUCTION,
8        Locale.UK,
9        uiCustomization,
10        Uri.parse("https://sampleAppName.com/3ds_authentication")
11);

This is the main class of the SDK that performs payment authentication with the authenticate method. It only needs to be initialized once for the lifetime of the application, and is initialized with the following parameters.

Field name	Field type	Description
`environment` optional	`Environment`	The environment the SDK will connect to (`PRODUCTION or SANDBOX`). Default: PRODUCTION
`locale` optional	`Locale`	The customer's locale and preferred language. Default: the device locale
`uiCustomization` optional	`uiCustomization`	The customizations for the challenge user interface.
`appUrl` optional	`URL`	The application URL used to open and move your application to the foreground. This field is optional, but we recommend including it to ensure a smoother out-of-band challenge experience for your user. This way, the user is automatically redirected back to your app after their banking app has authorized the transaction. This feature is available if the user’s card issuer also supports it. Note If your app uses a deep link scheme, make sure that the `appURL` field value links to the current 3D Secure transaction or app page. The `appUrl` field value can have up to 211 characters. If it exceeds 211 characters, it is ignored and the SDK returns an initialization warning.

Field name	Field type	Description
`environment` optional	`Environment`	The environment the SDK will connect to (`PRODUCTION or SANDBOX`). Default: PRODUCTION
`locale` optional	`Locale`	The customer's locale and preferred language. Default: the device locale
`uiCustomization` optional	`uiCustomization`	The customizations for the challenge user interface.
`context` required	`Context`	The app context. Required for Android to access app resources.
`appUrl` optional	`URL`	The application URL used to open and move your application to the foreground. This field is optional, but we recommend including it to ensure a smoother out-of-band challenge experience for your user. This way, the user is automatically redirected back to your app after their banking app has authorized the transaction. This feature is available if the user’s card issuer also supports it. Note If your app uses a deep link scheme, make sure that the `appURL` field value links to the current 3D Secure transaction or app page. The `appUrl` field value can have up to 211 characters. If it exceeds 211 characters, it is ignored and the SDK returns an initialization warning.

Optionally, you can use the getWarnings method to check for any security warnings when initializing the SDK, or any time afterwards. It will return the following information:

Field name Description

Field name	Description
`id` string required	An identifier of the warning. Security warnings are in the format `SWxx`, and initialization warnings use the format `CWxx`.
`message` string required	The warning description
`severity` string required	The severity of the warning. It can be either `low`, `medium`, or `high`.

id

string

required

An identifier of the warning. Security warnings are in the format SWxx, and initialization warnings use the format CWxx.

message

string

required

The warning description

severity

string

required

The severity of the warning. It can be either low, medium, or high.

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(
2    sessionID: sessionID,
3    sessionSecret: sessionSecret,
4    scheme: scheme)


1CKOAuthenticationParameters *authenticationParameters = [[CKOAuthenticationParameters alloc] initWithSessionID:sessionID
2                                                                                                 sessionSecret:sessionSecret
3                                                                                                        scheme:scheme];


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


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

Parameter name Parameter type Description

Parameter name	Parameter type	Description
`authenticationParameters` required	`AuthenticationParameters`	The authentication parameters, including `sessionId`, `sessionSecret`, and `scheme`.
`completionHandler` required	`(AuthenticationError?) → Void`	Closure that is called with the error that occurred during authentication, or `nil` if the authentication is successful.

authenticationParameters

required

AuthenticationParameters

The authentication parameters, including sessionId, sessionSecret, and scheme.

completionHandler

required

(AuthenticationError?) → Void

Closure that is called with the error that occurred during authentication, or nil if the authentication is successful.

Parameter name Description

Parameter name	Description
`sessionID` string required	The unique ID of the authentication session. You will have received this in the response to the create session call to our Sessions API.
`sessionSecret` string required	The session secret. You will have received this in the response to the create session call to our Sessions API.
`scheme` string required	The name of the customer's card scheme: `Visa`, `Mastercard`, `Jcb`, `Amex`, or `Diners`. Used to display the scheme's logo on the progress user interface.

sessionID

string

required

The unique ID of the authentication session. You will have received this in the response to the create session call to our Sessions API.

sessionSecret

string

required

The session secret. You will have received this in the response to the create session call to our Sessions API.

scheme

string

required

The name of the customer's card scheme: Visa, Mastercard, Jcb, Amex, or Diners. Used to display the scheme's logo on the progress user interface.

Parameter name Parameter type Description

Parameter name	Parameter type	Description
`authenticationParameters` required	`AuthenticationParameters`	The authentication parameters, including `sessionId`, `sessionSecret`, and `scheme`.
`callback` required	`AuthenticationCallback`	The AuthenticationCallback listener to be invoked with the result of the authentication process.

authenticationParameters

required

AuthenticationParameters

The authentication parameters, including sessionId, sessionSecret, and scheme.

callback

required

AuthenticationCallback

The AuthenticationCallback listener to be invoked with the result of the authentication process.

Parameter name Description

Parameter name	Description
`sessionId` string required	The unique ID of the authentication session. You will have received this in the response to the create session call to our Sessions API.
`sessionSecret` string required	The session secret. You will have received this in the response to the create session call to our Sessions API.
`scheme` string required	The name of the customer's card scheme: `Visa`, `Mastercard`, `Jcb`, `Amex`, or `Diners`. Used to display the scheme's logo on the progress user interface.

sessionId

string

required

The unique ID of the authentication session. You will have received this in the response to the create session call to our Sessions API.

sessionSecret

string

required

The session secret. You will have received this in the response to the create session call to our Sessions API.

scheme

string

required

The name of the customer's card scheme: Visa, Mastercard, Jcb, Amex, or Diners. Used to display the scheme's logo on the progress user interface.

Once the authentication is completed, the SDK returns a result.

On Android, the result is either Successful, Failed, or Error.
On iOS, the SDK returns an optional AuthenticationError. If the attempt was unsuccessful, this indicates the failure reason, otherwise this value is nil.

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 in
2    if let error = error {
3        // Handle error.
4    } else {
5        // Continue with payment.
6    }
7}


1[checkout3DS2 authenticateWithAuthenticationParameters:authenticationParameters
2                                                                            completionHandler:^(NSError * _Nullable error) {
3    if (error) {
4        // Handle error.
5    } else {
6       // Continue with payment.
7    }
8}];


1checkout3DSService!!.authenticate(authenticationParams) { result: AuthenticationResult ->
2    when (result.resultType) {
3        ResultType.Successful -> {
4            // continue with payment, show √
5        }
6        ResultType.Failed -> {
7            // terminate payment, show X
8        }
9        ResultType.Error -> {
10            // handle error (result as AuthenticationError)
11            // handle error based on error type category
12            val errorType: AuthenticationErrorType = (result as AuthenticationError).errorType
13            // Handle error based on fine grained error code or simply log the error
14            val errorCode: String = (result as AuthenticationError).errorCode
15        }
16    }
17}


1checkout3DSService.authenticate(authenticationParams, result -> {
2    switch (result.getResultType()) {
3        case Successful:
4            // continue with payment, show √
5            break;
6        case Failed:
7            // terminate payment, show X
8            break;
9        case Error:
10            // handle error
11            AuthenticationError authenticationError = (AuthenticationError) result;
12            // handle error based on error type category
13            AuthenticationErrorType errorType = authenticationError.getErrorType();
14            // Handle error based on fine grained error code.
15            String errorCode = authenticationError.getErrorCode();
16            break;
17    }
18});

This enumeration contains all the possible errors that might occur during authentication. Each error has a readable name and an associated error code.

Information

Swift uses AuthenticationError, but Objective-C uses NSError.

Represents the outcome of the authentication.

Field name	Field type	Description
`resultType`	`ResultType`	Returns the outcome of the authentication

The resultType will be one of the following:

Successful – Authentication was successful. You can proceed with the payment.
Failed – Authentication was unsuccessful. You cannot proceed with the payment.
Error – An error occurred during authentication. You will need to handle the error.

Represents the details of the error that occurred during authentication. The error object contains two bits of information: the errorType and the errorCode.

Field name	Field type	Description
`resultType`	`ResultType`	The authentication result. It will always be `Error`.
`errorType`	`AuthenticationErrorType`	The type of error that occurred.
`errorCode`	`String`	The error code.

The errorType will be one of the following:

Parameter name	Can I retry authentication?	Description
`AuthenticationProcessError`		The authentication did not complete due to the business rules of the SDK.
`ConnectivityError`		The communication between the SDK and the remote server could not be established. We recommend retrying authentication if this occurs.
`ThreeDS2ProtocolError`		The SDK encountered an error specified in the 3DS2 protocol.
`InternalError`		The SDK encountered an error related to the implementation of the SDK.

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 {
2    let toolbarCustomization: ToolbarCustomization = DefaultToolbarCustomization(
3        backgroundColor: .blue,
4        headerTitle: "3DS Check",
5        buttonTitle: "Cancel",
6        font: UIFont(name: "Optima-Bold", size: 20)!,
7        textColor: .black)
8    let labelCustomization: LabelCustomization = DefaultLabelCustomization(
9        headingTextColor: .purple,
10        headingFont: UIFont(name: "Optima-Bold", size: 16)!,
11        font: UIFont(name: "Optima-Regular", size: 16)!,
12        textColor: .orange)
13    let buttonCustomizations: ButtonCustomizations = DefaultButtonCustomizations(
14        verifyButtonCustomization: DefaultButtonCustomization(
15            backgroundColor: .red,
16            cornerRadius: 24,
17            cornerCurve: .circular,
18            font: UIFont(name: "Optima-Regular", size: 14)!,
19            textColor: .white,
20            borderWidth: 0,
21            borderColor: UIColor.clear.cgColor),
22        continueFlowButtonCustomization: DefaultButtonCustomization(
23            backgroundColor: UIColor.blue,
24            cornerRadius: 24,
25            cornerCurve: .circular,
26            font: UIFont(name: "Optima", size: 14)!,
27            textColor: .white,
28            borderWidth: 0,
29            borderColor: UIColor.clear.cgColor))
30    let whitelistCustomization: WhitelistCustomization = DefaultWhitelistCustomization(
31        font: UIFont(name: "Optima-Regular", size: 16)!,
32        textColor: .black,
33        switchTintColor: .green)
34    let footerCustomization: FooterCustomization = DefaultFooterCustomization(
35        backgroundColor: .clear,
36        font: UIFont(name: "Optima-Bold", size: 16)!,
37        textColor: .black,
38        labelFont: UIFont(name: "Optima-Regular", size: 16)!,
39        labelTextColor: .blue,
40        expandIndicatorColor: .green)
41    let entrySelectionCustomization: EntrySelectionCustomization = DefaultEntrySelectionCustomization(
42            borderWidth: 1,
43            borderColor: UIColor.blue.cgColor,
44            cornerRadius: 4,
45            cornerCurve: .continuous,
46            font: .systemFont(ofSize: 16),
47            textColor: .black,
48            borderStyle: .line,
49            backgroundColor: .white,
50            unselectedColor: .white,
51            selectedColor: .blue)
52}


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
20    informationHeader {
21        textColor = R.color.customStyle1Color1
22        textFont = R.font.raleway
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
83    entrySelector {
84        selectorColor = R.color.customStyle1Color2
85
86        label {
87            textColor = R.color.customStyle1Color1
88            textFont = R.font.raleway
89        }
90    }
91
92    footer {
93        expandIndicatorColor = R.color.customStyle1Color2
94
95        label {
96            textColor = R.color.customStyle1Color5
97            textFont = R.font.raleway
98        }
99
100        text {
101            textColor = R.color.customStyle1Color5
102            textFont = R.font.raleway
103        }
104    }
105}

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.

We've made some changes to our API

3D Secure mobile SDKs

Your customers' data

Tip

The 3DS2 customer experience

Frictionless flow

Challenge flow

Customize the challenge UI

How it works

Implementation examples

Integrate the 3D Secure SDK into your app

Add the 3D Secure SDK to your app's payment flow

Step 1: Initialize the SDK

Checkout3DSService

Note

Note

Check for security warnings

Step 2: Configure the authentication parameters

authenticate method parameters

authenticationParameters properties

authenticate method parameters

authenticationParameters properties

Step 3: Request authentication and handle the result

AuthenticationError

Information

AuthenticationResult

AuthenticationError

Customize the challenge user interface

Security

Protecting the integrity of the 3D Secure SDK

Security warnings

Protecting sensitive data

Secure communication

Disabling certificate transparency checks

Certificate transparency and SSL proxy servers

Keeping you informed