Migrate to the latest Android SDK version
Update to the current most recent version of the Android SDK, which is 4.0.1.
We’re rolling out Android 4.0.1, part of a major update to our mobile SDKs, introducing a refreshed user experience and powerful new features — including a new, seamless UI and support for payment retries.
A new, conversion-driven UI in parity with the TrueLayer web hosted page, with the following new features available automatically for all GBP and EUR single payments:
- 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.

The 4.x.x Mobile SDK UI.

The screen that appears when your user attempts to cancel their payment.
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.
Requirements
- The minimum Kotlin version is now
2.1.20
- The minimum Compose BOM is now
2025.06.01
- The
minSdk
is now 24,compileSdk
is 35 andtargetSdk
is 35 - If you are using the
androidx.datastore.datastore-preferences
explicitly in your project, make sure you've set the version to1.1.7
. - the
desugaring
library must be version2.1.5
You must also update these other libraries as follows:
androidx.activity.activity-compose
:1.10.1
androidx.appcompat.appcompat
:1.7.1
androidx.compose.runtime.runtime-tracing
:1.8.3
androidx.core.core-ktx
:1.16.0
androidx.fragment.fragment-ktx
:1.8.8
androidx.lifecycle.lifecycle-livedata-ktx
:2.9.1
androidx.lifecycle.lifecycle-runtime-compose-android
:2.9.1
androidx.lifecycle.lifecycle-runtime-ktx
:2.9.1
androidx.lifecycle.lifecycle-viewmodel-compose
:2.9.1
androidx.lifecycle.lifecycle-viewmodel-ktx
:2.9.1
androidx.navigation.navigation-compose
:2.9.1
androidx.room.room-compiler
:2.7.1
androidx.room.room-ktx
:2.7.1
androidx.room.room-runtime
:2.7.1
androidx.work.work-multiprocess
:2.10.2
androidx.work.work-runtime-ktx
:2.10.2
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:
Original | New location |
---|---|
com.truelayer.payments.ui.models.PaymentContext | com.truelayer.payments.ui.screens.processor.ProcessorContext.PaymentContext |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorResult | com.truelayer.payments.ui.screens.processor.ProcessorResult |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorActivityContract | com.truelayer.payments.ui.screens.processor.ProcessorActivityContract |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorActivity | com.truelayer.payments.ui.screens.processor.ProcessorActivity |
com.truelayer.payments.ui.screens.coordinator.FlowCoordinator | com.truelayer.payments.ui.screens.processor.Processor |
com.truelayer.payments.ui.models.PaymentUseCase | com.truelayer.payments.ui.screens.processor.PaymentUseCase |
com.truelayer.payments.ui.models.PaymentContext.Preferences | com.truelayer.payments.ui.screens.processor.ProcessorContext.PaymentPreferences |
PaymentContext.paymentId | PaymentContext.id |
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.
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
We've extended Android compatibility to Android 5.0+ (API level 21+). 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:
- Enable Compose in your project by adding the code snippet below to the
android
block in your app-levelbuild.gradle
file.
buildFeatures {
compose = true
}
composeOptions {
kotlinCompilerExtensionVersion = "1.5.4"
}
- Add the following dependencies to your
build.gradle
file:
implementation("androidx.activity:activity-compose:$latest-version")
implementation("androidx.compose.material3:material3")
- Follow the steps for Compose integration.
- For a full list of customisation options, read the Compose customisation guide.
If you are directly integrating with Compose
For the activity that hosts the Compose view that processes the payment:
- Call
enableEdgeToEdge()
inActivity.onCreate
. - Set
android:windowSoftInputMode="adjustResize"
in your Activity'sAndroidManifest.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)
Updated 2 days ago