Tokenization for Payment Pages

Michael Buckley

March 30, 2023 14:31

Click here to learn more about Account Checks.

You can use Payment Pages in conjunction with our API solutions to allow returning customers to process payments on your checkout 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).

This process is called Tokenization.

This document explains how to use an Account Check request in order to store the customer’s payment credentials for Tokenization. Account Check requests do not debit the customer’s bank account.

But if preferred, tokenization can also be performed on previous Authorisation requests, in which the customer has been charged, providing the requirements specified by the Credentials on File mandate have been met. To do this, you will need the transactionreference of the payment that you would like to repeat, then skip ahead to the Configuration for tokenized payment section of this document, found below.

Pre-requisites

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.
This document assumes your system is able to submit an API request to our gateway and handle the response returned. This is required for the tokenized payment.

You can also process the tokenized payment manually using MyST, by performing a re-authorisation. Click here for further information.

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.

In order to use Tokenization to process recurring payments or subscriptions, your merchant ID must be capable of processing recurring or continuous authority payments. If in doubt, we strongly recommend contacting your bank for clarification.

Process overview

The customer processes an Account Check through our hosted Payment Pages solution. Every Account Check processed can be identified by their transactionreference, a unique identifier assigned by Trust Payments. The customer is not debited as part of this step. For each new customer that performs an Account Check, you will need to ensure your own system keeps a record of the transactionreference returned in the URL notification.
When the returning customer is ready to perform a payment, your system can process an AUTH request using our API, ensuring this new request includes the correct transactionreference to reference their stored payment details.
If the customer is initiating the transaction (CIT), we recommend that you configure your checkout to prompt the customer 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 returned to confirm the new payment was processed successfully.

Apple Pay does not support tokenization in this manner.

Configuration for storing of payment credentials

First, you will need to configure the Payment Pages solution to perform an Account Check, without processing the payment.

To enable this behaviour, you will need to contact our Support Team and request the following changes to your account:

Account Checks needs to be enabled on your site reference(s).
Enhanced Post to be enabled on these site reference(s).
Update URL notification submitted to your system also include fields securityresponseaddress, securityresponsepostcode and securityresponsesecuritycode.

Once your account has been updated as described above, you will now need to configure your POST to Trust Payments to include the following additional 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.
mainamount	Numeric (14)	This will be displayed to the customer on the hosted Payment Pages checkout. Providing the requesttypedescriptions is submitted as “ACCOUNTCHECK”, the customer will not be debited. Caution: This amount is stored in our records. When performing the tokenized payment, if a new amount is not submitted, the value posted here will be used instead. (Can be submitted with value “0”)
requesttypedescriptions	Alpha (20)	This must be set to “ACCOUNTCHECK”.
subscriptionnumber	Numeric (5)	Required when you are planning on processing recurring payments at regular intervals. Submit “1”. In each subsequent child request, the number submitted must be incremented by 1. For example the second request is “2”, the third is “3”, etc.
subscriptionfinalnumber	Numeric (5)	Required when you are planning on processing recurring payments at regular intervals, under conditions described below. This is used to set the number of payments to be processed over the course of the subscription. Note: This field is required for certain acquiring banks on the US platform when the subscriptiontype is “INSTALLMENT” (otherwise the field is optional). Contact our Support Team for further information.
subscriptiontype	Alpha (11)	Required when you are planning on processing recurring payments at regular intervals. This is the type of subscription: “RECURRING” is for when the customer is making a recurring payment for a new product/service each time. “INSTALLMENT” is for when a customer is purchasing a single order over several installments. Installments 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. Note: If the subscription type is “INSTALLMENT” and you are processing payments on the US platform, certain acquiring banks also require the field subscriptionfinalnumber is submitted. Contact our Support Team for further information.

Example:

<html>
  <head>
  </head>
  <body>
    <!--YOUR HTML-->
    <form method="POST" action="<DOMAIN>/process/payments/choice">
      <input type="hidden" name="sitereference" value="test_site12345">
      <input type="hidden" name="stprofile" value="default">
      <input type="hidden" name="currencyiso3a" value="USD">
      <input type="hidden" name="mainamount" value="100.00">
      <input type="hidden" name="version" value="2">
      <input type="hidden" name="orderreference" value="myorder12345">
      <input type="hidden" name="sitesecurity" value="hee879a9ab97753b3a768925d50842f10e19fea03fef0b820026b6df92d415866">
      <input type="hidden" name="sitesecuritytimestamp" value="2019-05-28 14:22:37">
      <input type="hidden" name="requesttypedescriptions" value="ACCOUNTCHECK">
      <input type="hidden" name="credentialsonfile" value="1">
      <input type="submit" value="Pay">
    </form>
  </body>
</html>

Replace <DOMAIN> with a supported domain. Click here for a full list.

If the 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.

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 need to check the URL notification received by your system 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 tokenised payment

