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:

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

Below are some code examples for each platform.

// 1. Init with defaults
let checkout3DS = Checkout3DSService()

// 2. Init with explicit arguments
let checkout3DS = Checkout3DSService(
    environment: .production,
    locale: Locale(identifier: "en_GB"),
    uiCustomization: uiCustomization,
    appURL: URL(string: "myapp://my-app-url")!
)

let authenticationParameters = AuthenticationParameters(
    sessionID: sessionID,
    sessionSecret: sessionSecret,
    scheme: scheme)

checkout3DS.authenticate(authenticationParameters: authenticationParameters) { error in
    if let error = error {
        // Handle error.
    } else {
        // Continue with payment.
    }
}

// 1. Init with defaults
CKOCheckout3DSService *checkout3DS2 = [[CKOCheckout3DSService alloc] init];

// 2. Init with explicit arguments
CKOCheckout3DSService *checkout3DS2 = [[CKOCheckout3DSService alloc] initWithEnvironment:CKOEnvironmentProduction
                                                                                    locale:[NSLocale localeWithLocaleIdentifier:@"en_GB"]
                                                                           uiCustomization:uiCustomization
                                                                                    appURL:[NSURL URLWithString:@"myapp://my-app-url"]];

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

[checkout3DS2 authenticateWithAuthenticationParameters:authenticationParameters
                                     completionHandler:^(NSError * _Nullable error) {
    if (error) {
        // Handle error.
    } else {
       // Continue with payment.
    }
}];

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.

// Add the following to your project’s top-level build.gradle.kts file.
allprojects {
    repositories {
        maven {
           url = uri("https://maven.pkg.github.com/checkout/checkout-3ds-sdk-android")
           credentials {
               username = ""
               password = ""
           }
        }
    }
}

// Add the following to the module level build.gradle.kts file.
dependencies {
    implementation("com.checkout:checkout-sdk-3ds-android:")
}

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

// 1a. Initialize with default arguments
let checkout3DS = Checkout3DSService()

// 1b. Alternatively, initialize with explicit arguments
let checkout3DS = Checkout3DSService(
   environment: .production,
   locale: Locale(identifier: "en_GB"),
   uiCustomization: uiCustomization,
   appURL: URL(string: "https://my-app-url.com")!
)

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.

let authenticationParameters = AuthenticationParameters(
    sessionID: sessionID,
    sessionSecret: sessionSecret,
    scheme: scheme)

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

If successful, you can use our Payments API to complete the payment, or use another payment services provider to do so.

checkout3DS.authenticate(authenticationParameters: authenticationParameters) { error in
    if let error = error {
        // Handle error.
    } else {
        // Continue with payment.
    }
}

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:

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.

final class Customization1: UICustomization {
    let toolbarCustomization: ToolbarCustomization = DefaultToolbarCustomization(
        backgroundColor: .blue,
        headerTitle: "3DS Check",
        buttonTitle: "Cancel",
        font: UIFont(name: "Optima-Bold", size: 20)!,
        textColor: .black)
    let labelCustomization: LabelCustomization = DefaultLabelCustomization(
        headingTextColor: .purple,
        headingFont: UIFont(name: "Optima-Bold", size: 16)!,
        font: UIFont(name: "Optima-Regular", size: 16)!,
        textColor: .orange)
    let buttonCustomizations: ButtonCustomizations = DefaultButtonCustomizations(
        verifyButtonCustomization: DefaultButtonCustomization(
            backgroundColor: .red,
            cornerRadius: 24,
            cornerCurve: .circular,
            font: UIFont(name: "Optima-Regular", size: 14)!,
            textColor: .white,
            borderWidth: 0,
            borderColor: UIColor.clear.cgColor),
        continueFlowButtonCustomization: DefaultButtonCustomization(
            backgroundColor: UIColor.blue,
            cornerRadius: 24,
            cornerCurve: .circular,
            font: UIFont(name: "Optima", size: 14)!,
            textColor: .white,
            borderWidth: 0,
            borderColor: UIColor.clear.cgColor))
    let whitelistCustomization: WhitelistCustomization = DefaultWhitelistCustomization(
        font: UIFont(name: "Optima-Regular", size: 16)!,
        textColor: .black,
        switchTintColor: .green)
    let footerCustomization: FooterCustomization = DefaultFooterCustomization(
        backgroundColor: .clear,
        font: UIFont(name: "Optima-Bold", size: 16)!,
        textColor: .black,
        labelFont: UIFont(name: "Optima-Regular", size: 16)!,
        labelTextColor: .blue,
        expandIndicatorColor: .green)
    let entrySelectionCustomization: EntrySelectionCustomization = DefaultEntrySelectionCustomization(
            borderWidth: 1,
            borderColor: UIColor.blue.cgColor,
            cornerRadius: 4,
            cornerCurve: .continuous,
            font: .systemFont(ofSize: 16),
            textColor: .black,
            borderStyle: .line,
            backgroundColor: .white,
            unselectedColor: .white,
            selectedColor: .blue)
}