{"id":27151378,"url":"https://github.com/checkout/checkoutcardmanagement-ios","last_synced_at":"2025-04-08T14:39:55.061Z","repository":{"id":70604328,"uuid":"562872832","full_name":"checkout/CheckoutCardManagement-iOS","owner":"checkout","description":"iOS SDK for Checkout Issuing solution","archived":false,"fork":false,"pushed_at":"2025-03-19T09:13:39.000Z","size":6289,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-19T10:24:58.171Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":false,"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":null,"security":null,"support":"SupportFrameworks/CheckoutCardNetwork.xcframework/Info.plist","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-07T12:44:43.000Z","updated_at":"2025-03-19T09:12:25.000Z","dependencies_parsed_at":"2024-02-13T16:43:02.090Z","dependency_job_id":"8f6b72e4-6f6a-44a2-8151-15d92539ad7a","html_url":"https://github.com/checkout/CheckoutCardManagement-iOS","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-iOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-iOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-iOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/checkout%2FCheckoutCardManagement-iOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/checkout","download_url":"https://codeload.github.com/checkout/CheckoutCardManagement-iOS/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247863696,"owners_count":21008953,"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:54.498Z","updated_at":"2025-04-08T14:39:55.050Z","avatar_url":"https://github.com/checkout.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Table of Contents\n- [What is the CheckoutCardManagement-iOS SDK?](#What-is-the-CheckoutCardManagement-iOS-SDK)\n- [Environments](#Environments)\n  - [Migrating from Stub to Sandbox and Production](#Migrating_from_Stub_to_Sandbox_and_Production)\n- [Sample Application](#Sample-application)\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- [Out of Band (OOB) Authentication](#checkout-out-of-band-oob-authentication-sdk)\n- [Contact](#Contact)\n***\n\n\n# What is the CheckoutCardManagement-iOS SDK?\n\nOur CheckoutCardManagement-iOS 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# Environments\n\nThe iOS SDK supports 3 environments: Stub, Sandbox, and Production.\n\nThese environments are accessed through the 2 libraries available to you when you import the SDK with Swift Package Manager (SPM):\n- **CheckoutCardManagerStub**, which powers the Stub environment. Stub allows you to begin testing the APIs in your app, without having to wait for the legal and contractual arrangements required by the other environments, or for backend integration to be completed. The Stub environment is completely isolated; you can provide empty strings instead of tokens in your API calls as no network calls leave the device, and we provide mock data in the responses.\n- **CheckoutCardManager**, which powers the Sandbox and Production environments. Use 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## Migrating from Stub to Sandbox and Production\n\nWhen you're ready to migrate from the Stub environment, simply update the import statement from `import CheckoutCardManagerStub` to `import CheckoutCardManager`. No additional changes are required, and the public interfaces remain the same.\n\nIn the Live version of your app, you'll be expected to provide valid tokens in your requests, which our backend services will serve securely.\n\n***\n# Sample Application\n\nRefer to [our sample application](https://github.com/checkout/CheckoutCardManagement-iOS/tree/main/Sample%20Application) for a guidance of integration.\n\n***\n# Features\n\n### Easy to integrate\nYour app can consume the SDK directly through SPM; there is no additional setup required, meaning you can get up and running quickly.\n\nFor detailed steps on how to add a package, see Apple's [Add a package dependency](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#Add-a-package-dependency) documentation. Use our SDKs URL `https://github.com/checkout/CheckoutCardManagement-iOS` and ensure you use the latest release.\n\n### Decoupled integration\nYou can use the [Stub environment](#Environments) to begin work on UI development separately, without having to wait for network and other integrations to be completed.\n\n### Developer friendly\nWe value the Swift community and are big fans of following community-defined best practices. As such, our APIs are designed with the [Swift API design guidelines](https://www.swift.org/documentation/api-design-guidelines/) in mind, so usage will feel familiar.\n\nWhilst we are light on UI, we've provided you with flexible UI customization options so that you can adhere to Apple's [Human Interface guidelines](https://developer.apple.com/design/human-interface-guidelines/guidelines/overview/).\n\n### Feature-rich\nOur SDK aims to integrate with all of our backend services for SDK-relevant features.\n\nWhether you're retrieving a list of cards for a cardholder, accessing sensitive card information, or adding a card to the Apple wallet, our SDK makes it easy for you to provide this functionality to your users.\n\n### Compliant\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# Requirements\nThe SDK is distributed as a native iOS package. 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# Integration\n\n### Import SDK\nUse SPM to import the SDK into your app:\n\n1. In **Xcode**, select _File \u003e Swift Packages \u003e Add Package Dependency_.\n2. When prompted, enter `enter https://github.com/checkout/CheckoutCardManagement-iOS`.\n\nSee Apple's [Add a package dependency](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#Add-a-package-dependency) documentation for more information.\n\nAt this stage, you can choose to add the `CheckoutCardManagement` or `CheckoutCardManagementStub` library to your application target. If you're unsure about which library you should use, see our [Environments](#Environments) section.\n\n### Prepare card manager\nTo start consuming SDK functionality, instantiate the main object, which enables access to the functionality:\n```Swift\n// The statement should match the library imported in the previous step\nimport CheckoutCardManagement\n\nclass YourObject {\n   // Customizable UI properties for the secure components delivered by the SDK\n   let cardManagerDesignSystem = CardManagementDesignSystem(font: .systemFont(ofSize: 22),\n                                                            textColor: .blue)\n   // The core object through which the SDK's functionality is accessed \n   let cardManager = CheckoutCardManager(designSystem: cardManagerDesignSystem,\n                                         environment: .sandbox)\n}\n```\n\n### Login user\nIn order to provide your users with the SDK functionality, you must authenticate them for the session.\n\nIn a Live environment, **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\nIn a Stub environment, you can provide any `String`.\n```Swift\nlet token = \"{Token_retrieved_from_your_backend}\"\ncardManager.logIn(with: token)\n```\n\n### Get a list of cards\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- **last 4 digits of the long 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```Swift\ncardManager.getCards { result in\n    switch result {\n    case .success(let cards):\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    case .failure(let error):\n        // If something goes wrong, you'll receive an error with more details\n    }\n}\n```\n\n### Update card state\nThe API is attached to the card object, so you must first obtain it from the SDK.\n\nOnce you have the card object, we would also suggest using our `.possibleStateChanges` card API for an improved user experience. You can then request the new state from the card object.\n```Swift\n// This will return a list of possible states that the card can be transitioned to\nlet possibleNewStates = card.possibleStateChanges\n\n// We can activate the card, if the state was returned by possibleStateChanges\nif possibleNewStates.contains(.active) {\n    card.activate(completionHandler: cardStateChangeCompletion)\n}\n\n// We can suspend the card, if the state was returned by possibleStateChanges\nif possibleNewStates.contains(.suspended) {\n    // You can choose to pass an optional reason for why you're suspending the card\n    let reason: CardSuspendReason? = .lost\n    card.suspend(reason: reason, completionHandler: cardStateChangeCompletion)\n}\n\n// We can revoke the card, if the state was returned by possibleStateChanges\nif possibleNewStates.contains(.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    let reason: CardRevokeReason? = .lost\n    card.revoke(reason: reason, completionHandler: cardStateChangeCompletion)\n}\n```\n\nRegardless of the new state requested, the same completion handler can be used:\n```Swift\nfunc cardStateChangeCompletion(_ result: CheckoutCardManager.OperationResult) {\n    switch result {\n    case .success:\n        // Card state has been updated successfully, and will be reflected by both the backend and the SDK\n    case .failure(let error):\n        // If something goes wrong, you'll receive an error with more details\n    }\n}\n```\n\nNote: card states. There are 4 different card states, which apply to both virtual and physical cards. They are:\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\u003csub\u003e The following example covers PIN, but similar APIs are available for PAN, CVV, and PAN + CVV. The general flow remains the same.\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\nIn a Stub environment, you can provide any `String`.\n\n```Swift\nlet singleUseToken = \"{Single_use_token_retrieved_from_your_backend_after_SCA}\"\n\n// Request sensitive data via the card object\ncard.getPin(singleUseToken: singleUseToken) { result in\n    switch result {\n    case .success(let pinView):\n        // If successful, you'll receive a UI component that you can display to the user\n    case .failure(let error):\n        // If something goes wrong, you'll receive an error with more details\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**Push Provisioning** is the operation of adding a physical or virtual card to a digital wallet. On iOS, this means adding a card to an Apple Wallet.\n\nEnabling this operation is highly complex as it requires interaction between multiple entities including you, Checkout.com, Apple, and the card scheme (in our case, Mastercard).  As such, push provisioning is subject to onboarding and can only be tested in your Production environment. For more details, speak to your operations contact.\n\nA typical call may look as follows:\n```Swift\ncard.provision(cardholderID: \"{id_of_cardholder_performing_operation}\",\n               configuration: ProvisioningConfiguration(/* */),\n               provisioningToken: \"{specific_token_generated_for_operation}\")\n```\n\nThere are some behaviors to be aware of when you attempt a push provisioning operation:\n- if you're using the `CheckoutCardManagement` library, calling it without completing proper onboarding will result in an intentional crash.\n- if you're using the `CheckoutCardManagementStub` library, the operation will behave as expected, but no interaction with Apple Wallet, Checkout.com, or the card scheme will occur. Depending on which Checkout.com environment you're using with Stub, you will receive one of two results:\n  - in the sandbox Checkout.com environment, you'll receive a `pushProvisioningFailure` error, as push provisioning is only valid in production\n  - in the production Checkout.com environment, you'll receive an `OperationResult` success message\n\n***\n# Checkout Out of Band (OOB) Authentication SDK\nPlease find documentation [here](https://github.com/checkout/CheckoutCardManagement-iOS/blob/main/.github/partial-readmes/OOB-SDK-README.md).\n\n***\n# Contact\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-ios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheckout%2Fcheckoutcardmanagement-ios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheckout%2Fcheckoutcardmanagement-ios/lists"}