Migrate to the latest Android SDK version

Update to the current most recent version of the Android SDK, which is 4.1.6.

The latest version of the Android SDK is 4.1.6.

Version 4.1.6 includes all the features of 4.x.x, including a refreshed user experience with a new, seamless UI and support for payment retries.

📘

If you're using any version of the 4.x.x SDK, we strongly recommend updating to 4.1.6. This version includes critical bug fixes that prevent an indefinite loading issue when making payments with certain banks.

The following new features are available automatically for all GBP single payments and EUR payments in Ireland:

• A single-screen, modern, declarative UI system under the hood, allowing for smooth transitions and improved user experience.
• Retries: allow your users to change bank on the fly, or retry failed payments without restarting the SDK.
• Cancellation screen streamlining: more insight on why users are abandoning their payments.
• Preselected providers for returning users: automatically select the last used provider, allowing for faster one-click payments and more engaged, better converting users.

This update contains minor bug fixes, improvements and underlying library updates.

If you are upgrading from version 3.8.0 or later, this is not a breaking release. The minimum requirements for some libraries have changed. If you define libraries explicitly within your project, you need to update these.

If you don't define libraries explicitly within your project, they will automatically update.

Requirements

• The minimum Kotlin version is now 2.2.20

• The minimum Compose BOM is now 2025.12.00

• The minSdk is now 24, compileSdk is 36 and targetSdk is 36

• If you are using the androidx.datastore.datastore-preferences explicitly in your project, make sure you've set the version to 1.1.7.

• the desugaring library must be version 2.1.5

• the gradle library must be version gradle-8.13.1

  If you are explicitly defining libraries within your project, use these versions:

  • androidx.activity.activity-compose : 1.11.0
  • androidx.compose.runtime.runtime-tracing : 1.9.4
  • androidx.core.core-ktx : 1.17.0
  • androidx.fragment.fragment-ktx : 1.8.9
  • androidx.fragment.fragment-testing : 1.8.9
  • androidx.lifecycle.lifecycle-livedata-ktx : 2.10.0
  • androidx.lifecycle.lifecycle-runtime-compose-android : 2.10.0
  • androidx.lifecycle.lifecycle-runtime-ktx : 2.10.0
  • androidx.lifecycle.lifecycle-viewmodel-compose : 2.10.0
  • androidx.lifecycle.lifecycle-viewmodel-ktx : 2.10.0
  • androidx.navigation.navigation-compose : 2.9.5
  • androidx.work.work-multiprocess : 2.11.0
  • androidx.work.work-runtime-ktx : 2.11.0
  • com.google.android.material.material : 1.13.0
  • androidx.appcompat.appcompat : 1.7.1
  • androidx.room.room-compiler : 2.7.1
  • androidx.room.room-ktx : 2.7.1
  • androidx.room.room-runtime : 2.7.1
  • com.android.tools.desugar_jdk_libs : 2.1.5
  • io.coil-kt.coil-compose : 2.7.0
  • io.coil-kt.coil-svg : 2.7.0
  • io.coil-kt.coil : 2.7.0
  • org.jetbrains.kotlinx.kotlinx-coroutines-android : 1.10.2
  • org.jetbrains.kotlinx.kotlinx-coroutines-core : 1.10.2
  • org.jetbrains.kotlinx.kotlinx-coroutines-test : 1.10.2

There are some naming changes. The classes and functions that have been moved are listed in the table below:

Instead of a dependency on com.google.android.material:material, the SDK now has a dependency on androidx.compose.material3:material3. The dependency on com.google.accompanist:accompanist-insets has also been removed.

The Activity that hosts the SDK must be either android:launchMode="singleTask" or android:launchMode="singleInstance" depending on your app requirements.

This is to make sure that the SDK Activity is not recreated when your end user is redirected back from the bank to your app. This is important so that the result screen is not shown multiple times.

Limitations

The following features are supported by the SDK, but do not work with the newest UI. Instead, they will fall back to the legacy UI as it appeared in versions 3.9.1 and below:

• Payment mandates (or recurring payments)
• EUR payments for countries other than Ireland

This means that retries and cancellation insights are not available for these payments.

SDK theming

The SDK theme is applied automatically and is no longer customisable by integrators. You don't need to wrap the Processor composable with Theme — remove any previous TrueLayerTheme setup from your integration.

Because the SDK uses Scaffold and BottomSheetScaffold under the hood to present its UI components, you need to make sure that you don't have nested Scaffold or BottomSheetScaffold in your app when integrating the SDK via Compose. If you do, although the SDK will work the UI may not behave as expected.

Callbacks

The redirect callback has been removed from this version of the Android SDK. The SDK will no longer send a success message with reason redirect.

Therefore, the SDK will no longer be dismissed after the redirect to the bank app. Instead, you must bring the SDK screen back to the front when you redirect the user back from the bank app.

Payment statuses

The SDK now only returns one of the following terminal [statuses] for a payment:

• failed
• cancelled
• executed
• settled
• authorized.

Desugaring

The SDK supports Android 7.0+ (API level 24+). If your app supports Android 8.0 or below (API level 26), you must make sure that your project has desugaring enabled. Without desugaring, in specific scenarios, the SDK may crash on devices running Android below API level 26.

The following code example helps you to enable desugaring in your project.

android {
    ...

    compileOptions {
        coreLibraryDesugaringEnabled true
    }

    ...
}

dependencies {
	...
	coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.1.5"
	...
}

UI customisation with Jetpack Compose

To use the latest versions of the SDK, you must integrate with Compose to customise your app UI. You can no longer use XML files to do this.

If your app uses XML for UI

You can integrate the SDK with Compose, even if your app otherwise uses XML. Here's how:

1. Apply the Compose Compiler Gradle plugin (required for Kotlin 2.x) and enable Compose in your app-level build.gradle:

plugins {
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.20"
}

android {
    buildFeatures {
        compose = true
    }
}

2. Add the following dependencies to your build.gradle file:

implementation("androidx.activity:activity-compose:1.11.0")
implementation(platform("androidx.compose:compose-bom:2025.12.00"))
implementation("androidx.compose.material3:material3")

3. Follow the steps for Compose integration.

If you are directly integrating with Compose

For the activity that hosts the Compose view that processes the payment:

• Call enableEdgeToEdge() in Activity.onCreate.
• Set android:windowSoftInputMode="adjustResize" in your Activity's AndroidManifest.xml entry.
  This setting allows your app to receive the size of the software IME as insets. When the IME appears and disappears in your app, you can pad and lay out content appropriately.

These changes ensure that the UI displays correctly when the keyboard is shown.

If you process payments with a Jetpack Compose integration, remove the following code from your activity hosting. This code was required in previous versions, but will now cause user interface issues.

WindowCompat.setDecorFitsSystemWindows(window, false)
 @Suppress("DEPRECATION")
 window.setSoftInputMode(WindowManager.LayoutParams.SOFT_INPUT_ADJUST_RESIZE)