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.

📘
Legacy Versions
v3 SDKs deprecated PayWithMyBank references. If your app previously used version 2, update these references to Trustly before you update to a v3 SDK.

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

Prerequisites

Android 5.0 (API level 21) or later

Note: 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 make sure your app remains functional, you might need to use window insets. Window insets allow you to apply padding or margins to your layouts and avoid overlapping or obscured screen elements. For more information about window insets, see Lay out your app within window insets.
AndroidX
Gradle 8 or later

Configure the Gradle and Android Dependencies

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

dependencies {

implementation 'net.trustly:trustly-android-sdk:4.0.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 following entry:
```


<uses-permission android:name="android.permission.INTERNET" />
```

To allow your app to be called from external events such as a redirect from a mobile banking app, add the following entry to the AndroidManifest.xmlfile:

<!-- AndroidManifest.xml -->
<activity android:name=".RedirectActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="yourapp" />
    </intent-filter>
</activity>

Define a deep link or URL scheme 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.

Define Establish Data with a Request Signature

To ensure communications between the Trustly Lightbox SDK and the Trustly API are secure, add a requestSignature authentication request to your Android app to request the server access key before rendering the Select Bank Widget or Trustly Lightbox. For example:

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
    }
}

NOTE: When using the sandbox environment, set the env property to sandbox. When publishing your production application, remove the env property.

For more information about generating a requestSignature, see Securing Requests.

For more information about properties, accepted values, and their behaviors, see Establish Data.

Display the Select Bank Widget

The Trustly Lightbox can be launched without using the Select Bank Widget. However, Trustly recommends rendering the Select Bank Widget for an optimal customer experience. For information about using the Select Bank Widget with the Trustly Lightbox, see Displaying the Bank Widget.

On the application activity implementation of onCreate, call the SDK’s selectBankWidget function to render the Select Bank Widget view. This example adds trustlyWidgetView to the activity_main.xml file:

<!-- activity_main.xml -->

<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>

Use the onBankSelected function to update the establishData parameter with the customer's bank information. For example:

<!-- 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 app that launches the Lightbox. This example adds a Connect With My Bank button:

<!-- activity_main.xml -->

<androidx.constraintlayout.widget.ConstraintLayout>
...

    <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" />

</androidx.constraintlayout.widget.ConstraintLayout>

Configure the button to open the screen that contains the Lightbox and pass the establishData values. For example:

<!-- MainActivity.kt -->

val establishData = EstablishData.getEstablishDataValues().toMutableMap()

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)
}

Attach the establish function to the Connect With My Bank button. For example:

class LightboxActivity : AppCompatActivity() {

    private lateinit var lightboxView: TrustlyView

    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)
    }
}

Add Callback Functions

The Trustly Lightbox provides two callback functions to handle terminal customer behaviors. When a customer successfully creates a bank authorization, the onReturn function is called. If the customer exits the process at any time, or the authorization is otherwise unsuccessful, the onCancel function is called. For more information about these functions, see Handling the Redirect.

Define two functions to handle callbacks and pass them into the onReturn and onCancel parameters of the establish method. In the following example, a redirectToScreen method is used to prompt the customer to perform an action when their transaction is successfully or unsuccessfully authorized:

lightboxView.establish(establishData)
      .onReturn(
          (TrustlyCallback { lightboxView: Trustly, returnData: Map<String, String> ->
              redirectToScreen(Callback.RETURN)
          })
      ).onCancel(
          (TrustlyCallback { lightboxView: Trustly, cancelData: Map<String, String> ->
              redirectToScreen(Callback.CANCEL)
          })
      )

Although there are different methods available to process cancellations or successful authorizations, your application should retrieve some of the data provided in the onReturn callback and pass it to your server.

Retrieve the URL Scheme and Add an OAuth Transition Handler

Retrieve the URL scheme and close the Chrome Custom Tabs. For example:

class RedirectActivity : AppCompatActivity() {

    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()
}
```

Next Steps

If you need help with your integration, contact your Trustly representative or send your request to [email protected].