# Card Management Android SDK

`Version 3.1.0`

For [Issuing](https://www.checkout.com/docs/card-issuing.md), you can integrate the `CheckoutCardManagement` Android 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.

> **Note**
>
> You must migrate to SDK version 3.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 Android SDK](https://www.checkout.com/docs/developer-resources/sdks/card-issuing-sdks/out-of-band-authentication-android-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).

---

## Import the SDK

The SDK is distributed as a native Android dependency, which your app can consume through Maven Central.

Use Gradle to import the SDK into your app. In your project-level `build.gradle` file, add:

```gradle
repositories {
    mavenCentral()
}
```

### Add dependencies

In your app-level `build.gradle` file, add:

```gradle
dependencies {
    // Required to initialize the CardManagementDesignSystem
    implementation 'androidx.compose.ui:ui:$compose_ui_version'
    implementation 'com.checkout:checkout-sdk-card-management-android:$checkout_card_management_version'
}
```

### Add libraries

Checkout.com distributes the following SDK libraries to you as Android archive files (AARs):

- `checkout-sdk-card-network-android.aar` – Provides the SDK's sensible internals
- `d1-release.aar` – Provides push onboarding capability

If you intend to use the SDK to [add cards to digital wallets](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md), you must add `d1-release.aar`.

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

> **Note**
>
> - The D1 SDK version must be above `4.1.0`.
> - All additional libraries must match the same SDK version.
> - For SDK versions, see the release notes on GitHub – [CheckoutCardManagement-Android](https://github.com/checkout/CheckoutCardManagement-Android).

1. In the project `build.gradle` file, import the .aar files into the app's repository:

```gradle
repositories {
  flatDir {
    dirs 'path/to/the/aars/rootDir'
  }
}
```

2. In the app-level `build.gradle` file, add the .aar files dependency and the following transitive dependencies:

```gradle
dependencies {
    // Include the sdk
    implementation fileTree(dir: 'path/to/the/aars/appDir', include: ['d1-release.aar', checkout-sdk-card-network-android.aar])
    
    // Transitive dependencies for d1-release
    implementation 'com.google.android.gms:play-services-gcm:17.0.0'
    implementation 'androidx.annotation:annotation:1.6.0'
    implementation 'com.google.android.gms:play-services-base:18.2.0'
    implementation 'net.java.dev.jna:jna:5.17.0@aar'
    implementation 'androidx.appcompat:appcompat:[1.0.0,1.3.1]'
    
    // Transitive dependencies for checkout-sdk-card-network-android
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    implementation 'com.squareup.okhttp3:okhttp:5.0.0-alpha.2'
    implementation 'com.squareup.okhttp3:logging-interceptor:5.0.0-alpha.2'
    implementation 'com.google.dagger:dagger:2.46.1'
    implementation 'androidx.compose.ui:ui:1.4.3'
    implementation 'androidx.compose.material:material:1.4.3'
    implementation 'androidx.work:work-runtime-ktx:2.10.3'
    implementation 'com.checkout:checkout-sdk-event-logger-android:2.0.2'
    kapt 'com.google.dagger:dagger-compiler:2.46.1'
}
```

> **Information**
>
> - For more information on adding .aar libraries to your project, see Android Developers – [Add your AAR or JAR as a dependency](https://developer.android.com/studio/projects/android-library#psd-add-aar-jar-dependency).
> - If you're building a hybrid app, see your platform's documentation on how to consume native third-party SDKs.

---

## Set the SDK environment

The SDK supports two environments, which are both powered by the `CheckoutCardManager` library:

- Sandbox (test)
- Production (live)

To authenticate in these 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.

To set the SDK environment, provide the `CardManagerEnvironment` environment as follows:

**Sandbox**

```kotlin
let cardManager = CheckoutCardManager(designSystem: designSystem, environment: .sandbox)
```

**Production**

```kotlin
let cardManager = CheckoutCardManager(designSystem: designSystem, environment: .production)
```

---

## Instantiate the CardManagement SDK

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

- Text style, using the properties exposed by the [`compose.ui.text.TextStyle`](https://developer.android.com/reference/kotlin/androidx/compose/ui/text/TextStyle) class
- Format separator, to set the text separator when formatting the card number

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

Instantiate both objects as follows:

```kotlin
// Customizable properties for the appearance of the secure UI components delivered by the SDK
private val cardManagerDesignSystem = CardManagementDesignSystem(
  textStyle = TextStyle(), //	Text style, using the properties exposed by the compose.ui.text.TextStyle class
  panTextSeparator = "-" // Format separator, as a String, to set the text separator when formatting the card number
)

// Access to the SDK functionality
private val cardManager = CheckoutCardManager(
  context = context,
  designSystem = cardManagerDesignSystem,
  environment = Environment.SANDBOX // Sets the SDK environment to either SANDBOX or PRODUCTION from com.checkout.cardmanagement.model.Environment
)
```

> **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.activate()` | [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.getDigitizationState(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.getPan(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.getPANAndSecurityCode(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.getPin(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.getSecurityCode(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.provision(activity, token)` | [Provisions the card](https://www.checkout.com/docs/card-issuing/manage-cards/add-a-card-to-a-digital-wallet.md#Provision_the_card). |
| `card.revoke()` | [Revokes the card](https://www.checkout.com/docs/card-issuing/manage-cards/revoke-a-card.md#Revoke_a_card_in_your_app). |
| `card.suspend()` | [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.

**[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.