Front-end Integration for 3DS

3DS Android SDK

Install Install

Forter3DS SDK supports installation via Maven.

Requirements Requirements

Minimum version: Android 5.1 (API level 22)

Add to Maven Add to Maven

If the Gradle version is 7.0 and above:

Inside your app's settings.gradle, append the following repository, provided below, to your dependencyResolutionManagement block.

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        ...
        maven {
            url "https://mobile-sdks.forter.com/android"
            credentials {
                username "<username-provided-by-forter>"
                password "<password-provided-by-forter>"
            }
        }
    }
}

If the Gradle version is earlier than 7.0:

Inside your app's build.gradle, append the following repository, provided below, to your repositories block.

repositories {
    ...
    maven { url 'https://maven.google.com' }
    maven {
        url "https://mobile-sdks.forter.com/android"
        credentials {
            username "<username-provided-by-forter>"
            password "<password-provided-by-forter>"
        }
    }
}

Specify and commit the credentials to your Git. Note that these credentials are not sensitive, but we keep them private to prevent bots and search engines from accessing the repository.

Add the Forter3DS SDK dependency Add the Forter3DS SDK dependency

Add the Forter3DS SDK as a dependency to your app's build.gradle file under the dependencies block. Use the dependency provided below.

implementation 'com.forter.mobile:forter3ds:2.0.4'

Manifest Permissions Manifest Permissions

The Forter3DS SDK requires the common permission: Internet. This permission is typically required by many applications and components. If you have not already included it in your permissions list, please add to your manifest file.

<!-- Forter3DS SDK permissions -->
<uses-permission android:name="android.permission.INTERNET"/>

Initializing the SDK Initializing the SDK

The init method is utilized to configure and set up the SDK, ensuring its readiness to handle transactions effectively.

The SDK must be initialized from the main Application Context. If your app is not currently using an Application class, please add one and register it in the manifest.

Signature Signature

fun init(
    context: Context,
    config: Forter3DSConfig,
    callback: IForter3DSInitCallback?
)

Parameters Parameters

• context: An instance of the Android Context class, typically the application context.
• config: An instance of Forter3DSConfig containing configuration parameters for the SDK initialization.
• callback: An optional callback of type IForter3DSInitCallback to receive initialization status notifications.

Forter3DSConfig class Forter3DSConfig class

The Forter3DSConfig class encapsulates configuration parameters required for initializing the SDK. It includes the following parameters:

• merchantId: Represents the unique identifier assigned to the merchant within the application.
• siteId: The site ID associated with the merchant account.
• defaultCustomization: Customization options for the default theme.
• darkCustomization: Customization options for the dark theme.
• monochromeCustomization: Customization options for the monochrome theme.
• shouldLoadTestServers: A boolean flag indicating whether to load test servers during initialization.

IForter3DSInitCallback Interface IForter3DSInitCallback Interface

The IForter3DSInitCallback interface defines callback methods to notify the client application of the initialization status. It includes the following methods:

• onInitializationSucceeded(): Invoked when the SDK initialization is successful.
• onInitializationFailed(): Invoked when the SDK initialization fails.

Usage Usage

val context: Context = applicationContext
val config = Forter3DSConfig.Builder()
    .setMerchantId("your_merchant_id")
    .setSiteId("your_site_id")
    if (BuildConfig.DEBUG) {
        config.loadTestServers()
    }

Forter3DS.getInstance().init(context, config.build(), object : IForter3DSInitCallback {
    override fun onInitializationSucceeded() {
        // Handle successful initialization
    }

override fun onInitializationFailed() {
        // Handle initialization failure
    }
})

FTR3DSCustomization class FTR3DSCustomization class

The FTR3DSCustomization class provides customization options for the UI elements in the native challenge screen. It allows developers to customize buttons, labels, text boxes, and toolbars to match the design and branding requirements of their application.

• setButtonCustomization: Customizes background color, corner radius and text color.
• setLabelCustomization: Customizes font size, text color and font.
• setTextBoxCustomization: Customizes border color, border width and corner radius.
• setToolbarCustomization: Customizes background color, button text and header text.

To create an instance of FTR3DSCustomization, simply use its default constructor and apply the required customizations:

val customization = FTR3DSCustomization().apply {
    val button = FTR3DSButtonCustomization()
    button.setBackgroundColor("#FF7C72")
    setButtonCustomization(button, FTR3DSButtonType.SUBMIT)
    val label = FTR3DSLabelCustomization()
    label.setHeadingTextFontSize(40)
    setLabelCustomization(label)
}

Do Challenge if Needed Do Challenge if Needed

This method is called by your app with the managed order token obtained from the backend. If a WebView challenge is presented, the method also requires a presenting Activity for displaying the challenge UI and an ActivityResultLauncher that will receive the challenge result.

Signature Signature

fun doChallengeIfNeeded(
    activity: Activity?,
    launcher: ActivityResultLauncher<FTR3DSChallengeParams>,
    token: String,
    callback: IForter3DSChallengeCallback
)

Parameters Parameters

• activity: The activity responsible for presenting the challenge UI.
• launcher: The launcher that will receive the WebView challenge result.
• token: The managed order token obtained from your backend.
• callback: The callback for the native challenge result.

IForter3DSChallengeCallback interface IForter3DSChallengeCallback interface

The IForter3DSChallengeCallback interface provides callback methods for handling challenge results during the 3DS authentication process.

Callback Methods

• onChallengeFinished: Invoked when a challenge is successfully completed. Receives a JSONObject with an encoded challenge result.
• onChallengeFail(): Invoked when a challenge fails.
• onChallengeSkipped(): Invoked when a challenge is skipped.

All callback methods are executed on the main thread.