Out-of-Band Authentication Android SDK

Last updated: March 12, 2025

For the Issuing solution, you can integrate the CheckoutOOBManager Android 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 Android dependency, which your app can consume through Maven Central.

Use Gradle to import the SDK into your app. In your project-level build.gradle file, add:


1repositories {
2  mavenCentral()
3}

In your app-level build.gradle file, add:


1dependencies {
2  implementation("com.checkout:checkout-sdk-oob-android:$checkout_sdk_oob_version")
3}

Information

If you're building a hybrid app, see your platform's documentation on how to consume native third-party SDKs.

Initialize the primary CheckoutOOBManager object and set the SDK environment:


1val oobManager = CheckoutOOBManager(context = context, environment = 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": "2025-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}

Use the following code to handle errors that the OOB SDK may encounter during operation:


1private fun provideErrorMessage(throwable: Throwable): String {
2    return when (throwable) {
3        is ConfigurationError -> {
4            when (throwable.errorCode) {
5                E1000_INVALID_CARD_ID -> "Invalid card ID"
6                E1001_INVALID_TOKEN -> "Invalid token"
7                E1005_INVALID_TRANSACTION_ID -> "Invalid transaction ID"
8                else -> throwable.errorMessage
9            }
10        }
11       is UnprocessableContentError ->
12            "Server failure with error code: ${throwable.errorCode} and error message: ${throwable.errorMessage}"
13       is HttpError -> "error code ${throwable.errorCode}, message: ${throwable.errorMessage}"
14       is ConnectivityError -> {
15            when (throwable.errorCode) {
16                E1006_NO_INTERNET_CONNECTION -> "No internet connection"
17                E1007_CONNECTION_FAILED -> "Network connection failed. Please check internet connection"
18                E1008_CONNECTION_TIMEOUT -> "Network connection timeout. Please try again later"
19                else -> "Unknown connectivity error"
20            }
21        }
22        else -> throwable.message ?: "Unknown error from the SDKKit. Please contact support."
23    }
24}

Information

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

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 Android 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

Handle errors

Information

Set up Strong Customer Authentication

Next steps

Authenticate cardholders for transactions