Migrate to the latest Android SDK version

The latest version of the Android SDK is 4.1.1.

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

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.10.01
• 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

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.9.4
• androidx.lifecycle.lifecycle-runtime-compose-android : 2.9.4
• androidx.lifecycle.lifecycle-runtime-ktx : 2.9.4
• androidx.lifecycle.lifecycle-viewmodel-compose : 2.9.4
• androidx.lifecycle.lifecycle-viewmodel-ktx : 2.9.4
• 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
• 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:

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

When integrating via Compose you no longer need to wrap the Processor composable with Theme.
The theme will be applied automatically. If you want to customise the theme, the Processor composable
now accepts a theme parameter.

Contact us for more details about custom theming. If you try to customise the SDK theme but custom theming is not enabled, the SDK falls back to the default theme.

// Your payments custom theme or use the provided defaults as below
// theme is optional, if not provided default theme will be applied
val theme = TrueLayerTheme(
    lightPalette = LightColorDefaults,
    darkPalette = DarkColorDefaults,
    typography = TypographyDefaults
)

// Obtain your payment context from your backend
val paymentContext = PaymentContext(
    id =  "your-payment-identifier",
    resourceToken = "payment-resource-token",
    redirectUri = "redirect-uri-that-will-be-invoked-when-coming-back-from-bank"
)

setContent {
    Processor(
        context = paymentContext,
        // theme is optional, if not provided default theme will be applied
        theme = theme,
        onSuccess = { successStep ->
            // action on success
        },
        onFailure = { failureReason ->
            // action on failure
        }
    )
}

Because the SDK is using 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.

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

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)