Getting started with Android SDK

Features

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.

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:

Integrating SDK Artefacts as a Dependency from Maven

In your app-level build.gradle file, add the following dependencies:

// Trust Payments SDK core dependency
implementation 'com.trustpayments.mobile:core:<latest_version>'

// Optional UI module providing ready-to-use "drop-in" view
implementation 'com.trustpayments.mobile:ui:<latest_version>'

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

In your root-level build.gradle file, add the following dependency to get the Cardinal SDK.

allprojects {
  repositories {
    google()
    ...
    maven {
      url "https://gitlab.com/api/v4/projects/56100229/packages/maven"
      name "GitLab"
      credentials(HttpHeaderCredentials) {
        name = "Private-Token"
        value = <gitlab_token>
      }
      authentication {
        header(HttpHeaderAuthentication)
      }
    }
  }
}

Integrating SDK to your project using the source code

If you wish to integrate the source code of the SDK into your project, please include both the Core and UI modules.

// Trust Payments SDK core dependency
implementation project(":core")

// Optional UI module providing ready-to-use "drop-in" view
implementation project(":ui")

In your root-level build.gradle file, add the following dependency to get the Cardinal SDK.

allprojects {
  repositories {
    google()
    ...
    maven {
      url "https://gitlab.com/api/v4/projects/56100229/packages/maven"
      name "GitLab"
      credentials(HttpHeaderCredentials) {
        name = "Private-Token"
        value = <gitlab_token>
      }
      authentication {
        header(HttpHeaderAuthentication)
      }
    }
  }
}

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:

PaymentTransactionManager(
  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: https://support.google.com/googleplay/android-developer/answer/11150561

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 

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="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:fillViewport="true">

<com.trustpayments.mobile.ui.dropin.DropInPaymentView
android:id="@+id/dropInPaymentView"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:padding="20dp" />
</ScrollView>

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.

Example:

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.trustpayments.mobile.ui.dropin.DropInPaymentView
import com.trustpayments.mobile.ui.model.PaymentInputType
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import androidx.lifecycle.lifecycleScope
import com.trustpayments.mobile.core.PaymentSession
import com.trustpayments.mobile.core.services.api.TrustPaymentsGatewayType
import com.trustpayments.mobile.core.services.transaction.PaymentTransactionManager

/**
* SampleActivity demonstrates the implementation of a drop-in payment view 
* for handling payment transactions.
*/
class SampleActivity : AppCompatActivity(R.layout.activity_sample), DropInPaymentView.DropInPaymentViewListener {

  // Payment transaction manager responsible for managing payment transactions
  private val paymentTransactionManager by lazy {
    PaymentTransactionManager(
      context = this,
      gatewayType = TrustPaymentsGatewayType.EU,
      isCardinalLive = false,
      merchantUsername = "usernameFromTrustpayments",
      cardinalStyleManager = null,
      isLocationDataConsentGiven = false
    )
  }

  // Payment session for managing the payment session lifecycle
  private lateinit var paymentSession: PaymentSession

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // Set the drop-in payment view listener
    findViewById<DropInPaymentView>(R.id.dropInPaymentView).dropInPaymentViewListener = this

    // Create a payment session with JWT token obtained from the server
    paymentSession = paymentTransactionManager.createSession(getJWTToken())
  }

  /**
  * Get JWT token from the server.
  * @return JWT token string
  */
  private fun getJWTToken(): String {
    return ""
  }

  /**
  * Notify about changes in the payment form data (PAN, Expiry Date, CVV).
  * @param paymentInputType The type of payment input being updated
  * @param input The input value
  */
  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.
  * Executes the payment session in the background and processes the result.
  */
  override fun onPayButtonClicked() {
    lifecycleScope.launch {
      val result: PaymentTransactionManager.Response = withContext(Dispatchers.IO) {
        paymentTransactionManager.executeSession(paymentSession)
      }
      // Process the result
    }
  }
}
  

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.

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

paymentTransactionManager.executeSession(paymentSession, activityProvider)

When calling the paymentTransactionManager.executeSession method and also specifying THREEDQUERY in the JWT payload requesttypedescriptions field list, you must ensure to pass executeSession with parameter activityProvider. 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 challenge window to your customers.

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.

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.

1. Sign in to Portal.
   
   
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.