3-D Secure 2 handlers for mobile apps

Most PSPs have their own certified SDKs for 3-D Secure 2 (3DS2) in mobile apps but they all have equivalent features. To abstract the details of specific 3DS2 SDKs, we define a interface PO3DSService in Kotlin and protocol PO3DS2Service in Swift that supply the functionality in a consistent way (this is the threeDSService parameter in the code samples above).

We officially support our own implementation POTest3DSService of PO3DSService that emulates the normal 3DS authentication flow but does not actually make any calls to a real Access Control Server (ACS). It is mainly useful during development in our sandbox testing environment.

The example below shows how you can create an instance of the POTest3DSService to pass as the threeDSService parameter of authorizeInvoice().

import ProcessOutUI

...

try await ProcessOut.shared.invoices.authorizeInvoice(
    request: request, threeDSService: POTest3DSService()
)
ProcessOut.instance.invoices.authorize(
    request = request,
    threeDSService = POTest3DSService(
        activity = this,
        customTabLauncher = customTabLauncher,
        returnUrl = "yourapp://processout/return"
    )
)

With some PSPs such as Adyen you must add the version number of the 3DS2 SDK to the POInvoiceAuthorizationRequest object when you make the call to authorizeInvoice().

The example below demonstrates how you can do that and also change the preferred card scheme (for example, to carte bancaire) if the customer's card supports co-schemes.

...

let request = POInvoiceAuthorizationRequest(
    ...
    preferredScheme: "carte bancaire", // Optional
    thirdPartySdkVersion: "<VERSION>"
)

try await ProcessOut.shared.invoices.authorizeInvoice(
    request: request, threeDSService: threeDSService
)

...
val request = POInvoiceAuthorizationRequest(
    ...
    thirdPartySdkVersion = "<VERSION>",
    preferredScheme = "carte bancaire" // Optional.
)

ProcessOut.instance.invoices.authorize(
    request = request,
    threeDSService = threeDSService
)

Netcetera 3DS SDK integration on iOS

We provide a built-in integration with the Netcetera 3DS SDK, available as a separate ProcessOutNetcetera3DS module. The example below shows how to create a PONetcetera3DS2Service and use it.

import UIKit
import ProcessOut
import ProcessOutNetcetera3DS
import ThreeDS_SDK

// 1. Define the 3DS service delegate (optional).
final class NetceteraDelegate: PONetcetera3DS2ServiceDelegate {

    func netcetera3DS2Service(
        _ service: PONetcetera3DS2Service, shouldContinueWith warnings: [Warning]
    ) async -> Bool {
        // The default implementation ignores all warnings. You can change that
        // and, for example, abort 3DS2 if there is a high severity warning.
        !warnings.contains { $0.getSeverity() == .HIGH }
    }

    func netcetera3DS2Service(
        _ service: PONetcetera3DS2Service,
        willPerformChallengeOn viewController: inout UIViewController?
    ) async {
        // Optionally change the view controller used to present the challenge.
        // If it is nil when this method returns, the challenge fails.
    }
}

// 2. Create the delegate and keep a strong reference to it, for example as a
//    property of your view model. The service only holds the delegate weakly.
let threeDSServiceDelegate = NetceteraDelegate()

// 3. Create the configuration (optional).
let configuration = PONetcetera3DS2ServiceConfiguration(
    returnUrl: URL(string: "https://yourapp.example.com/3ds/return")! // See "Out-of-band (app-to-app) challenges".
)

// 4. Create the 3DS service.
let threeDSService = PONetcetera3DS2Service(
    configuration: configuration, delegate: threeDSServiceDelegate
)

try await ProcessOut.shared.invoices.authorizeInvoice(
    request: request, threeDSService: threeDSService
)
📘

PONetcetera3DS2Service reports the version of the bundled Netcetera SDK automatically, so you don't need to set thirdPartySdkVersion in POInvoiceAuthorizationRequest. If you set it, your value replaces the automatic one.

📘

Only one 3DS authentication can run at a time. The Netcetera SDK does not support concurrent use, even across different PONetcetera3DS2Service instances.

Configuration options

All parameters of PONetcetera3DS2ServiceConfiguration are optional.

