Android

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.

Prerequisites

• Android 5.0 (API level 21) or later
• AndroidX
• Gradle 8 or later

Authentication flow

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

Configure Gradle and Android dependencies

1. 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:

   1
   // build.gradle
   2
   dependencies {
   3
       implementation 'net.trustly:trustly-android-sdk:4.2.0'
   4
       implementation 'androidx.browser:browser:1.8.0'
   5
       implementation 'com.google.code.gson:gson:2.13.1'
   6
       // ...
   7
   }

2. Sync your project to enable the dependency changes.

3. If your app does not have internet permissions enabled, open the AndroidManifest.xml file and add the INTERNET permission:

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

4. 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:

1
package com.myapp
2
3
object EstablishData {
4
5
    fun getEstablishDataValues(): Map<String, String> {
6
        val establishDataValues: MutableMap<String, String> = HashMap()
7
        establishDataValues["accessId"] = "YOUR_ACCESS_ID"
8
        establishDataValues["merchantId"] = "YOUR_MERCHANT_ID"
9
        establishDataValues["requestSignature"] = "GENERATED_HASH"
10
        establishDataValues["description"] = "transaction description"
11
        establishDataValues["merchantReference"] = "ABCDREF"
12
        establishDataValues["currency"] = "USD"
13
        establishDataValues["amount"] = "0.00"
14
        establishDataValues["paymentType"] = "Deferred"
15
        establishDataValues["metadata.urlScheme"] = "yourapp://" // your app's deep link
16
        
17
        // establishDataValues["env"] = "sandbox"
18
        return establishDataValues
19
    }
20
}

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.

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

   1
   <androidx.constraintlayout.widget.ConstraintLayout>
   2
       <net.trustly.android.sdk.views.TrustlyView
   3
           android:id="@+id/trustlyWidgetView"
   4
           android:layout_width="match_parent"
   5
           android:layout_height="match_parent"
   6
           app:layout_constraintEnd_toEndOf="parent"
   7
           app:layout_constraintStart_toStartOf="parent"
   8
           app:layout_constraintTop_toTopOf="parent" />
   9
   10
   </androidx.constraintlayout.widget.ConstraintLayout>

2. 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:

   1
   // MainActivity.kt
   2
   val establishData = EstablishData.getEstablishDataValues().toMutableMap()
   3
   4
   val trustlyWidget = findViewById<TrustlyView>(R.id.trustlyWidgetView)
   5
   6
   trustlyWidget.selectBankWidget(establishData).onBankSelected { callback, data ->
   7
       establishData["paymentProviderId"] = data["paymentProviderId"].toString()
   8
   }

Launch the Lightbox

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

   1
   <androidx.appcompat.widget.AppCompatButton
   2
       android:id="@+id/btnConnectWithMyBank"
   3
       android:layout_width="match_parent"
   4
       android:layout_height="wrap_content"
   5
       android:text="@string/connect_my_bank"
   6
       app:layout_constraintBottom_toBottomOf="parent"
   7
       app:layout_constraintEnd_toEndOf="parent"
   8
       app:layout_constraintStart_toStartOf="parent" />

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

   1
   // MainActivity.kt
   2
   val connectTrustlyButton = findViewById<AppCompatButton>(R.id.btnConnectWithMyBank)
   3
   4
   connectTrustlyButton.setOnClickListener {
   5
       val intent = Intent(this@MainActivity, LightboxActivity::class.java)
   6
       intent.putExtra(LightboxActivity.ESTABLISH_DATA, establishData as Serializable)
   7
       startActivity(intent)
   8
   }

3. In your LightboxActivity, call establish to open the Lightbox:

   1
   class LightboxActivity : AppCompatActivity() {
   2
   3
       private lateinit var lightboxView: TrustlyView
   4
       
   5
       companion object {
   6
           const val ESTABLISH_DATA = "establish_data"
   7
       }
   8
   9
       override fun onCreate(savedInstanceState: Bundle?) {
   10
           super.onCreate(savedInstanceState)
   11
           setContentView(R.layout.activity_light_box)
   12
   13
           val establishData = intent.getSerializableExtra(ESTABLISH_DATA) as Map<String, String>
   14
           lightboxView = findViewById(R.id.lightBoxWidget)
   15
           lightboxView.establish(establishData)
   16
       }
   17
   }

4. 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:

   1
   <activity android:name=".LightboxActivity"
   2
           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:

1
lightboxView.establish(establishData)
2
    .onReturn(
3
        TrustlyCallback { lightboxView: Trustly?, returnData: Map<String, String> ->
4
            // TODO: Handle success (For example, navigate to a success screen)
5
            // redirectToScreen(Callback.RETURN) 
6
            Log.d("Trustly", "Transaction successful: $returnData")
7
        }
8
    ).onCancel(
9
        TrustlyCallback { lightboxView: Trustly?, cancelData: Map<String, String> ->
10
             // TODO: Handle cancellation (For example, show a toast or stay on current screen)
11
             // redirectToScreen(Callback.CANCEL)
12
             Log.d("Trustly", "Transaction cancelled")
13
        }
14
    )

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.

1
// LightboxActivity.kt
2
3
       override fun onCreate(savedInstanceState: Bundle?) {
4
           super.onCreate(savedInstanceState)
5
6
           val transactionDetail = getTransactionDetailFromUri(intent.data!!)
7
                   val intent = Intent(
8
               this,
9
               LightboxActivity::class.java
10
           ).apply { addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP) }
11
               .putExtra(LightboxActivity.TRANSACTION_DETAILS, transactionDetail as Serializable)
12
       startActivity(intent)
13
       finish()
14
   }
15
16
   fun getTransactionDetailFromUri(appLinkData: Uri): Map<String, String> {
17
       return mapOf(
18
           Pair("transactionId", appLinkData.getQueryParameter("transactionId")!!),
19
           Pair("transactionType", appLinkData.getQueryParameter("transactionType")!!),
20
           Pair("panel", appLinkData.getQueryParameter("panel")!!),
21
           Pair("payment.paymentType", appLinkData.getQueryParameter("payment.paymentType")!!),
22
           Pair("status", appLinkData.getQueryParameter("status")!!)
23
       )
24
   }
25
   }

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

   1
   <!-- LightboxActivity.kt -->
   2
   3
   override fun onRestart() {
   4
       super.onRestart()
   5
   6
       lightboxView.proceedToChooseAccount()
   7
   }

App Links

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

• Set up App Links
• Migrate from custom schemes