3D Secure mobile SDKs

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.

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.

To use one of our 3DS mobile SDKs, first integrate the library into your project. Then, configure your iOS or Android app to:

1. Initialize the SDK with your preferred user interface options.
2. Configure the parameters for an authentication.
3. Request authentication and handle the result to continue your payment flow.

Below are some code examples for each platform.

swift
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}

objc
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}];

To gain access to the 3D Secure mobile SDKs, contact your Customer Success Manager or Integrations engineer, or email us at support@checkout.com.

Then, on iOS, install the library in your app project using CocoaPods. For Android, add the library to your app as a Gradle dependency.

kotlin
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}

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

swift
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)

Default: PRODUCTION

Default: the device locale

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.

swift
1let authenticationParameters = AuthenticationParameters(
2    sessionID: sessionID,
3    sessionSecret: sessionSecret,
4    scheme: scheme)

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.

swift
1checkout3DS.authenticate(authenticationParameters: authenticationParameters) { error in
2    if 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.

swift
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}