--- title: 3DS Android SDK slug: 3ds-android-sdk docTags: createdAt: 2026-06-01T13:20:14.000Z --- ## Install Forter3DS SDK supports installation via [Maven](https://developer.android.com/build/dependencies#google-maven) ### Requirements Minimum version: `Android 5.0 (API level 21)` :::::WorkflowBlock ::::WorkflowBlockItem ### 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. ```text dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() ... maven { url "https://mobile-sdks.forter.com/android" credentials { username "" password "" } } } } ``` 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. ```text repositories { ... maven { url 'https://maven.google.com' } maven { url "https://mobile-sdks.forter.com/android" credentials { username "" password "" } } } ``` :::hint{type="warning"} 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. ::: :::: ::::WorkflowBlockItem ### 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. :::CodeblockTabs build.gradle ```c implementation 'com.forter.mobile:forter3ds:2.1.0' ``` build.gradle.kts ```none implementation("com.forter.mobile:forter3ds:2.1.0") ``` ::: :::: ::::WorkflowBlockItem ### 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. :::CodeblockTabs AndroidManifest.xml ```xml ``` ::: :::: ::::: *** ## 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 :::CodeblockTabs Kotlin ```kotlin fun init( context: Context, config: Forter3DSConfig, callback: IForter3DSInitCallback? ) ``` Java ```java void init( Context context, Forter3DSConfig config, IForter3DSInitCallback callback ); ``` ::: ### 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 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. It typically aligns with the site ID unless a PSP necessitates distinct IDs per merchant. - **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. Set it with `setShouldLoadTestServers(true)`, and only in a testing environment. - **thirdPartyBaseUrl** (optional, from version 2.1.0): Your custom domain (CNAME), if Forter provided one because your app must not call Forter's domains directly. The SDK then sends all 3DS requests (managed-order execution, verification and the 3DS Method notification) to this domain instead of Forter's default hosts. Set it with `setThirdPartyBaseUrl("https://")`. `build()` throws `Forter3DSConfigError` if the value isn't an `https` URL with a host. ### 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 :::CodeblockTabs Kotlin ```kotlin val context: Context = applicationContext val config = Forter3DSConfig.Builder() .setMerchantId("your_merchant_id") .setSiteId("your_site_id") .setShouldLoadTestServers(BuildConfig.DEBUG) // Only for testing // .setThirdPartyBaseUrl("https://") // Only if Forter provided a custom domain .build() Forter3DS.getInstance().init(context, config, object : IForter3DSInitCallback { override fun onInitializationSucceeded() { // Handle successful initialization } override fun onInitializationFailed() { // Handle initialization failure } }) ``` Java ```java Context context = getApplicationContext(); Forter3DSConfig config; try { config = new Forter3DSConfig.Builder() .setMerchantId("your_merchant_id") .setSiteId("your_site_id") .setShouldLoadTestServers(BuildConfig.DEBUG) // Only for testing // .setThirdPartyBaseUrl("https://") // Only if Forter provided a custom domain .build(); } catch (Forter3DSConfigError e) { // Invalid configuration, e.g. a missing site ID or a non-https custom domain return; } Forter3DS.getInstance().init( context, config, new IForter3DSInitCallback() { @Override public void onInitializationSucceeded() { // Handle successful initialization } @Override public void onInitializationFailed() { // Handle initialization failure } } ); ``` ::: ### 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: :::CodeblockTabs Kotlin ```kotlin val customization = FTR3DSCustomization().apply { val button = FTR3DSButtonCustomization() button.setBackgroundColor("#FF7C72") setButtonCustomization(button, FTR3DSButtonType.SUBMIT) val label = FTR3DSLabelCustomization() label.setHeadingTextFontSize(40) setLabelCustomization(label) } ``` Java ```java FTR3DSCustomization customization = new FTR3DSCustomization(); FTR3DSButtonCustomization button = new FTR3DSButtonCustomization(); button.setBackgroundColor("#FF7C72"); customization.setButtonCustomization(button, FTR3DSButtonType.SUBMIT); FTR3DSLabelCustomization label = new FTR3DSLabelCustomization(); label.setHeadingTextFontSize(40); customization.setLabelCustomization(label); ``` ::: *** ## Do Challenge if Needed This method is called by the 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 a `ActivityResultLauncher` that will receive the challenge result. If a native challenge is presented, the method requires a presenting `Activity` for displaying the challenge UI and a callback that will receive the challenge result. To initiate the `doChallengeIfNeeded` function, provide the `managedOrderToken` received from the backend (see [Order API](https://docs.forter.com/reference/order-v3)). :::hint{type="info"} From version 2.1.0, when the card issuer requires it, the SDK first runs the issuer's 3DS Method (a short device-data collection step) in a hidden web view, for up to 15 seconds. This happens automatically and requires no code changes. ::: ### Signature :::CodeblockTabs Kotlin ```kotlin val challengeLauncher: ActivityResultLauncher = registerForActivityResult(FTR3DSChallengeActivityResult()) { result -> result?.let { onChallengeFinished(it.data) } ?: run { onChallengeFail(null) } } fun doChallengeIfNeeded( activity: Activity?, launcher: ActivityResultLauncher, token: String, callback: IForter3DSChallengeCallback ) ``` Java ```java ActivityResultLauncher challengeLauncher = registerForActivityResult( new FTR3DSChallengeActivityResult(), result -> { if (result != null) { onChallengeFinished(result.getData()); } else { onChallengeFail(null); } } ); void doChallengeIfNeeded( Activity activity, ActivityResultLauncher launcher, String token, IForter3DSChallengeCallback callback ); ``` ::: ### 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 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(error: Throwable?)**: Invoked when a challenge fails. `error` describes the failure when available. Before version 2.1.0 this method took no arguments; update your implementation when upgrading. - **onChallengeSkipped()**: Invoked when a challenge is skipped. :::hint{type="info"} All callback methods are executed on the main thread. :::