Out-of-Band Authentication iOS SDK

Last updated: March 12, 2025

For the Issuing solution, you can integrate the CheckoutOOBManager iOS SDK to perform out-of-band (OOB) 3D Secure (3DS) cardholder authentication for digital transactions in your mobile app. OOB authentication is a type of two-factor authentication (2FA).

Make sure you have a test account with Checkout.com.
You must have started your Issuing onboarding and received 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

Import the SDK.
Set up webhooks.
Handle errors.

To authenticate cardholders for transactions, see Next steps.

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.

The SDK is distributed as a native iOS package.

Use Swift Package Manager (SPM) to import the SDK into your app:
Open your project in Xcode.
Go to Project > Add package dependency.
When prompted, enter the SDK's GitHub URL: https://github.com/checkout/CheckoutCardManagement-iOS.
Select Up to next major version.
Select Add package.
To use the OOB SDK as a standalone package, select your main target to include CheckoutOOBSDK.
Select Add package.
Add CheckoutNetwork as a dependency in your project. See the NetworkClient-ios repository on GitHub for more information.

Information

For more information, see Apple – 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.

Initialize the primary CheckoutOOB object and set the SDK environment:


1import CheckoutOOBSDK
2
3// Initialize the SDK and set the environment
4let checkoutOOB = CheckoutOOB(environment: .sandbox)

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:

Implement a push notification to your app.
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.

You receive a webhook containing the following JSON payload with the details of the transaction for authentication:


1{
2  "acsTransactionId": "bea260bb-c183-4d74-8bc9-421fe3aa2658",
3  "cardId": "crd_abcdef1ghijklmn23opq45r6st",
4  "applicationId": "ios-4283-23344-7884ea-474752",
5  "transactionDetails": {
6    "maskedCardNumber": "**** **** **** 1234",
7    "purchaseDate": "2024-12-24T17:32:28.000Z",
8    "merchantName": "ACME Corporation",
9    "purchaseAmount": 1,
10    "purchaseCurrency": "GBP"
11  },
12  "threeDSRequestorAppURL": "https://requestor.netcetera.com?transID=bea260bb-c183-4d74-8bc9-421fe3aa2658"
13}

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` datetime	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.
`transactionDetails.` `purchaseCurrency` string	The currency of the purchase. Format – ISO 4217 code Example – `GBP`
`threeDSRequestorAppURL` string	The URL to the 3DS requestor app.

If the transaction is canceled (for example, due to a timeout), you receive a webhook containing the following JSON payload:


1{
2  "transactionId": "bea260bb-c183-4d74-8bc9-421fe3aa2658"
3}

Information

If you have integration questions or issues, contact your issuing representative or [email protected].
For SDK release notes, see GitHub – oob-authentication-android.

While Checkout.com handles in-depth compliance, you are responsible for performing Strong Customer Authentication (SCA) 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.

After you've completed the integration, see how to authenticate cardholders in your app:

Authenticate cardholders for transactions

Perform out-of-band (OOB) 3D Secure cardholder authentication for digital transactions in your app.

Out-of-Band Authentication iOS SDK

Before you begin

Note

How it works

SDK environments

Import the SDK

Information

Set up webhooks

Note

Transaction details webhook

Webhook fields

Cancellation webhook

Information

Set up Strong Customer Authentication

Next steps

Authenticate cardholders for transactions