Card issuing iOS SDK

Last updated: July 5, 2023

Our CheckoutCardManagement-iOS SDK is the mobile gateway to our card issuing solution. The SDK enables your mobile application to:

securely access and display sensitive card details to your cardholders
activate, suspend, or revoke a card
add a card to an Apple Pay wallet

Information

You can use the Out-of-Band Authentication iOS SDK to authenticate cardholders for digital transactions from within your app.

The SDK supports three environments:

sandbox
production
stub

To use the sandbox and production environments, you must have begun onboarding for card issuing with Checkout.com. During your onboarding you'll receive client credentials, which you'll need to handle on your back end for authentication to access the environments.

The stub environment allows you to begin testing the APIs in your app, without having to wait for the legal and contractual approvals required by the other environments.

Additionally, as the stub environment is completely isolated, no network calls leave the device. In API calls that require a token, you can supply any String object instead as all responses return mock data.

When you import the SDK, you can access the environments through the two available libraries:

CheckoutCardManager, which powers the sandbox and production environments
CheckoutCardManagerStub, which powers the stub environment

The SDK is distributed as a native iOS package, meaning you can use Swift Package Manager (SPM) to import the SDK into your app:

Open your project in Xcode.
Navigate to File > Swift Packages > Add Package Dependency.
When prompted, enter https://github.com/checkout/CheckoutCardManagement-iOS.
Select the CheckoutCardManager or CheckoutCardManagerStub environment.
If you selected CheckoutCardManager library, add import CheckoutCardManagement to your import statements. If you selected CheckoutCardManagerStub, add import CheckoutCardManagementStub instead.

Information

For more information, refer to Apple's documentation on adding package dependencies to your app. If you're building a hybrid app, refer to your platform's documentation on how to consume native third-party SDKs.

When you are ready to migrate from the stub environment to sandbox or production, you can:

Add the CheckoutCardManagerStub library as an application target in your project.
Update the import statement in your app from import CheckoutCardManagementStub to import CheckoutCardManagement.

In the sandbox and production environments, you will need to provide valid tokens in your requests, which our back-end services will serve securely.

API calls and public interfaces do not need to be updated, as these remain the same across all environments.

Note

When you migrate from the stub environment, you are expected to manage Strong Custom Authentication (SCA) requirements as part of the agreement to access the SDK's functionality.

The CardManagementDesignSystem object defines the look of the UI components displayed to the user. You can set the following properties:

font
textColor
formatSeparator, to set the text separator when formatting the card number


1// The import statement should match the library you added, for example:
2// CheckoutCardManager > import CheckoutCardManagement, or CheckoutCardManagerStub > import CheckoutCardManagementStub
3import CheckoutCardManagement
4
5class YourObject {
6
7   // Sets the customizable UI properties for the secure components delivered
8   let cardManagerDesignSystem = CardManagementDesignSystem(font: .systemFont(ofSize: 22),
9                                                            textColor: .blue)
10}

To access the SDK's functionality, instantiate the CheckoutCardManager object within the same object you instantiated CardManagementDesignSystem in:


1// The import statement should match the library you added, for example:
2// CheckoutCardManager > import CheckoutCardManagement, or CheckoutCardManagerStub > import CheckoutCardManagementStub
3import CheckoutCardManagement
4
5class YourObject {
6
7   // Sets the customizable UI properties for the secure components delivered
8   let cardManagerDesignSystem = CardManagementDesignSystem(font: .systemFont(ofSize: 22),
9                                                            textColor: .blue)
10
11   // Instantiates the core card manager object, which provides access to the SDK functionality
12   let cardManager = CheckoutCardManager(designSystem: cardManagerDesignSystem,
13                                         environment: .sandbox)
14}

While Checkout.com handles in-depth compliance, you are required to perform Strong Customer Authentication (SCA) on your users.

You can generate multiple tokens for different systems during a single authentication session. For example, for sign in, to get an SDK session token, or to get an internal authentication token.

However, you can only generate a single SDK session token for each SCA flow requested.

Card issuing iOS SDK

Information

SDK environments

Import the SDK

Information

Migrate from the stub environment

Note

Instantiate the design system

Instantiate the card manager

Authentication requirements

Next steps

Activate, suspend, or revoke a card

Display card details in your app

Add a card to a digital wallet