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 theNetworkClient-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 CheckoutOOBSDK23// Initialize the SDK and set the environment4let 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 |
---|---|
string | The acquirer's unique identifier for the transaction you want the cardholder to authenticate. |
string | The unique identifier for the card, prefixed with |
string | The app you want to send the push notification to. |
object | Information about the transaction you want the cardholder to authenticate. |
string | The masked card primary account number (PAN). |
datetime | The date and time when the cardholder made the purchase, in UTC. |
string | The merchant the cardholder made the purchase with. |
double | The amount of the purchase, in the major currency unit. |
string | The currency of the purchase. |
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: