Getting started with Android SDK

  Before proceeding, please ensure you have met all requirements
Click here to open this information in a new tab

  Our GitLab repository includes an example app that demonstrates how to integrate our payment SDK into your application. Our examples are predominantly written in Kotlin, but examples in Java are also provided. Click here to view.


The Trust Payments Android SDK allows you to seamlessly integrate a prebuilt or custom UI in your app to accept card payments & comply with the Strong Customer Authentication (SCA) mandate.

Use this integration if you need a pre-built “Drop-In” UI that supports the following features:

  • Card payments
  • Tokenization payments
  • Customisation of UI components to fit with your business branding
  • Locale and custom translations

Otherwise if you have already built your own payment checkout views in your Android app, but need a method to process payments to the Trust Payments gateway, you can use our Payment Transaction Manager API.

  Click here to learn more.




1. Install the SDK in your app


To embed the Mobile SDK into your project, you will need to use Gradle, a build automation tool that offers dependency management features:



Make sure Maven Central is on the list of repositories in your project-level build.gradle file:

allprojects {
repositories {

To integrate the Mobile SDK, add the following dependencies to your app-level build.gradle file:

 You will need to refer to the following resources and include the latest package version numbers in the placeholders below:
//Trust Payments SDK core dependency
implementation<latest Maven package version number>
//Optional UI module providing ready-to-use "drop-in" view
implementation<latest Maven package version number>




2. Initialise the Android SDK in your app


Configure the instance

Before you can perform any payment request, an instance of PaymentTransactionManager is needed. To instantiate it, you will need to provide application context and to set the username and gateway. You also need to provide a value for isCardinalLive flag (when set to true, all 3-D Secure-related operations will be targeted to the 3-D Secure live environment, otherwise the staging environment will be used). The parameter, cardinalStyleManager, is optional and allows for providing UI customization setup for 3-D Secure views. isLocationDataConsentGiven parameter will indicate to the SDK if your app received consent from the customer to capture their device location as part of your app privacy policy. Please find example PaymentTransactionManager constructor usage below:

context = applicationContext,
gatewayType = TrustPaymentsGatewayType.EU,
isCardinalLive = false,
merchantUsername = usernameFromTrustPayments,
cardinalStyleManager = null,
isLocationDataConsentGiven = false

As of v2.7.10.1 of the Android SDK, we have introduced an additional parameter to the SDKs PaymentTransactionManager class called isLocationDataConsentGiven. By default, isLocationDataConsentGiven is set to false, meaning the customer has not agreed to your app privacy policy that requests consent to capture the device location data. The information required for the privacy policy to be displayed to the customer can be found here.

To reduce the likelihood of your customers being challenged by the card issuer for further authentication, you should ensure to complete the following:

  1. Once your customer has agreed to your app privacy policy, which includes location data, the consent to your app privacy policy must be passed to the Trust Payments SDK PaymentTransactionManager instance by setting isLocationDataConsentGiven as true. 

  2. Request that GPS can be enabled if currently disabled by the app customer.
  3. Create a location consent prompt when your app is creating an instance of the PaymentTransactionManager class. You will need to include permissions in the manifest file:
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    If permission to access the device location is granted to your app by the customer, then the SDK will attempt to capture the device location. For best practices to generate the device location consent prompt, please refer to Google's official best practices:

For an example of how to present the privacy policy to customers in your app for customer acceptance, you can reference our sample application class PrivacyPolicyActivity.kt 

For an example of how to present the location consent prompt to customers in your app, you can reference our sample application BaseActivity and refer to checkLocationPermission() for displaying the location request prompt.


Inflate the Drop-In Payment View

To inflate our default Drop-In Payment View, you will need to add it to an appropriate XML file:

<?xml version="1.0" encoding="utf-8"?>
<ScrollView xmlns:android=""

android:padding="20dp" />

Then, an activity related to this layout has to implement the required listener interface and override its methods that are provided for this Drop-In Payment View. Those methods will provide all of the necessary data to correctly initialize the PaymentTransactonManager instance and process a transaction.


class SampleActivity : AppCompatActivity(R.layout.activity_sample),
DropInPaymentView.DropInPaymentViewListener {

private var paymentSession: PaymentSession

private val paymentTransactionManager =
context = this,
gatewayType = TrustPaymentsGatewayType.EU,
isCardinalLive = false,
merchantUsername = BuildConfig.MERCHANT_USERNAME
cardinalStyleManager = null,
isLocationDataConsentGiven = false

override fun onCreate(savedInstanceState: Bundle?) {
dropInPaymentView.dropInPaymentViewListener = this
paymentSession = paymentTransactionManager.createSession({jwtToken})

// notify about the payment form data changes (PAN, Expiry Date, CVV)
override fun onInputValid(paymentInputType: PaymentInputType, input: String) {
when (paymentInputType) {
PaymentInputType.PAN -> paymentSession.cardPan = input
PaymentInputType.ExpiryDate -> paymentSession.cardExpiryDate = input
PaymentInputType.CVV -> paymentSession.cardSecurityCode = input

// notify about the Pay Button click event
override fun onPayButtonClicked() {
val result: PaymentSessionResponse =
// process the result

  When calling the createSession method, you are required to provide a JSON Web Token (JWT). The payload of this token contains the payment request details. To learn how to construct the JWT, click here to open more info in a new tab.


Payment Transaction Manager

If you already have or intend to build your own payment checkout views in your Android app, but need a method to process payments to the Trust Payments gateway, you can use our Payment Transaction Manager API.

  You can review our example app in the GitLab repository for examples on how to configure the Payment Transaction Manager.

val paymentTransactionManager =
context = applicationContext,
gatewayType = TrustPaymentsGatewayType.EU,
isCardinalLive = false,
merchantUsername = usernameFromTrustpayments,
cardinalStyleManager = null,
isLocationDataConsentGiven = false

paymentTransactionManager.executeSession(paymentSession, activity, activityResultProvider)

When calling the paymentTransactionManager.executeSession method and also specifying THREEDQUERY in the JWT payload requesttypedescriptions field list, you must ensure to pass executeSession with parameters activityProvider and activityResultProvider.

The activityProvider is a callback to an Activity. The Activity would be the window in your Android app and this needs to be known to our payment SDK to successfully display the 3-D Secure version 2 native challenge window to your customers.

activityResultProvider will be needed to ensure the result of the 3-D Secure version 1 webview challenge window is returned to the Activity specified in activityProvider.

In our Gitlab repository we have various app examples and the following linked example demonstrates how you would configure a pay by card with 3-D Secure solution. Click here to open this in a new tab.

As part of this process, the payment card fields, pan, expirydate and securitycode will be captured on your custom payment form and added to the JSON Web Token (JWT) payload. To learn how to construct the JWT, click here to open more info in a new tab.

If you specify the fields pan, expirydate and securitycode inside of the JWT payload created on your merchant server, then the same JWT (including card details) provided during initialisation will be passed back in the response from the gateway inside the field jwt.

Ensure any sensitive payment credentials (pan, expirydate and securitycode) are sanitized prior to logging to your system.




3. Configure webhooks


It is strongly recommended that you configure webhooks on your Mobile SDK solution. When configured, URL notifications are sent to your system when payments are processed on your account.

  If you do not configure webhooks as explained below, you may not be notified of payments processed on your account, e.g. in cases of client-side errors that occur prior to the response being returned.

  1. Sign in to MyST.

  2. Search for your sitereference using the search box found at the top of the page.

  3. When viewing your site details, click “Rule manager“.


  4. Select the action type “URL notification” from the drop-down and your browser will be redirected.


  5. Create a new URL notification rule:
      • (A) Click “Add new condition” and specify the circumstances in which the URL notification is to be triggered following a transaction. In the Requests box displayed, ensure “AUTH” is ticked (meaning the notification is triggered following payment authorisations).
        Click here to learn more about configuring conditions.
      • (B) Click “Add new action” and specify the endpoint for the URL notification.
        Click here to learn more about URL notification actions.
      • (C) Using the drop-down boxes, assign the condition to the action and click “Create rule“.


  6. Ensure the rule is active (this is shown with a tick under the Active column). Once enabled, the rule will be applied to all payment sessions for the given sitereference, and the URL notification will be triggered whenever the condition specified is met.

    Note: All new rules should be created on your test sitereference and tested to ensure they work as expected before being added to your live sitereference.

  7. You must configure your system to respond to all URL notifications received from Trust Payments with an HTTP 200 OK response.
    For example: “HTTP/1.0 200 OK”.
    Your system must reply within 8 seconds of receiving a notification.


  Once you have completed the steps above, we recommend returning to the Getting started page to learn more about enabling add-ons, testing your solution and going live.

Click here to open the Getting started page.


Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request