Checkout.com’s Out-of-Band (OOB) Authentication SDK enables iOS apps to authenticate users for digital transactions (3DS). Our OOB SDK enables you to offer a modern 3DS challenge method alongside existing challenge types, such as OTP.
OOB involves utilising a secondary factor, such as your phone’s banking app, to authenticate a payment and encompasses the fundamental processes of device binding and transaction authentication. Our OOB SDK is focused on this use case.
The iOS SDK supports the following environments: Sandbox and Production. You’ll define the environment to use when you initialise the SDK.
To use Sandbox and Production environments, you must have begun onboarding for card issuing with Checkout.com. During your onboarding, you'll receive client credentials, which you'll need to handle on your back end for authentication to access the environments.
-
The SDK is provided as a native Swift package. If you're working on a hybrid project, consult your hybrid platform's documentation for instructions on integrating native third-party SDKs.
-
It's important to ensure Strong Customer Authentication (SCA) is enabled for your users. While we handle various security measures, you're responsible for performing SCA on your users as specified.
-
Each authentication session has the ability to generate multiple tokens simultaneously for various systems. For instance, for sign-in purposes or to obtain an SDK session token or an internal authentication token. However, only one SDK token can be generated from each SCA flow requested.
Our SDK is designed to seamlessly integrate with all our backend services for features relevant to OOB authentication. Whether you're registering a device for OOB or authenticating payments via your iOS app, our SDK simplifies the process, making it effortless for you to offer this functionality to your users.
Import the SDK into your app using Swift Package Manager (SPM):
- Open Xcode and navigate to
Project -> Package Dependencies. - When prompted, enter the URL: https://github.com/checkout/CheckoutCardManagement-iOS.git
- Select
Up to Next Major Versionas below
- Click on
Add Package - You'll be presented with these options:
- If you just want to use OOB SDK as a standalone SDK and no other product from Checkout.com, select your main target to include
CheckoutOOBSDKas below. If you also want to use Checkout.com's Issuing solution (CheckoutCardManagement), then follow the instructions in its README. (See an example here)
- Click on
Add Packageagain. - You have to add CheckoutNetwork as a dependency to your project as well. Use
https://github.com/checkout/NetworkClient-iOS.gitfor that - For an example, see our SampleApplication's configuration under
Project -> Package Dependenciesthereof. - Refer to Apple's documentation on adding a SPM dependency for detailed instructions.
To begin utilising the SDK functionality, initialise the primary object, granting access to its features:
import CheckoutOOBSDK
// Initialise the SDK with preferred environment
let checkoutOOB = CheckoutOOB(environment: .sandbox)This is the first core flow whereby the device and app must be registered for OOB. Note that a given card can only be registered for OOB for a single device/app combination. If you register another device for the same card it will overwrite the previously bound device/app combination.
The register device stage can likely be done as a background process during onboarding of a user in your iOS app, but you could offer a button that enables a user to do this manually if you wish. Note that before registering a device/app/card combination for OOB, you must perform SCA on the cardholder.
To establish device binding, register your cardholder's mobile device as follows:
// You must be in an async context to call SDK's async functions.
// You can use a Task for that.
Task {
do {
let deviceRegistration = try CheckoutOOB.DeviceRegistration(token: "access_token",
cardID: "card_id", // 30 characters
applicationID: "application_id", // Most probably your notification token. Communicate with your backend to figure it out.
phoneNumber: CheckoutOOB.PhoneNumber(countryCode: "+44", number: "5006007080"),
locale: .english) // Other option is `.french`
try await checkoutOOB.registerDevice(with: deviceRegistration)
} catch {
print(error.localizedDescription)
}
}This is the core authentication flow where the user will approve or reject the transaction within your iOS app. This flow will begin from our card issuing backend, where you will need to listen to the webhook provided to obtain transaction details to inject into the SDK (more on webhooks later).
Note that before authenticating a payment using OOB, you must perform SCA on the cardholder.
Once you have the data from your backend, verify online card transactions made by your cardholders like so:
Task {
do {
let paymentAuthentication = try CheckoutOOB.Authentication(token: "access_token",
cardID: "card_id", // 30 characters
transactionID: "transaction_id",
method: .biometrics,
decision: .accepted)
try await checkoutOOB.authenticatePayment(with: paymentAuthentication)
} catch {
print(error.localizedDescription)
}
}Our SDK remains light on UI objects so that you can create the experience you desire. You will therefore need to build the UI for the transaction authentication screen (the screen that shows during the authenticate payment stage), as well as any associated UI (if you wish so) for the register device process.
(Only read if you are developing the backend support for your application's OOB functionality, if you're solely a mobile developer, disregard this section)
In order to obtain transaction information to inject into our SDK, you must be able to listen to webhooks from our issuing backend. We recommend that you implement a push notification to the mobile app and use the data from the webhook to inform the cardholder about the details of the transaction they are authenticating for.
You should provide an endpoint that receives a HTTP POST and returns a 200 OK response on receipt of the webhook. The transaction will not complete unless we receive acknowledgement.
The JSON payload you should expect looks like this:
{
"acsTransactionId": "bea260bb-c183-4d74-8bc9-421fe3aa2658",
"cardId": "ea3ze38kfj3g6ktv6wn14aaylvmdv3qn",
"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"
}
The applicationId property is used to identify which mobile app to send a push notification to.
We will also provide a webhook in the event that the transaction is cancelled, due to timeout or any other cause. We also expect a 200 OK acknowledgement for this webhook. In this case, the JSON payload will look like this:
{
"transactionId": "bea260bb-c183-4d74-8bc9-421fe3aa2658"
}In both cases we will also include an Authorization header in the request containing the value provided to us at client onboarding. This is used to verify that the request comes from us.
For any questions on onboarding, please speak to your issuing representative or contact [email protected].
You must perform SCA (strong customer authentication) on the cardholder before device registration and payment authentication flows. This would likely be when the user enters the app, but could be at other stages.