{"id":27151379,"url":"https://github.com/checkout/checkoutcardmanagement-android","last_synced_at":"2025-04-08T14:39:58.775Z","repository":{"id":177257601,"uuid":"656781271","full_name":"checkout/CheckoutCardManagement-Android","owner":"checkout","description":"Android SDK for Checkout Issuing solution","archived":false,"fork":false,"pushed_at":"2025-03-31T12:03:48.000Z","size":114,"stargazers_count":3,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-31T12:36:25.610Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/checkout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-21T16:13:38.000Z","updated_at":"2025-03-31T11:58:39.000Z","dependencies_parsed_at":"2025-01-31T16:32:57.016Z","dependency_job_id":"5d1d6892-4998-4465-9aad-e0041fd520c7","html_url":"https://github.com/checkout/CheckoutCardManagement-Android","commit_stats":null,"previous_names":["checkout/checkoutcardmanagement-android"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-Android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-Android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-Android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-Android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/checkout","download_url":"https://codeload.github.com/checkout/CheckoutCardManagement-Android/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247863709,"owners_count":21008954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-08T14:39:58.223Z","updated_at":"2025-04-08T14:39:58.746Z","avatar_url":"https://github.com/checkout.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CheckoutCardManagement-Android SDK\n\n# Table of Contents\n- [What is the CheckoutCardManagement-Android SDK?](#What-is-the-CheckoutCardManagement-Android-SDK?)\n- [Environments](#Environments)\n- [Features](#Features)\n- [Requirements](#Requirements)\n- [Integration](#Integration)\n  - [Import SDK](#Import-SDK)\n  - [Prepare Card Manager](#Prepare-Card-Manager)\n  - [Login user](#Login-user)\n  - [Get a list of cards](#Get-a-list-of-cards)\n  - [Update card state](#Update-card-state)\n  - [Retrieve Secure Data](#Retrieve-secure-data)\n  - [Push Provisioning](#Push-provisioning)\n- [Contact](#Contact)\n***\n\n# What is the CheckoutCardManagement Android SDK?\n\nOur CheckoutCardManagement-Android SDK is the mobile gateway to our wider [card issuing solution](https://www.checkout.com/docs/card-issuing). It enables your mobile application to securely access important card information and functionality, in a fast and safe way.\n\n***\n\n# Environments\n\nThe Android SDK supports 2 environments: Sandbox and Production, both powered by the **CheckoutCardManager** library.\n\nUse of these environments requires onboarding with our operations team. During onboarding, you'll receive client credentials, which you will then need to handle on your backend for authentication. You will be expected to manage [Strong Custom Authentication (SCA) requirements](https://www.checkout.com/docs/payments/regulation-support/sca-compliance-guide) as part of accessing the SDK's functionality.\n\n***\n\n# Features\n\n### Easy to integrate\n\nYour app can consume the SDK directly through Maven Central; there is no additional setup required, meaning you can get up and running quickly.\n\n### Developer friendly\n\nWe value the Android community and are big fans of following best practices and making use of cutting-edge technology. As such, our APIs utilise [Jetpack Compose](https://developer.android.com/jetpack/compose), [Kotlin Coroutine](https://kotlinlang.org/docs/coroutines-overview.html), and follow the [Kotlin Coding Convention](https://kotlinlang.org/docs/coding-conventions.html), so usage will feel familiar.\n\n### Feature-rich\n\nWhether you're retrieving a list of cards for a cardholder, accessing sensitive card information, or adding a card to the Google Wallet, our SDK makes it easy for you to provide this functionality to your users.\n\n### Compliant\n\nUsing the SDK keeps you compliant with the [Payment Card Industry Data Security Standards (PCI DSS)](https://www.checkout.com/docs/payments/regulation-support/pci-compliance).\n\nIf you have any specific questions about PCI compliance, reach out to your operations contact.\n\n***\n\n# Requirements\n\nThe SDK is distributed as a native Android dependency. If you have a hybrid project, review your hybrid platform's documentation for guidance on how to consume native third-party SDKs.\n\nYou should have **SCA** enabled for your users. Whilst we take care of in-depth compliance, you are required to perform SCA on your users as requested and documented.\n\nEach authentication session can be used to simultaneously generate multiple tokens for different systems. For example, for sign in, or to get an SDK session token or an internal authentication token. However, only one SDK token can be generated from each SCA flow requested.\n\n***\n\n# Integration\n\n## Import SDK\n\nUse Gradle to import the SDK into your app.\n\nIn your project-level `build.gradle` file, add:\n\n```gradle\nrepositories {\n    mavenCentral()\n}\n```\n\nIn your app-level `build.gradle` file, add:\n\n```gradle\ndependencies {\n    // Required to initialise the CardManagementDesignSystem\n    implementation \"androidx.compose.ui:ui:$compose_ui_version\"\n    implementation 'com.checkout:checkout-sdk-card-management-android:$checkout_card_management_version'\n}\n```\n\n## Prepare Card Manager\n\nTo start consuming SDK functionality, instantiate the main object, which enables access to the\nfunctionality:\n\n```Kotlin\nimport androidx.compose.ui.text.TextStyle\nimport com.checkout.cardmanagement.CheckoutCardManager\nimport com.checkout.cardmanagement.model.Environment\n\nclass YourObject {\n  // Customisable properties for the secure UI components delivered by the SDK\n  private val cardManagerDesignSystem = CardManagementDesignSystem(\n    textStyle = TextStyle(),\n    panTextSeparator = \"-\"\n  )\n\n  // The object through which the SDK functionality is accessed \n  private val cardManager = CheckoutCardManager(\n    context = context,\n    designSystem = cardManagerDesignSystem,\n    environment = Environment.SANDBOX\n  )\n}\n```\n\n## Login user\n\nIn order to provide your users with the SDK functionality, you must authenticate them for the session.\n\n**You are responsible for ensuring you authenticate a user** for the session. This means your application should retrieve a session token from your authentication backend.\n\n`logInSession()` returns a boolean value of the token validation result. `CheckoutCardManager` is allowed to operate `getCards` only if the token is valid.\n\n```Kotlin\ncardManager.logInSession(\"{Token_retrieved_from_your_backend}\")\n```\n\n## Get a list of cards\n\nOnce you've authenticated the cardholder and your application, you can return a list of non-sensitive card data using `getCards` for that cardholder.\n\nThis returns the following card details:\n\n- **last 4 digits of the full card number**, also known as the Primary Account Number (PAN)\n- card's **expiry date**\n- **cardholder's** name\n- card's **state** (inactive, active, suspended, or revoked)\n- a **unique ID** for each card returned\n\n```Kotlin\ncardManager.getCards { result: Result\u003cList\u003cCard\u003e\u003e -\u003e\n  result.onSuccess {\n    // You'll receive a list of cards that you can integrate within your UI\n    // The card info includes the last 4 digits (PAN), expiry date, cardholder name, card state, and id\n  }.onFailure {\n    // If something goes wrong, you'll receive an error with more details\n  }\n}\n```\n\n## Update Card State\n\nThe Card State Management API is an extension function of the `Card` class, so you must first obtain it from the SDK.\n\nOnce you have the `Card` object, we would also suggest using the `card.possibleStateChanges` API for an improved user experience. Although it's not a hard requirement, you can request the possible new states from the card object before running the card management operation.\n\n```Kotlin\n// This will return a list of possible states that the card can be transitioned to\nval possibleNewStates = card.possibleStateChanges\n\n// We can activate the card, if the state was returned by possibleStateChanges\nif (possibleNewStates.contains(CardState.ACTIVE)) {\n  card.activate(completionHandler)\n}\n\n// We can suspend the card, if the state was returned by possibleStateChanges\nif (possibleNewStates.contains(CardState.SUSPENDED)) {\n  // You can choose to pass an optional reason for why you're suspending the card \n  val reason: CardSuspendReason? = CardSuspendReason.LOST\n  card.suspend(reason, completionHandler)\n}\n\n// We can revoke the card, if the state was returned by possibleStateChanges\nif (possibleNewStates.contains(CardState.REVOKED)) {\n  // This is a destructive and irreversible action - once revoked, the card cannot be reactivated\n  // We recommended that you request UI confirmation that your user intended to perform this action\n  // You can choose to pass an optional reason for why you're revoking the card\n  val reason: CardRevokeReason? = CardRevokeReason.STOLEN\n  card.revoke(reason, completionHandler)\n}\n```\n\nRegardless of the new state requested, the same completion handler can be used:\n\n```Kotlin\nfun cardStateChangeCompletionHandler(result: Result\u003cUnit\u003e): Unit {\n  result\n    .onSuccess {\n      // Card state has been updated successfully, and will be reflected by both the backend and the SDK\n    }.onFailure {\n      // If something goes wrong, you'll receive an error with more details\n    }\n}\n```\n\nThere are 4 possible card states, which apply to both virtual and physical cards:\n\n| Status    | Description                                                                                                                                                                            |\n|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Inactive  | The card is awaiting activation and is unusable until then. By default, physical cards are set to `inactive` on creation. Cards cannot transition to `inactive` from any other status. |\n| Active    | The card can process transactions as normal. By default, virtual cards are set to `active` on creation.                                                                                |\n| Suspended | Card has been manually suspended by the cardholder; transactions are temporarily blocked. The card can be reactivated to allow for normal use.                                         |\n| Revoked   | Transactions are permanently blocked. The card cannot be reactivated from this status.                                                                                                 |\n\n## Retrieve Secure Data\n\n\u003csub\u003e The following example covers PIN, but similar APIs are available for PAN, CVV, and PAN + CVV. The general flow remains the same. The only different is the API for PAN + CVV it will return a pair of views instead of one.\u003c/sub\u003e\n\nThese calls are subject to a unique SCA flow prior to every individual call. Only on completion of a specific authentication can a single-use token be requested and provided to the SDK, in order to continue executing the request.\n\n```Kotlin\nval singleUseToken = \"{Single_use_token_retrieved_from_your_backend_after_SCA}\"\n\n// Request sensitive data via the card object\ncard.getPin(singleUseToken) { result: Result\u003cAbstractComposeView\u003e -\u003e\n  result\n    .onSuccess {\n      // If successful, you'll receive a Compose view that contains the secure data that you can display to the user\n    }.onFailure {\n      // If something goes wrong, you'll receive an error with more details\n    }\n}\n```\n\nThe UI component protects the value and safely delivers it to the user as the sole recipient. The UI component design can be adjusted as appropriate when [creating the card manager](#Prepare-card-manager) and providing the `CardManagementDesignSystem`.\n\n### Push Provisioning\n\n**Push Provisioning** is the operation of adding a physical or virtual card to a digital wallet. On Android, this means adding a card to the Google Wallet so that card can be used for Google Pay.\n\nEnabling this operation is highly complex as it requires interaction between multiple entities including you, Checkout.com, Google Pay, and the card scheme (in our case, Mastercard). As such, push provisioning is subject to additional onboarding and can only be tested in your Production environment. For more details on onboarding, please speak to your operations contact.\n\nA typical call may look as follows:\n\n```Kotlin\ncard.provision(\n  activity = theActivityHandleTheProvisionOutcome,\n  cardholderID = \"{id_of_cardholder_performing_operation}\",\n  configuration = ProvisioningConfiguration(/* */),\n  token = \"{specific_token_generated_for_operation}\",\n  completionHandler = { result: Result\u003cUnit\u003e -\u003e\n    // Callback after the operation has completed\n  }\n)\n```\n\nWhen you attempt a push provisioning operation without completing proper onboarding will result in an intentional crash.\n\n***\n\n# Contact\n\nFor Checkout.com issuing clients, please email issuing_operations@checkout.com for any questions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheckout%2Fcheckoutcardmanagement-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheckout%2Fcheckoutcardmanagement-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheckout%2Fcheckoutcardmanagement-android/lists"}