ParameterDefaultDescription
authenticationMode.compatibility.compatibility leaves out device parameters that produce large values (I003 font families, I011 locales), which keeps the request within the payload size limits some providers enforce (e.g. Stripe's 5000 characters). .full collects every available parameter.
localenil (system)Locale used for the challenge UI.
uiCustomizationsnilNetcetera UiCustomization values for each appearance (UiCustomization.UICustomizationType).
showsProgressViewtrueWhether a progress view is shown while the SDK collects device data. A progress view is always shown right before a challenge, whatever this is set to.
bridgingExtensionVersionnilTurns on the EMV® 3DS Bridging Message Extension (.v1 or .v2). See below.
returnUrlnilURL the issuer's app uses to return the customer to your app. Required for app-to-app. See below.
challengeTimeout5 minutesTime allowed to complete the challenge. The minimum is 5 minutes.
logLevel.errorLog level of the Netcetera SDK.

Out-of-band (app-to-app) challenges

Some issuers authenticate the customer out-of-band (OOB): during the challenge the customer is switched to their banking app and approves the payment there. The banking app then opens your app again, and the 3DS SDK finishes the challenge without the customer having to tap "Continue". To support this flow:

1. Provide a return URL. Pass returnUrl when creating the configuration. It is sent to the issuer as the 3DS Requestor App URL. The SDK adds a transID query parameter automatically, so the URL you register must accept extra query parameters.

❗️

Use a universal link (an https:// URL associated with your app) as the return URL. Custom URL schemes such as yourapp:// are technically accepted by the SDK, but some issuers' ACSs reject them, and the challenge then can't return to your app.

let configuration = PONetcetera3DS2ServiceConfiguration(
    bridgingExtensionVersion: .v2, // Optional, see step 3.
    returnUrl: URL(string: "https://yourapp.example.com/3ds/return")!
)

2. Forward incoming links to ProcessOut. Universal links reach your app as an NSUserActivity, and custom-scheme URLs through openURLContexts. Forward both to ProcessOut.shared.processDeepLink(url:):

final class SceneDelegate: UIResponder, UIWindowSceneDelegate {

    // Universal links (recommended).
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
           let url = userActivity.webpageURL {
            ProcessOut.shared.processDeepLink(url: url)
        }
    }

    // Custom URL schemes.
    func scene(_ scene: UIScene, openURLContexts urlContexts: Set<UIOpenURLContext>) {
        if let url = urlContexts.first?.url {
            ProcessOut.shared.processDeepLink(url: url)
        }
    }
}

In SwiftUI apps, use .onOpenURL { ProcessOut.shared.processDeepLink(url: $0) }. processDeepLink(url:) returns true when the SDK handled the URL.

3. (Optional) Enable the Bridging Message Extension. Set bridgingExtensionVersion so the SDK can process the EMV® 3DS Bridging Message Extension. When the ACS sends it, the SDK switches automatically for OOB v2.2 challenges and masks input for TEXT v2.2 challenges.

📘

If the system terminates your app while the customer is in their banking app, the challenge is lost and the return URL simply launches your app. Check the payment status after relaunch (for example, from your backend) and let the customer retry if needed.

Please check the SDK reference for additional details.

Netcetera 3DS SDK integration on Android

We also provide a built-in integration with the Netcetera 3DS SDK, which is available as a separate module.

implementation("com.processout:processout-android-netcetera-3ds:<version>")

Follow the steps below to create the PONetcetera3DS2Service.

// 1. Initialize PO3DSRedirectCustomTabLauncher in the onCreate() method of an Activity or Fragment.

private lateinit var customTabLauncher: PO3DSRedirectCustomTabLauncher

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    customTabLauncher = PO3DSRedirectCustomTabLauncher.create(from = this)
}

// 2. Implement the PONetcetera3DS2ServiceDelegate.

class Netcetera3DS2ServiceDelegate(
    private val provideActivity: () -> ComponentActivity?,
    private val customTabLauncher: PO3DSRedirectCustomTabLauncher,
    private val returnUrl: String
) : PONetcetera3DS2ServiceDelegate {

    override fun activity(): ComponentActivity? = provideActivity()

    override fun handle(
        redirect: PO3DSRedirect,
        callback: (ProcessOutResult<String>) -> Unit
    ) {
        customTabLauncher.launch(redirect, returnUrl, callback)
    }

    override suspend fun shouldContinue(warnings: Set<Warning>): Boolean {
        // Inspect the severity of the warnings to decide whether the flow should continue.
        // The default implementation ignores any warnings.
        return true
    }
}

// 3. Create the 3DS service.

val threeDSService = PONetcetera3DS2Service(
    delegate = Netcetera3DS2ServiceDelegate(
        provideActivity = { requireActivity() },
        customTabLauncher = customTabLauncher,
        returnUrl = "yourapp://processout/return"
    ),
    configuration = PONetcetera3DS2ServiceConfiguration() // optional
)
🚧

Netcetera 3DS SDK renders challenge UI within the provided activity instance. Make sure to provide the correct activity instance depending on your use case:

  • When integrating with the non-UI API bindings, provide an instance of your activity.
  • When integrating with the POCardTokenizationLauncher, provide the POCardTokenizationActivity.instance.
  • When integrating with the PODynamicCheckoutLauncher, provide the PODynamicCheckoutActivity.instance.
📘

If your app's release configuration includes shrinkResources true, make sure to add a rule to keep your themes and styles.

