The Trustly Lightbox SDK for Android allows you to quickly build a bank authorization workflow in your Android app. Integrate the Select Bank Widget or the Trustly Lightbox to retrieve bank authorization data that can be used with other Trustly APIs.

To use an example project for testing and learning, see the Android Example in GitHub.

If you need help with your integration, contact your Trustly representative or send your request to us.integrations@trustly.com.

v3 SDKs and above deprecated PayWithMyBank references. If your app previously used v2 SDKs, you must change these references to Trustly when upgrading to a v3 or above SDK.

Prerequisites

Android 15: Edge-to-edge display mode is the default behavior for Android 15 (API level 35) and later. If your app wasn’t designed for edge-to-edge display mode, critical elements of your app can be obscured. To ensure your app remains functional, you may need to use Window Insets to apply padding or margins to your layouts.

Authentication flow

The following diagram illustrates how the Trustly SDK manages the secure transition between your application, the SDK, and the banking institution.

sequenceDiagram
    participant User
    participant App
    participant SDK as Trustly SDK
    participant System as Android System / Bank

    User->>App: Start
    App->>SDK: Initialize
    SDK-->>System: Open Auth [A]
    
    Note right of System: Login
    
    System-->>App: Redirect [B]
    App->>SDK: Verify
    SDK-->>App: Callback [C]
    App-->>User: Success

Step	Description
A	Authentication launch The SDK launches a secure browser overlay (Chrome Custom Tabs) or performs a direct App-to-App switch if the user has the target bank app installed.
B	Deep Link return The bank redirects the user back to your application using the URL scheme defined in your `strings.xml`. Android recognizes this scheme and brings your `LightboxActivity` to the foreground.
C	SDK resumption Your `onRestart` override calls `proceedToChooseAccount`, prompting the SDK to verify the transaction status and trigger the `onReturn` callback.

Configure Gradle and Android dependencies

To add the Trustly SDK and the AndroidX Browser Library with Chrome Custom Tabs to your project, open your build.gradle file and add the following dependencies:

// build.gradle
dependencies {
    implementation 'net.trustly:trustly-android-sdk:4.2.0'
    implementation 'androidx.browser:browser:1.8.0'
    implementation 'com.google.code.gson:gson:2.13.1'
    // ...
}

Sync your project to enable the dependency changes.
If your app does not have internet permissions enabled, open the AndroidManifest.xml file and add the INTERNET permission:
```
<uses-permission android:name="android.permission.INTERNET" />
```
Define an App Link for your app if you have not defined one. Without it, customers are not automatically redirected to your app after they log in to their mobile banking app. See Set up App Links.

Define Establish Data with a Request Signature

To ensure communications between the Trustly Lightbox SDK and the Trustly API are secure, use a requestSignature. You must generate a signature on your server using your access key and pass it to the Android app before rendering the Select Bank Widget or Trustly Lightbox.

Create a helper object in a new file named EstablishData.kt to hold your configuration:

package com.myapp

object EstablishData {

    fun getEstablishDataValues(): Map<String, String> {
        val establishDataValues: MutableMap<String, String> = HashMap()
        establishDataValues["accessId"] = "YOUR_ACCESS_ID"
        establishDataValues["merchantId"] = "YOUR_MERCHANT_ID"
        establishDataValues["requestSignature"] = "GENERATED_HASH"
        establishDataValues["description"] = "transaction description"
        establishDataValues["merchantReference"] = "ABCDREF"
        establishDataValues["currency"] = "USD"
        establishDataValues["amount"] = "0.00"
        establishDataValues["paymentType"] = "Deferred"
        establishDataValues["metadata.urlScheme"] = "yourapp://" // your app's deep link
        
        // establishDataValues["env"] = "sandbox"
        return establishDataValues
    }
}

When testing in the sandbox environment, set the env property to sandbox. You must remove the env property before publishing your production application.

To generate a requestSignature, see Generate request signatures. For a full list of parameters, see About OAuth Authentication.

Display the Select Bank Widget

Trustly recommends rendering the Select Bank Widget for an optimal customer experience.

In your activity's layout XML (for example, activity_main.xml), add the TrustlyView:

<androidx.constraintlayout.widget.ConstraintLayout>
    <net.trustly.android.sdk.views.TrustlyView
        android:id="@+id/trustlyWidgetView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

In your activity's onCreate method, initialize the widget and handle the bank selection event. Use onBankSelected to update your establishData with the customer's choice:

