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.

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.


  Click here to learn more.

 

             

 

1. Install the SDK in your app

Web_Developer_Flatline.png

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

 

Gradle

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

allprojects {
repositories {
mavenCentral()
...
}
...
}

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 com.trustpayments.mobile:core:<latest Maven package version number>
//Optional UI module providing ready-to-use "drop-in" view
implementation com.trustpayments.mobile:ui:<latest Maven package version number>

 

             

 

2. Initialise the Android SDK in your app

Phone_maintenance_Flatline.png

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 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 last parameter, cardinalStyleManager, is optional and allows for providing UI customization setup for 3D Secure views. Please find example PaymentTransactionManager constructor usage below:

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

 

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:

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

private var paymentSession: PaymentSession

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

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
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 =
paymentTransactionManager.executeSession(
paymentSession
)
// 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 / 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 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 =
PaymentTransactionManager(
context = applicationContext,
gatewayType = TrustPaymentsGatewayType.EU,
isCardinalLive = false,
merchantUsername = usernameFromTrustpayments
cardinalStyleManager = null
)

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

Data_and_settings_Flatline.png

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

    msdk-hook-01.png

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

    msdk-hook-02.png

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

    msdk-hook-03.png

  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.

Checklist__Flatline.png

  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