Once your system is able to process Account Checks and store the associated transactionreference values for later retrieval, you can configure the tokenized payment. The configuration required depends on the party that is initiating the transaction:

Customer-Initiated Transaction (CIT) - Ecommerce (ECOM)

If the tokenized payment is initiated by the customer (e.g. by clicking “Pay” on your website), the transaction must be authenticated with 3-D Secure. To do this, you will need to utilise our JavaScript Library.

You must process customer-initiated tokenized payments with our JavaScript Library, as this supports the latest 3-D Secure version 2 specification, whereas our Webservices API only supports 3-D Secure version 1.

If you are unfamiliar with our JavaScript Library, click here to learn more.

To achieve this, the tokenized payment request will need to perform at least the following request types:

THREEDQUERY – This performs the 3-D Secure authentication.
AUTH – This processes the payment.

To learn more about additional requests that can be performed, click here.

In the request, you will need to ensure the following additional fields are submitted within the JWT payload:

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	To process a 3-D Secure authenticated payment, your server must submit at least [“THREEDQUERY”,”AUTH”].

Example payload for processing tokenized payment (JavaScript Library):

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "credentialsonfile":"2",
    "parenttransactionreference":"1-2-345"
  },
  "iat":1559033849,
  "iss":"jwt.user"
}

Click here for the full specification of the JWT payload.

Merchant-Initiated Transaction (MIT) (e.g. recurring payments)

If the tokenized payment is initiated by your own server with the customer not present, you will need to submit an AUTH request using our API.

You can also process the tokenized payment manually using MyST, by performing a re-authorisation. Click here for further information.

When using our JavaScript Library, you will need to ensure your JWT payload includes the fields shown in the table below.
When using our Webservices API, you will need to ensure your AUTH request includes the fields shown in the table below.

Field	Format	Description
credentialsonfile XPath: /operation/credentialsonfile	Numeric (1)	This must be set to “2”, to indicate the new transaction is using previously-stored credentials.
initiationreason XPath: /operation/initiationreason	Char (1)	It is mandated you provide a reason for processing the tokenized payment. Submit one of the following values that best describes the reason for payment: “A” – Re-authorisation “C” – Unscheduled payment “D” – Delayed Charges “S” – Resubmission “X” – No-show (for a hotel booking) Click here for further information on the different initiationreason values.
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	Submit the transaction reference of the previous request from which the card details will be inherited.
requesttypedescriptions XPath: /@type	List	Your server must submit at least [“AUTH”] in the requesttypedescriptions list. Note: Because this transaction is Merchant-Initiated, 3-D Secure authentication is not possible.
subscriptionnumber XPath: /billing/subscription/number	Numeric (5)	Required when processing recurring payments at regular intervals. This is used to identify a payment’s position within a sequence of recurring transactions. For each subsequent payment, the number submitted should be incremented by 1 (without gaps). e.g. 2^nd transaction is “2”, 3^rd is “3”, then “4” etc. (You should only increment this number if the previous recurring payment request was successful) We do not impose limits on the number of payments made against a card.
subscriptiontype XPath: /billing/subscription/@type	Alpha (11)	Required when processing recurring payments at regular intervals. This is the type of subscription: “RECURRING” is for when the customer is making a recurring payment for a new product/service each time. “INSTALLMENT” is for when a customer is purchasing a single order over several installments (only supported by certain acquirers; contact our Support Team for further information).

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.

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.

Request examples:

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "credentialsonfile":"2",
    "initiationreason":"S",
    "parenttransactionreference":"1-2-345",
    "requesttypedescriptions":["AUTH"]
  },
  "iat":1559033849,
  "iss":"jwt.user"
}

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "credentialsonfile": "2",
  "initiationreason": "S",
  "parenttransactionreference": "1-2-345"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'credentialsonfile' => '2',
  'initiationreason' => 'S',
  'parenttransactionreference' => '1-2-345'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias":"webservices@example.com",
  "version": "1.00",
  "request": [{
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "orderreference": "My_Order_123",
    "accounttypedescription": "ECOM",
    "credentialsonfile": "2",
    "initiationreason": "S",
    "parenttransactionreference": "1-2-345"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "baseamount":"1050",
    "orderreference":"My_Order_123",
    "accounttypedescription":"ECOM",
    "parenttransactionreference":"1-2-345",
    "initiationreason":"S",
    "credentialsonfile":"2"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <payment>
        <expirydate>12/2020</expirydate>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
      </payment>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>1-2-345</parenttransactionreference>
      <initiationreason>S</initiationreason>
      <credentialsonfile>2</credentialsonfile>
    </operation>
  </request>
</requestblock>

Pre-requisites

Process overview

Configuration for storing of payment credentials

Field specification

About Credentials on File

Handling the response

Configuration for tokenised payment

Articles in this section