Tokenization for Android SDK

You can use our Mobile SDK to allow returning customers to process payments on your app without the need to re-enter all of their card details. Not only does this lead to faster and easier payments for your customers, your business also benefits from not needing to store sensitive card numbers (this can simplify your PCI accreditation process).

This process is called Tokenization.

Prerequisites

• Account Checks are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.
• Account Checks can only be performed for card-based payment methods.

Configuration for storing of payment credentials

Configure the JWT

You will need to ensure your JWT payload includes the following fields:

Field specification

	Field	Format	Description
	credentialsonfile	Numeric (1)	This must be set to “1”, to indicate the customer agreed for the payment credentials to be stored for future transactions. See below for further information.
	requesttypedescriptions	List	When processing a payment, submit: [“THREEDQUERY”,”AUTH”] When not processing a payment, submit: [“THREEDQUERY”,”ACCOUNTCHECK”] Click here to learn more.

{
  "payload": {
    "accounttypedescription": "ECOM",
    "baseamount": "1050",
    "credentialsonfile": "1",
    "currencyiso3a": "GBP",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "sitereference": "test_site12345",
    "termurl":"https://payments.securetrading.net/process/payments/mobilesdklistener"

  },
  "iat": 1559033849,
  "iss": "jwt.user"
}

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":1050,
    "credentialsonfile":"1",
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["THREEDQUERY","ACCOUNTCHECK"],
    "sitereference":"test_site12345",
    "termurl":"https://payments.securetrading.net/process/payments/mobilesdklistener"
  },
  "iat":1559033849,
  "iss":"jwt.user"
}

About Credentials on File

Identifying transactions as using CoF provides the following advantages:

• Increases the likelihood of transaction authorisation and settlement.
• Greater transparency and improved experience from the customer’s perspective.
• Issuers are less likely to use the absence of a security code as a reason to decline a transaction.

Handling the response

After the request has been processed, you will receive a single response JWT that contains the response to the ACCOUNTCHECK request:

• Ensure that the errorcode value returned is “0”, indicating success. (You must not store credentials if an error has occurred)
• Check the values returned in the securityresponseaddress, securityresponsepostcode and securityresponsesecuritycode fields. Click here for further information on these checks and only proceed if business requirements have been satisfied.

Following successful tokenization, you can store the transactionreference in your records. This will be needed later in order to process a new payment with the stored payment credentials. You can also store the last four digits of the maskedpan and paymenttypedescription for purposes of displaying to returning customers when they are choosing their payment method for their next purchase.

Configuration for tokenized payment

Update your payment form

For the tokenized payment, you will first need to ensure you have inflated the Drop-In Payment View into your layout:

(XML)

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

Here is an example of a Drop-In Payment View controller with only the security code field visible, in order to perform a transaction based on a saved transactionreference for payment credentials:

(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,
    isLocationDataConsentGiven = false
  )

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    dropInPaymentView.dropInPaymentViewListener = this
    dropInPaymentView.setupForTokenizedPayment(setOf(PaymentInputType.CVV), CardType.Visa)
    paymentSession = paymentTransactionManager.createSession({jwtToken})
  }

  // notify about the payment form data changes, this time we're only interested in CVV
  override fun onInputValid(paymentInputType: PaymentInputType, input: String) {
    when (paymentInputType) {
      PaymentInputType.CVV -> paymentSession.cardSecurityCode = input
    }
  }

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

Whenever the security code field is requested, it is also necessary to provide the card type (security code input length is determined based on its value).

The Drop-In Payment View can be configured to display any combination of input fields:

(Example)

PaymentInputType {
  PAN,
  ExpiryDate,
  CVV
}

Configure the JWT

In addition to the fields that are required to be submitted within the JWT (as described on this page), the payload will need to contain the parenttransactionreference field, the value of which is returned in the transactionreference field of the Account check response. It will also need to contain the field credentialsonfile with value set to “2”, in order to indicate the new transaction is using previously-stored credentials.

(Payload)

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "parenttransactionreference":"1-2-345",
    "credentialsonfile":"2",
    "termurl":"https://payments.securetrading.net/process/payments/mobilesdklistener",
    "requesttypedescriptions":["THREEDQUERY","AUTH"]
  },
  "iat":1559033849,
  "iss":"jwt.user"
}

Field specification

	Field	Format	Description
	credentialsonfile	Numeric (1)	This must be set to “2”, to indicate the new transaction is using previously-stored credentials.
	parenttransactionreference	Alphanumeric & hyphens (25)	Submit the transaction reference of the previous request from which the card details will be inherited.
	requesttypedescriptions	List	This will need to contain at least the following request types: [“THREEDQUERY”,”AUTH”] Click here to learn more.