# Out-of-Band Authentication iOS SDK `Version 4.1.0` For [Issuing](https://www.checkout.com/docs/card-issuing.md), you can integrate the `CheckoutOOBManager` iOS SDK in your mobile app to perform out-of-band (OOB) 3D Secure (3DS) cardholder authentication for digital transactions. OOB authentication is a type of two-factor authentication (2FA). --- ## 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. - You need to build the UI for the transaction authentication and device registration screens. This enables you to fully customize the experience. Therefore, the SDK does not provide many UI components. > **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 up webhooks. 3. Handle errors. To authenticate cardholders for transactions, see [Next steps](#Next_steps). ### SDK environments The SDK supports two environments: - Sandbox (test) - Production (live) To authenticate in these environments, use the client credentials you receive as part of your Issuing onboarding. --- ## Import the SDK The SDK is distributed as a native iOS package. 1. Use Swift Package Manager (SPM) to import the SDK into your app: 1. Open your project in Xcode. 2. Go to _Project_ > _Add package dependency_. 3. When prompted, enter the SDK's GitHub URL: `https://github.com/checkout/CheckoutCardManagement-iOS`. 4. Select _Up to next major version_. 5. Select _Add package_. 6. To use the OOB SDK as a standalone package, select your main target to include `CheckoutOOBSDK`. 7. Select _Add package_. 2. Add `CheckoutNetwork` as a dependency in your project. See the `NetworkClient-ios` [repository](https://github.com/checkout/NetworkClient-iOS.git) on GitHub for more information. > **Information** > > - For more information, see Apple – [Adding package dependencies to your app](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app). > - If you're building a hybrid app, see your platform's documentation on how to consume native third-party SDKs. 3. Initialize the primary `CheckoutOOB` object and set the SDK environment: ```swift import CheckoutOOBSDK // Initialize the SDK and set the environment let checkoutOOB = CheckoutOOB(environment: .sandbox) ``` --- ## Subscribe to webhooks If you're developing the back end for your app's OOB functionality, you must listen to webhooks sent from Checkout.com's Issuing back end to get transaction details. If you're only developing the mobile part of the OOB functionality, you can disregard this section. We recommend using the following flow when you request authentication from the cardholder: 1. Implement a push notification to your app. 2. Use the data from the webhook to display to the cardholder the details of the transaction you're asking them to authenticate. You must provide to Checkout.com an endpoint that: - Can receive HTTP POST requests - Returns a 200 OK response to acknowledge receiving all webhooks > **Note** > > The transaction fails if your endpoint does not acknowledge receiving a webhook. To confirm that Checkout.com sent the webhooks, we include an Authorization header in the request containing the value you provided us during your onboarding. ### Transaction details webhook You receive a webhook containing the following JSON payload with the details of the transaction for authentication: ```json { "acsTransactionId": "bea260bb-c183-4d74-8bc9-421fe3aa2658", "cardId": "crd_abcdef1ghijklmn23opq45r6st", "applicationId": "ios-4283-23344-7884ea-474752", "transactionDetails": { "maskedCardNumber": "**** **** **** 1234", "purchaseDate": "2024-12-24T17:32:28.000Z", "merchantName": "ACME Corporation", "purchaseAmount": 1, "purchaseCurrency": "GBP" }, "threeDSRequestorAppURL": "https://requestor.netcetera.com?transID=bea260bb-c183-4d74-8bc9-421fe3aa2658" } ``` ### Webhook fields | Field name | Description | | --- | --- | | `acsTransactionId`
`string` | The acquirer's unique identifier for the transaction you want the cardholder to authenticate. | | `cardId`
`string` | The unique identifier for the card, prefixed with `crd_`. | | `applicationId`
`string` | The app you want to send the push notification to. | | `transactionDetails`
`object` | Information about the transaction you want the cardholder to authenticate. | | `transactionDetails.`
`maskedCardNumber`
`string` | The masked card primary account number (PAN). | | `transactionDetails.`
`purchaseDate`
`date-time` | The date and time when the cardholder made the purchase, in UTC.
Format – ISO 8601
Example – `2025-01-31T10:20:30.456` | | `transactionDetails.`
`merchantName`
`string` | The merchant the cardholder made the purchase with. | | `transactionDetails.`
`purchaseAmount`
`double` | The amount of the purchase, in the [major currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value.md). | | `transactionDetails.`
`purchaseCurrency`
`string` | The currency in which the purchase was made.
Standard – [ISO 4217 code](https://www.checkout.com/docs/developer-resources/testing/codes/currency-codes.md)
Example – `GBP` | | `threeDSRequestorAppURL`
`string` | The URL to the 3DS requestor app. | ### Cancellation webhook If the transaction is canceled (for example, due to a timeout), you receive a webhook containing the following JSON payload: ```json { "transactionId": "bea260bb-c183-4d74-8bc9-421fe3aa2658" } ``` > **Information** > > - If you have integration questions or issues, contact your issuing representative or [issuing_operations@checkout.com](mailto:issuing_operations@checkout.com). > - For SDK release notes, see GitHub – [oob-authentication-android](https://github.com/checkout/oob-authentication-android). --- ## 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 | | --- | --- | | `checkoutOOBManager.registerDevice(deviceRegistration)` | [Registers the cardholder's device and app for OOB](https://www.checkout.com/docs/card-issuing/manage-issuing-transactions/authenticate-cardholders-for-transactions.md#Register_the_device). | | `checkoutOOBManager.authenticatePayment(paymentAuthentication)` | [Authenticates the transaction](https://www.checkout.com/docs/card-issuing/manage-issuing-transactions/authenticate-cardholders-for-transactions.md#Authenticate_the_transaction). | --- ## Next steps After you've completed the integration, see how to authenticate cardholders in your app: **[Authenticate cardholders for transactions](https://www.checkout.com/docs/card-issuing/manage-issuing-transactions/authenticate-cardholders-for-transactions.md)** Perform out-of-band (OOB) 3D Secure cardholder authentication for digital transactions 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.