// MainActivity.kt
val establishData = EstablishData.getEstablishDataValues().toMutableMap()

val trustlyWidget = findViewById<TrustlyView>(R.id.trustlyWidgetView)

trustlyWidget.selectBankWidget(establishData).onBankSelected { callback, data ->
    establishData["paymentProviderId"] = data["paymentProviderId"].toString()
}

Launch the Lightbox

Add a button to your activity's layout XML (for example., activity_main.xml) to launch the payment flow:

<androidx.appcompat.widget.AppCompatButton
    android:id="@+id/btnConnectWithMyBank"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:text="@string/connect_my_bank"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent" />

Configure the button listener to launch a new activity. For example, LightboxActivity and pass the establishData:

// MainActivity.kt
val connectTrustlyButton = findViewById<AppCompatButton>(R.id.btnConnectWithMyBank)

connectTrustlyButton.setOnClickListener {
    val intent = Intent(this@MainActivity, LightboxActivity::class.java)
    intent.putExtra(LightboxActivity.ESTABLISH_DATA, establishData as Serializable)
    startActivity(intent)
}

In your LightboxActivity, call establish to open the Lightbox:

class LightboxActivity : AppCompatActivity() {

    private lateinit var lightboxView: TrustlyView
    
    companion object {
        const val ESTABLISH_DATA = "establish_data"
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_light_box)

        val establishData = intent.getSerializableExtra(ESTABLISH_DATA) as Map<String, String>
        lightboxView = findViewById(R.id.lightBoxWidget)
        lightboxView.establish(establishData)
    }
}

Optional. If your application doesn't specify a screen orientation, add the android:configChanges attribute to your AndroidManifest.xml to handle rotation gracefully. For example:
```
<activity android:name=".LightboxActivity"
        android:configChanges="screenSize|orientation" />
```
For more information about handling configuration changes in Android apps, see Handle configuration changes.

Add callback functions

The Trustly Lightbox provides two callback functions to handle transaction results:

onReturn: Called when the customer successfully authorizes the transaction.
onCancel: Called if the customer exits the process or the authorization fails.

Chain these callbacks to the establish method to handle the transaction result.

In the following example, a redirectToScreen helper function is used to prompt the customer when their transaction is successfully or unsuccessfully authorized:

lightboxView.establish(establishData)
    .onReturn(
        TrustlyCallback { lightboxView: Trustly?, returnData: Map<String, String> ->
            // TODO: Handle success (For example, navigate to a success screen)
            // redirectToScreen(Callback.RETURN) 
            Log.d("Trustly", "Transaction successful: $returnData")
        }
    ).onCancel(
        TrustlyCallback { lightboxView: Trustly?, cancelData: Map<String, String> ->
             // TODO: Handle cancellation (For example, show a toast or stay on current screen)
             // redirectToScreen(Callback.CANCEL)
             Log.d("Trustly", "Transaction cancelled")
        }
    )

Your application should retrieve data provided in the onReturn callback (such as the transaction ID) and pass it to your server for validation.

Add an OAuth transition handler

To support the transition from an external OAuth login (such as a bank app) back to the Lightbox, override the onRestart method in your LightboxActivity. This ensures the Lightbox resumes correctly after the user returns to your app.

// LightboxActivity.kt

       override fun onCreate(savedInstanceState: Bundle?) {
           super.onCreate(savedInstanceState)

           val transactionDetail = getTransactionDetailFromUri(intent.data!!)
                   val intent = Intent(
               this,
               LightboxActivity::class.java
           ).apply { addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP) }
               .putExtra(LightboxActivity.TRANSACTION_DETAILS, transactionDetail as Serializable)
       startActivity(intent)
       finish()
   }

   fun getTransactionDetailFromUri(appLinkData: Uri): Map<String, String> {
       return mapOf(
           Pair("transactionId", appLinkData.getQueryParameter("transactionId")!!),
           Pair("transactionType", appLinkData.getQueryParameter("transactionType")!!),
           Pair("panel", appLinkData.getQueryParameter("panel")!!),
           Pair("payment.paymentType", appLinkData.getQueryParameter("payment.paymentType")!!),
           Pair("status", appLinkData.getQueryParameter("status")!!)
       )
   }
   }

Add an override to the LightboxActivity class to support the transition from the OAuth login authorization to the Lightbox launch. For example:
```


override fun onRestart() {
    super.onRestart()

    lightboxView.proceedToChooseAccount()
}
```

App Links

Configure Android App Links to ensure users return directly to your application after completing a transaction.