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 new 4.x.x Mobile SDK UI.

The 4.x.x Mobile SDK UI.

The screen that appears when your user cancels a payment.

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 and targetSdk is 35
  • 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

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:

OriginalNew location
com.truelayer.payments.ui.models.PaymentContextcom.truelayer.payments.ui.screens.processor.ProcessorContext.PaymentContext
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorResultcom.truelayer.payments.ui.screens.processor.ProcessorResult
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorActivityContractcom.truelayer.payments.ui.screens.processor.ProcessorActivityContract
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorActivitycom.truelayer.payments.ui.screens.processor.ProcessorActivity
com.truelayer.payments.ui.screens.coordinator.FlowCoordinatorcom.truelayer.payments.ui.screens.processor.Processor
com.truelayer.payments.ui.models.PaymentUseCasecom.truelayer.payments.ui.screens.processor.PaymentUseCase
com.truelayer.payments.ui.models.PaymentContext.Preferencescom.truelayer.payments.ui.screens.processor.ProcessorContext.PaymentPreferences
PaymentContext.paymentIdPaymentContext.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:

  1. Enable Compose in your project by adding the code snippet below to the android block in your app-level build.gradle file.
buildFeatures {
    compose = true
}

composeOptions {
    kotlinCompilerExtensionVersion = "1.5.4"
}

  1. Add the following dependencies to your build.gradle file:
implementation("androidx.activity:activity-compose:$latest-version")
implementation("androidx.compose.material3:material3")

  1. Follow the steps for Compose integration.
  2. 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() 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)