Android
Add the Trustly UI to native Android apps
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 Versionsv3 SDKs deprecated
PayWithMyBank
references. If your app previously used version 2, update these references toTrustly
before you update to a v3 SDK.
Example AppTo use an example project for testing and learning, see the Android Example in Github.
Prerequisites
- Android 5.0 (API level 21) or later
- 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:
<!-- AndroidManifest.xml -->
<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.xml
file:
<!-- 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 tosandbox
. When publishing your production application, remove theenv
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 of 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βsselectBankWidget
function to render the Select Bank Widget view. This example addstrustlyWidgetView
to theactivity_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 theestablishData
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:
<!-- LightboxActivity.kt -->
override fun onRestart() {
super.onRestart()
lightboxView.proceedToChooseAccount()
}
Next Steps
- Handling Errors in the Lightbox
- Customizing content strings in the Lightbox
- Branding & Experience guidance
If you need help with your integration, contact your Trustly representative or send your request toΒ [email protected].
Updated about 14 hours ago