You can use our JavaScript Library 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.
This document explains how to use an AUTH or ACCOUNTCHECK request in order to store the customer’s payment credentials for Tokenization. ACCOUNTCHECK requests do not debit the customer’s bank account.
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.
In order to reduce fraud, Visa has mandated that all merchants with a Merchant Category Code (MCC) of 6012 are required to send additional fields in AUTH and ACCOUNTCHECK requests. Click here for further information.
Process overview
- 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.
- Your payment request can include the transactionreference from the customer’s previous purchase – or Account Check request – to inherit the card number and expiry date for a new purchase (we explain how to do this, below).
- 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.
- We will then process the tokenized payment. Ensure your system checks the response JWT to confirm the new payment was processed successfully.
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 AUTH or ACCOUNTCHECK request using our JavaScript Library.
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 |
|
If the credentialsonfile field has been submitted in the request and it is supported by the acquirer processing the transaction, it is returned in the response JWT.
If the parent response indicates an error occurred (errorcode is not “0”), the credential cannot be considered a stored credential, and you must not use these card details in any subsequent payments.
Payment - Tokenizing (Storing) card details - Cardholder Initiated Transaction
Include the following requesttypedescriptions within the JWT payload: [“THREEDQUERY”,”AUTH”]
- The 3-D query is processed. This authenticates the customer using 3-D Secure.
- The Authorisation is then processed. This processes a payment against the customer’s card.
Payload example:
{
"payload": {
"accounttypedescription": "ECOM",
"baseamount": "1050",
"currencyiso3a": "GBP",
"sitereference": "test_site12345",
"credentialsonfile": "1",
"requesttypedescriptions": [
"THREEDQUERY",
"AUTH"
]
},
"iat": 1559033849,
"iss": "jwt.user"
}
No Payment - Tokenizing (Storing) card details - Cardholder Initiated Transaction
Include the following requesttypedescriptions within the JWT payload: [“THREEDQUERY”,”ACCOUNTCHECK”]
- The 3-D query is processed. This authenticates the customer using 3-D Secure.
- An Account Check is then processed against the customer’s card. This checks the card submitted is valid.
Payload example:
{
"payload": {
"accounttypedescription": "ECOM",
"baseamount": "1050",
"currencyiso3a": "GBP",
"sitereference": "test_site12345",
"credentialsonfile": "1",
"requesttypedescriptions": [
"THREEDQUERY",
"ACCOUNTCHECK"
]
},
"iat": 1559033849,
"iss": "jwt.user"
}
About Credentials on File
A stored credential is information (including, but not limited to, an account number or payment token) that is stored in order to process future transactions.
The process of storing credentials for future use is known as Credentials on File (CoF).
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 your requests. You must also flag any subsequent payments that are utilising previously-stored credentials, by including the credentialsonfile field in these requests.
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 THREEDQUERY & AUTH/ACCOUNTCHECK request:
- Ensure that the errorcode value returned in AUTH/ACCOUNTCHECK response 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 AUTH/ACCOUNTCHECK 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
First, you will need to update your payment form to include the additional field fieldsToSubmit.
fieldsToSubmit requires a list containing the value “securitycode”.
Because the customer only needs to be prompted for their security code, the JavaScript will automatically hide the PAN (st-card-number) and expiry date (st-expiration-date) divs. These will not be displayed to the customer.
We have provided an example below as a reference:
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-security-code" class="st-security-code"></div>
<button type="submit" id="st-form__submit" class="st-form__submit">
Pay securely
</button>
</form>
<script src="<CDN_DOMAIN>"></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
fieldsToSubmit: ['securitycode']
});
st.Components();
})();
</script>
</body>
</html>
Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.
Configure the JWT
You will also need to ensure your JWT payload includes the following fields:
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 |
When processing a payment, submit: [“THREEDQUERY”,”AUTH”] |
Payment - Tokenized (Stored) card details - Cardholder Initiated Transaction
Include the following requesttypedescriptions within the JWT payload: [“THREEDQUERY”,”AUTH”]
- The 3-D query is processed. This authenticates the customer using 3-D Secure.
- The Authorisation is then processed. This processes a payment against the customer’s card.
Payload example:
{
"payload": {
"accounttypedescription": "ECOM",
"baseamount": "1050",
"currencyiso3a": "GBP",
"sitereference": "test_site12345",
"parenttransactionreference": "1-2-345",
"credentialsonfile": "2",
"requesttypedescriptions": [
"THREEDQUERY",
"AUTH"
]
},
"iat": 1559033849,
"iss": "jwt.user"
}
Handling the response
After the request has been processed, you will receive a single response JWT that contains the response to the THREEDQUERY & AUTH request:
- Ensure that the errorcode value returned in AUTH response is “0” indicating success.
- 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 AUTH 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.
