iOS 3D Secure SDK

The Checkout.com 3D Secure (3DS) mobile SDK allows you to provide a native 3DS2 experience in your mobile app, with visual styling that you can control.

The SDK handles the device data collection, communication with the card issuer, and presentation of 3D Secure challenges to the customer when required.

• Features
• Minimum Requirements
• Installation
  • Swift Package Manager
• Integration
  • Checkout.com’s 3DS server
• Payment Authorisation
• Dependencies
• Help and Feedback
• License

👉  See the Integration Guide with Code Examples

📚  Read the reference documentation

Features

• Supports 3D Secure protocol 2.2.0.
• Presents native 3DS2 challenge screens to the user, with styling that you can customise to best fit your apps and branding.
• Optionally falls back to 3DS1 when 3DS2 is not available, returning the same authentication result to your app as for 3DS2. (This option can be configured by Checkout.com for your account.)
• Supports a range of local languages and accessibility needs, and allows you to set your own string translations.
• Meets requirements from EMVCo and the PCI Security Standards Council, specifically set for 3DS SDKs, so you can be sure it is interoperable with card issuers and that your customers’ sensitive data stays secure.

Minimum Requirements

• The 3DS SDK for iOS requires Xcode 16.1 and above with Swift version 6.1.2 and above, and supports apps targeting iOS 13.0 and above. It also supports Objective-C.
• We have discontinued support for intel machines (x86_64 architecture based environments). You must use ARM64 architecture based environments to compile our 3DS iOS SDK.

Installation

We’ve done our best to support the most common distribution methods on iOS. We are in strong favour of SPM (Swift Package Manager)

Swift Package Manager

⚠️ Important

SPM (Swift Package Manager) and CocoaPods can usually coexist in the same project without issues. That said, since CocoaPods is now in maintenance mode, the iOS team made a tech decision to officially support only SPM going forward. It’s simpler to manage and already works well alongside CocoaPods if needed.

Swift Package Manager integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. It should work out of the box on latest Xcode projects since Xcode 11 and has had a lot of community support, seeing huge adoption over the recent years. This is our preferred distribution method for Frames iOS and is the easiest one to integrate, keep updated and build around.

If you’ve never used it before, get started with Apple’s step by step guide into adding package dependencies to your app .

.package(url: "https://github.com/checkout/checkout-3ds-sdk-ios", from: "X.Y.Z")

⚙️ Adding Environment Variable for SPM Integration

You may need to add the following environment variable to your Run Scheme if Checkout3DS-Security.framework fails to load:

<EnvironmentVariable
    key="DYLD_INSERT_LIBRARIES"
    value="$(TARGET_BUILD_DIR)/Checkout3DS.framework/Checkout3DS:$(TARGET_BUILD_DIR)/Checkout3DS-Security.framework/Checkout3DS-Security"
    isEnabled="YES">
</EnvironmentVariable>

This environment variable ensures the dynamic libraries are correctly loaded at runtime.

How to add this environment variable:

• Open your Xcode project.
• Go to Edit Scheme for your target.
• Select the Run action.
• Under Environment Variables, add a new entry:
  • Key: DYLD_INSERT_LIBRARIES
  • Value: $(TARGET_BUILD_DIR)/Checkout3DS.framework/Checkout3DS:$(TARGET_BUILD_DIR)/Checkout3DS-Security.framework/Checkout3DS-Security
  • Ensure the checkbox is enabled.

Then, configure your app to:

Integration

Checkout.com’s 3DS server

This integration method involves one call to our authenticate method, which will perform an entire Authentication flow using Checkout.com’s 3DS servers.

1. Initialize the SDK with your preferred user interface options using our uiCustomization object.
2. Configure the parameters for an authentication.
3. Request authentication and handle the result to continue your payment flow.
4. The authenticate function now returns Result type with two cases
   • AuthenticationResult with transactionStatus and sdkTransactionID 👉  More info about transaction status
   • AuthenticationError with a message.

👉  Strongly recommend providing the appURL parameter as a universal link. Apple Documentation

Code snippet

// 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: "https://www.MerchantRequestorAppUniversalLink.com")
)

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

checkout3DS.authenticate(authenticationParameters: authenticationParameters) { result in
    switch authenticationResult {
    case .success(let authenticationResult):
        // handle authentication result. Checkout Payment Authorisation section.
    case .failure(let error):
        // handle failure scenarios
     }
}

👉  See the Integration Guide with Code Examples for full details.

📚  Read the reference documentation

Payment Authorisation

After initiating the authentication process and obtaining the AuthenticationResult object, you can continue the authentication flow based on the value of transStatus:

transStatus	Description	Proceed with Payment Authorisation Request
Y	Authentication verification successful.	Yes
A	Attempt at processing performed.	Yes
I	Informational only.	Yes
N	Not authenticated or account not verified.	No
R	Authentication or account verification rejected.	No
U	Authentication or account verification could not be performed.	No

👉  More info about transaction status

Dependencies

Our iOS SDK depends on some external libraries:

• To help maintain security, we use JOSESwift. To overcome the limitation in Swift Package Manager (SPM) related to binary target dependencies, we’ve integrated JOSESwift as an xcframework sourced from the same JOSESwift.
• To help provide support and monitor the performance of the SDK, we use our own Checkout Event Logger Kit.

Help and Feedback

For help using the 3D Secure SDK, or to pass on your feedback, you can email our team at support@checkout.com.

If you’ve found a bug, we encourage you to open an issue through GitHub. If your problem isn’t already listed, please detail the versions of the SDK and your development environment that you’re using, what you were hoping to accomplish, and what the actual result you observed was.

If you have an idea for a new feature, we’d also love to hear about it through GitHub. Please open an issue, detailing your idea and why it’s important for your project.

License

This software is released under license. See LICENSE for details.