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.

Set Up

Requirements

Installation

Download the latest Trustly Android SDK: v2.2.1
Import the .aar file into your Android app's ./app/libs directory.

📘
PayWithMyBank references
Future versions beyond 3.x may deprecate PayWithMyBank references. For current and previous versions, these references will be supported.

Gradle Setup

Update your build.gradle file to include the Trustly SDK and the AndroidX Browser Library with support for Chrome Custom Tabs (more on that in the next step).

dependencies {
  
  implementation files('libs/paywithmybank-android-sdk-2.2.1.aar')
  implementation 'androidx.browser:browser:1.4.0'
  …
}

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

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

Define Establish data with a requestSignature

Render the Select Bank Widget

Launch the Lightbox

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

	<com.paywithmybank.android.sdk.views.PayWithMyBankView
        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<PayWithMyBankView>(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: PayWithMyBankView

    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(
          (PayWithMyBankCallback { lightboxView: PayWithMyBank, returnData: Map<String, String> ->
              redirectToScreen(Callback.RETURN)
          })
      ).onCancel(
          (PayWithMyBankCallback { lightboxView: PayWithMyBank, 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:

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

Android (Legacy)

Set Up

Requirements

Installation

📘
PayWithMyBank references

Gradle Setup

Configurations for OAuth Handling

🚧
Deep Link Required

Lightbox Integration

👍
Checklist

Define Establish Data with a Request Signature

Display the Select Bank Widget

Launch the Lightbox

Handle Lightbox Callback Events

OAuth Transition Handler

Next Steps

Set Up

Requirements

Installation

📘PayWithMyBank references

Gradle Setup

Configurations for OAuth Handling

🚧Deep Link Required

Lightbox Integration

👍Checklist

Define Establish Data with a Request Signature

Display the Select Bank Widget

Launch the Lightbox

Handle Lightbox Callback Events

OAuth Transition Handler

Next Steps

📘
PayWithMyBank references

🚧
Deep Link Required

👍
Checklist