Contents

Tokenization

 

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

Warning
Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use, and that these must be flagged at the time of the first authorisation, by submitting the credentialsonfile field in the payload of your request.

 


 

Process overview

1
Every transaction can be identified by their transactionreference, a unique identifier assigned by Trust Payments. When a new customer orders from your app, you will need to ensure your own system keeps a record of the transactionreference returned.
2
Your payment request can include the transactionreference from the customer’s previous purchase to inherit the card number and expiry date for a new purchase (we explain how to do this, below).
3
The customer will be prompted to enter the security code that is normally found on the back of their card (because we are unable to store this value on our records for security reasons). The customer will need to enter this in order for additional security checks to be performed by the card issuer.
4
We will then process the transaction, which in all other regards will follow the same process as a standard payment. Ensure your system checks the response JWT to confirm the new payment was processed successfully.
PAYMENT Apple Pay
Apple Pay does not support tokenization in this manner.

 


 

Configuration for storing of payment credentials

In order to store the customer’s payment credentials on the Trust Payments system and acquire a reference for use in future purchases, your system can process an Account check using the payment transaction manager or drop-in view controller. The following example is how to set up the drop-in view controller:


let dropInViewController = try ViewControllerFactory.shared.dropInViewController(jwt: jwt, typeDescriptions: [.accountCheck], payButtonTappedClosureBeforeTransaction: { controller in
    controller.continue() 
}, successfulPaymentCompletion: { _, _, _, cardReference: TPCardReference in 

    // in success closure you can save the returned card reference, here is an example of storing reference in UserDefaults in our demo application

    Wallet.shared.add(card: cardReference)
}, transactionFailure: { _, _, _, _ in })

/// This is the definition of the TPCardReference class:
///
/// Represents a transaction and card details used for that transaction.
///
/// Can be used for future payments without the need to provide all card details.
///
/// Pass `transactionReference` property as `parenttransactionreference` in the JWT payload to perform transaction based on parent's card details.
/// - warning: `transactionReference` will be nil when `credentialsonfile` will not be set.
///
/// Use `maskedPan` property to show to the end user what card will be used alongside with brand logo. You can get the logo from Card module:
/// ```
///CardType.cardType(for: `cardType`).logo
///```
@objc public class TPCardReference: NSObject, Codable {
    @objc public let transactionReference: String?
    @objc public let cardType: String
    @objc public let maskedPan: String
}

 

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 field credentialsonfile with value set to “1”, in order to indicate the customer agreed for the payment credentials to be stored for future transactions.


{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","credentialsonfile":"1"},"iat":1559033849,"iss":"jwt.user"}

 

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.

 


 

Configuration for tokenized payment

As described in the above example where we define the TPCardReference class, in order to perform transactions using the transactionreference, when generating the JWT payload, the property with the transactionreference must be passed (parenttransactionreference: cardReference.transactionReference).

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

let visibleFields = CardType.cardType(for: cardReference.cardType) == .amex ? [DropInViewVisibleFields.cvv4] : [.cvv3]

let dropInViewController = try ViewControllerFactory.shared.dropInViewController(jwt: jwt, typeDescriptions: [.threeDQuery, .auth], visibleFields: visibleFields, payButtonTappedClosureBeforeTransaction: { controller in 
    controller.continue() 
}, successfulPaymentCompletion: { _, _, _, _ in }, transactionFailure: { _, _, _, _ in })

 

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 field credentialsonfile with value set to “2”, in order to indicate the new transaction is using previously-stored credentials.


{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","parenttransactionreference":"10-20-34","credentialsonfile":"2"},"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.