# Card Management iOS SDK

`Version 4.1.0`

For [Issuing](https://www.checkout.com/docs/card-issuing.md), you can integrate the `CheckoutCardManagement` iOS SDK in your mobile app for the following use cases:

- Activate, suspend, and revoke cards.
- Display sensitive card details to your cardholders.
- Enable cardholders to add cards to their digital wallet, without entering the card details, in your app or the Apple Wallet app

> **Note**
>
> You must migrate to SDK version 4.0.0. For guidance on how to update your integration, see Support – [Issuing Card Management SDKs migration guide](https://support.checkout.com/hc/en-us/articles/32194131879698).

> **Information**
>
> To authenticate cardholders for digital transactions in your app, see the [Out-of-Band Authentication iOS SDK](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/out-of-band-authentication-ios-sdk.md).

---

## Before you start

- Make sure you have a [test account](https://www.checkout.com/get-test-account) with Checkout.com.
- You must have started [Issuing onboarding](https://www.checkout.com/docs/card-issuing/set-up-card-program.md) and received your client credentials.

> **Note**
>
> The SDK does not support the following frameworks:
> - Cordova
> - Flutter
> - .NET MAUI / Xamarin
> - React Native

---

## How it works

1. Import the SDK.
2. Set the SDK environment.
3. Instantiate the CardManagement SDK.
4. Set up Strong Customer Authentication (SCA).

To implement the required use cases, see [Next steps](#Next_steps).

### SDK environments

The SDK supports three environments:

- Stub (isolated testing)
- Sandbox (test)
- Production (live)

The stub environment enables you to start testing the APIs in your app, without the legal and contractual approvals required for the other environments.
This environment is completely isolated, so no network calls leave the device. In API calls that require a `token`, you can provide any `String` because all responses return mock data.

To authenticate in the sandbox and production environments, use the client credentials you receive as part of your Issuing onboarding.
You must provide valid `tokens` in your requests, which our back-end services serve securely.

API calls and public interfaces are the same across all environments.

---

## Import the SDK

The SDK is distributed as a native iOS package.
You can access the different [SDK environments](#SDK_environments) through the following libraries:

- `CheckoutCardManager` – Powers the sandbox and production environments
- `CheckoutCardManagerStub` – Powers the stub environment

Your app does not call these libraries directly. They are dynamically linked by the SDK.

Use Swift Package Manager (SPM) to import the SDK into your app.

1. Open your project in Xcode.
2. Go to _File_ > _Add package dependency_.
3. When prompted, enter the SDK's GitHub URL: `https://github.com/checkout/CheckoutCardManagement-iOS`.
4. Select your project as the target for either the `CheckoutCardManager` or the `CheckoutCardManagerStub` package product.
5. Select _Add package_.

Add your selected package to your import statements:

**CheckoutCardManager**

```swift
import CheckoutCardManagement

```

**CheckoutCardManagerStub**

```swift
import CheckoutCardManagementStub

```

**Both**

```swift
#if canImport(CheckoutCardManagement)
import CheckoutCardManagement
#elseif canImport(CheckoutCardManagementStub)
import CheckoutCardManagementStub
#endif

```

### Add dependencies

If you want to implement the [add cards to Apple Wallet use case](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md#Before_you_begin), add the [CheckoutNetwork 1.1.2](https://github.com/checkout/NetworkClient-iOS) package to enable network calls.

> **Information**
>
> For more information, see Apple – [Adding package dependencies to your app](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).

### Add libraries

Checkout.com distributes the following SDK libraries to you:

- `D1`
- `D1Core`
- `TPCSDKSwift`
- `SecureLogAPI`

> **Note**
>
> - The D1 SDK versions must be above `3.2.0`. Checkout.com has tested up to `4.0.0`.
> - All additional libraries must match the same SDK version.
> - For SDK versions, see the release notes on GitHub – [CheckoutCardManagement-iOS](https://github.com/checkout/CheckoutCardManagement-iOS).

Link all these libraries to your app, and then follow these steps to embed and sign them:

1. In your Xcode project, go to _Targets_ > _ApplicationTarget_.
2. Select _General_ > _Frameworks, Libraries, and Embedded Content_.
3. For each library listed under `CheckoutCardManagement`, select _Embed & Sign_.

> **Information**
>
> If you're building a hybrid app, see your platform's documentation on how to consume native third-party SDKs.

---

## Instantiate the CardManagement SDK

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

- `font`
- `textColor`

The `CheckoutCardManager` object enables access to the SDK's functionality and sets the SDK environment to `.sandbox` or `.production`.

Instantiate both objects as follows:

```swift
// The import statement must match the library you added, for example:
// CheckoutCardManager > import CheckoutCardManagement, or CheckoutCardManagerStub > import CheckoutCardManagementStub
import CheckoutCardManagement

class YourObject {
   // The CardManagementDesignSystem object defines the appearance of the UI components displayed to the user.
   let cardManagerDesignSystem = CardManagementDesignSystem(font: .systemFont(ofSize: 22), textColor: .blue)
   // Instantiates the core cardManager object, which provides access to the SDK functionality
   let cardManager = CheckoutCardManager(designSystem: cardManagerDesignSystem, environment: .sandbox)
}
```

> **Information**
>
> If you have integration questions or issues, contact your issuing representative or [issuing_operations@checkout.com](mailto:issuing_operations@checkout.com).

---

## Set up Strong Customer Authentication

While Checkout.com handles in-depth compliance, you are responsible for performing [Strong Customer Authentication (SCA)](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/sca-compliance.md) on your cardholders for every session where they use functionality provided by the SDK.
This applies to both the sandbox and production environments.

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

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

---

## SDK functions

The SDK provides the following functions:

| Function | Description |
| --- | --- |
| **Cards** |  |
| `card.activateCard(cardId, sessionToken)` | [Activates the card](https://www.checkout.com/docs/card-issuing/activate-a-card.md#Activate_a_card_in_your_app). |
| `card.copyPan(singleUseToken)` | [Copies the card number to the clipboard](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details.md#Copy_the_card_number_to_clipboard). |
| `card.displayPan(forCard, displayConfiguration, singleUseToken)` | [Retrieves the card's full primary account number (PAN)](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details.md#Retrieve_the_sensitive_card_details). |
| `card.displayPanAndSecurityCode(forCard, displayConfiguration, singleUseToken)` | [Retrieves the card's full PAN and security code (CVC2)](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details.md#Retrieve_the_sensitive_card_details). |
| `card.displayPin(forCard, displayConfiguration, singleUseToken)` | [Retrieves the card's personal identification number (PIN)](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details.md#Retrieve_the_sensitive_card_details). |
| `card.displaySecurityCode(forCard, displayConfiguration, singleUseToken)` | [Retrieves the card's CVC2](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details.md#Retrieve_the_sensitive_card_details). |
| `card.getCardDigitizationState(cardId, token)` | [Retrieves the card's digitization status](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md#Verify_digitization_status). |
| `card.provision(provisioningToken, viewController)` | [Provisions the card](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md#Provision_the_card). |
| `card.revokeCard(cardId, reason, sessionToken)` | [Revokes the card](https://www.checkout.com/docs/card-issuing/manage-cards/revoke-a-card.md#Revoke_a_card_in_your_app). |
| `card.suspendCard(cardId, reason, sessionToken)` | [Suspends the card](https://www.checkout.com/docs/card-issuing/manage-cards/suspend-a-card.md#Suspend_a_card_in_your_app). |
| **Card manager** |  |
| `cardManager.configurePushProvisioning(activity, cardholderId, configuration)` | [Configures push provisioning](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md#Configure_push_provisioning). |
| `cardManager.getCards()` | [Retrieves the cardholder's cards](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md#Retrieve_the_cardholder's_cards). |
| `cardManager.getCard(cardId)` | [Retrieves a specific card for a cardholder](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md#Retrieve_the_cardholder's_cards). |
| `cardManager.logInSession(token)` | Signs in to a card management session for the SDK session token provided. |
| `cardManager.logoutSession()` | Signs out of a card management session. |

---

## Next steps

After you've completed the integration, see how to implement the following use cases in your app:

**[Activate a card](https://www.checkout.com/docs/card-issuing/activate-a-card.md)**

Learn how to activate an issued card using the Dashboard, API, and your app, and how cardholders can activate their cards.

**[Display card details](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details-in-your-app.md#Display_card_details_in_your_app)**

Enable your cardholders to see their card details in your app.

**[Add a card to a digital wallet](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md)**

Enable your cardholders to add their cards to their digital wallet in your app or the Apple Wallet app.

**[Mobile SDKs lifecycle policy](https://www.checkout.com/docs/developer-resources/sdks/mobile-sdks-lifecycle-policy.md)**

Learn how we version, support, and deprecate our mobile SDKs, and how long you have to adopt each new release.