The Trustly Lightbox SDK for Android allows you to quickly build a bank authorization workflow in your Android app. Integrating the Select Bank Widget and/or the Trustly Lightbox provides a powerful user experience that results in bank authorization data which can be used with other Trustly APIs.

💻

Example App

Prefer running an example project? Checkout our Android Example on Github.

Set Up

Requirements

• Android 4.4 (API level 19) or above
• AndroidX
• Gradle 8 or above

Install Dependencies

📘

Legacy Versions

v3 SDKs deprecated PayWithMyBank references. If your app previously used version 2, take note and update these references to Trustly when upgrading to a v3 SDK.

Update your build.gradle file to include the latest Trustly SDK (available from Maven Central) and the AndroidX Browser Library with support for Chrome Custom Tabs to support OAuth user flows.

dependencies {
  
  implementation 'net.trustly:trustly-android-sdk:3.2.0'
  implementation 'androidx.browser:browser:1.8.0'
  …
}

[Optional] Manual Installation

Download the latest version from the Trustly Android Github repository.

Import the .aar file into your Android app's ./app/libs directory.

Update the dependencies section of your app's build.gradle file to reference the imported file:

dependencies {
  
  implementation files('libs/trustly-android-sdk-3.2.0.aar')
  implementation 'androidx.browser:browser:1.8.0'
  …
}

Remember to sync your project for the dependency changes to take effect.

📘

Required Permissions

If your app does not already have internet permissions enabled, configure it in your AndroidManifest.xml file. The Trustly Lightbox is a web-based module, therefore your application must allow internet connectivity.

<!-- AndroidManifest.xml -->

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

Configurations for OAuth Handling

In order to support OAuth login flows, the Trustly Lightbox interacts with Chrome Custom Tabs or in some cases it hands off to the users mobile banking app directly. In addition to the dependency added above, add the following intent-filter to the Activity section of your AndroidManifest.xml file. These properties allow your app to be called from external events such as a redirect from a mobile banking app.

<!-- AndroidManifest.xml -->

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

🚧

Deep Link Required

If your app does not already have a defined deep link or URL scheme, you must define one. Without it, users will not be automatically redirected to your app after logging in on a mobile banking app.

Lightbox Integration

With the configurations above in place, you are ready to integrate the Trustly Lightbox into your Android app.

👍

Checklist

1. Define Establish data with a requestSignature
2. Render the Select Bank Widget
3. Launch the Lightbox
4. Handle Callback Events

Define Establish Data with a Request Signature

As the Trustly Lightbox SDK runs on the client, requests between it and the Trustly API must be secured. Calculate a requestSignature using your Access Key from your server and fetch it from your Android app prior to rendering the Select Bank Widget or Trustly Lightbox.

See Securing Requests for more details on generating a requestSignature.

See Establish Data for more details on properties, accepted values and their behaviors.

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 developing against the sandbox environment, set the env property to sandbox. When publishing your production application, remove the env property altogether.

Display the Select Bank Widget

While it is possible to launch the Trustly Lightbox without use of the Select Bank Widget, Trustly recommends rendering the Select Bank Widget for an optimal user experience. For information on the Select Bank Widget as it relates to the Trustly Lightbox visit Displaying the Bank Widget.

On the application activity implementation of onCreate call the SDK’s selectBankWidget function to render the Select Bank Widget view.

For example, add trustlyWidgetView to your 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>

Then use the onBankSelected function to update the establishData with the user's chosen bank.

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

The Lightbox is launched by calling the establish function with the establishData defined earlier. The establish function can be called by any button in your app such as a "Checkout" or "Continue" button.

For this example we will add a “Connect with My Bank” button to our main activity:

<!-- activity_main.xml -->

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

	<androidx.appcompat.widget.AppCompatButton
	        android:id="@+id/btnConnectMyBank"
	        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>

Then use this button to open the screen that contains the Lightbox and pass the enhanced establishData to that screen.

<!-- MainActivity.kt -->

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

val connectTrustlyButton = findViewById<AppCompatButton>(R.id.btnConnectMyBank)
connectTrustlyButton.setOnClickListener {
    val intent = Intent(this@MainActivity, LightboxActivity::class.java)
    intent.putExtra(LightboxActivity.ESTABLISH_DATA, establishData as Serializable)
    startActivity(intent)
}

And finally, attach the establish function to the “Connect My Bank” button.

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

At this point, a user can select a bank from the Select Bank Widget and launch the Lightbox with the provided Establish data. In the next section we'll add handler functions to the onReturn and onCancel callback functions to complete a basic Lightbox implementation.

Handle Lightbox Callback Events

The Trustly Lightbox provides two callback functions to handle terminal user behaviors. When a user successfully creates a bank authorization, the onReturn function will be called. If the user exits the process at any time or the authorization is otherwise unsuccessful, the onCancel function will be called. Find more details regarding these functions at Handling the Redirect.

Define two functions to handle these callbacks and pass them into the onReturn and onCancel parameters of the establish method. Handling the user experience of a cancellation or a successful authorization can be done in many ways. At a minimum your application will likely need to retrieve some of the data provided in the onReturn callback and pass it to your server.

For example:

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

In this example, we have defined a redirectToScreen method which is simply another screen where we will prompt the user to take the next action depending on whether their transaction was authorized successfully or not.

OAuth Transition Handler

Finally, in order to support a smooth user experience when an OAuth login authorization is completed and the user returns to the Lightbox, add a simple override to the LightboxActivity class. For example:

<!-- LightboxActivity.kt -->

override fun onRestart() {
    super.onRestart()

    lightboxView.proceedToChooseAccount()
}

Next Steps

Additional items to consider beyond this basic Lightbox implementation are:

• Handling Errors in the Lightbox
• Customizing content strings in the Lightbox
• Branding & Experience guidance

If you'd like more help with your integration, reach out to your Trustly representative or send your request to [email protected].