<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@style/*" />
📘

If your app uses DexGuard, make sure to include the configuration specified in the dexguard.txt file.

Please check the SDK reference for additional details.

Checkout 3DS SDK integration on iOS

We provide a built-in integration with the Checkout 3DS SDK, available as a separate
ProcessOutCheckout3DS module. The example below shows how to create a
POCheckout3DSService and use it.

import ProcessOut
import ProcessOutCheckout3DS
import Checkout3DS

// 1. Define the 3DS service delegate (optional).
final class Checkout3DSServiceDelegate: POCheckout3DSServiceDelegate {

    func checkout3DSService(
        _ service: POCheckout3DSService,
        configurationWith parameters: ThreeDS2ServiceConfiguration.ConfigParameters
    ) -> ThreeDS2ServiceConfiguration? {
        // If you don't want to customize the 3DS2 SDK appearance or behavior, you
        // can omit this method. `parameters` must be passed through unchanged.
        // The example below sets the return URL for app-to-app challenges and
        // changes the challenge timeout to 10 minutes.
        .init(
            configParameters: parameters,
            appURL: URL(string: "https://yourapp.example.com/3ds/return")!,
            challengeTimeout: 10 * 60
        )
    }

    func checkout3DSService(
        _ service: POCheckout3DSService,
        shouldContinueWith warnings: Set<Warning>
    ) async -> Bool {
        // The default implementation ignores all warnings. You can change that
        // and, for example, abort 3DS2 on jailbroken devices.
        !warnings.contains(.jailbroken)
    }
}

// 2. Create the delegate.
let threeDSServiceDelegate = Checkout3DSServiceDelegate()

// 3. Create the 3DS service.
let threeDSService = POCheckout3DSService(
    // The service holds a strong reference to the delegate, so make sure you
    // are not creating any retain cycles.
    delegate: threeDSServiceDelegate, environment: .sandbox
)

try await ProcessOut.shared.invoices.authorizeInvoice(
    request: request, threeDSService: threeDSService
)

Out-of-band (app-to-app) challenges

To let the issuer's banking app return the customer to your app after an out-of-band challenge, pass appURL in the ThreeDS2ServiceConfiguration returned from your delegate, as shown above, and forward incoming links to ProcessOut.shared.processDeepLink(url:) from your scene delegate (both scene(_:continue:) for universal links and scene(_:openURLContexts:) for custom schemes).

❗️

Use a universal link (an https:// URL) as appURL. Some issuers' ACSs reject custom URL schemes.

Checkout 3DS SDK integration on Android

We also provide a built-in 3DS2 SDK that is available in separate ProcessOutCheckout3DS module on Android.

The example below shows how you can create an instance of Checkout-based PO3DSService and use it.

// 1. Initialize PO3DSRedirectCustomTabLauncher in the onCreate() method of Activity or Fragment.

private lateinit var customTabLauncher: PO3DSRedirectCustomTabLauncher

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    customTabLauncher = PO3DSRedirectCustomTabLauncher.create(from = this)
}

// 2. Implement POCheckout3DSServiceDelegate and pass the launcher.

class Checkout3DSServiceDelegate(
    private val activity: Activity,
    private val customTabLauncher: PO3DSRedirectCustomTabLauncher
) : POCheckout3DSServiceDelegate {

    override fun configuration(parameters: ConfigParameters): ThreeDS2ServiceConfiguration {
        return ThreeDS2ServiceConfiguration(
            context = activity,
            configParameters = parameters,
            // Optional properties.
            locale = Locale.UK,
            uiCustomization = UICustomization(),
            appUri = Uri.parse("https://my-app-url.com"),
            challengeTimeout = 300
        )
    }

    override fun shouldContinue(warnings: Set<Warning>, callback: (Boolean) -> Unit) {
        // The default implementation ignores all warnings.
        // As an example we can define to continue the flow
        // only if there are no warnings or all warnings have low severity.
        callback(warnings.all { it.severity == Severity.LOW })
    }

    override fun handle(redirect: PO3DSRedirect, callback: (ProcessOutResult<String>) -> Unit) {
        customTabLauncher.launch(
            redirect = redirect,
            returnUrl = "yourapp://processout/return",
            callback = callback
        )
    }

    // Optionally implement service lifecycle callbacks for logs or custom logic.

    override fun willCreateAuthenticationRequest(configuration: PO3DS2Configuration) {}

    override fun didCreateAuthenticationRequest(result: ProcessOutResult<PO3DS2AuthenticationRequest>) {}

    override fun willHandle(challenge: PO3DS2Challenge) {}

    override fun didHandle3DS2Challenge(result: ProcessOutResult<Boolean>) {}
}

// 3. Create the 3DS service.
val threeDSService = POCheckout3DSService.Builder(
    activity = this,
    delegate = Checkout3DSServiceDelegate(activity = this, customTabLauncher)
)   // Optional parameter, by default Environment.PRODUCTION.
    .with(environment = Environment.SANDBOX)
    .build()

For other providers, you can create your own PO3DSService implementation using our code as a starting point. See our GitHub repositories with the definition of the 3DS2 SDK integration for Android and iOS.


Did this page help you?