Contents

Storing payment credentials for tokenization

 

You can use our Webservices API 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.

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

 


 

Prerequisites

Warning
The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.

If you are unsure, please contact our Support Team for assistance.

Padlock
All businesses within the EEA (European Economic Area) are mandated to use 3-D Secure when processing e-commerce Account Checks, as part of the PSD2 mandate.

 

To process an e-commerce Account Check that is authenticated with 3-D Secure, you will need to utilise our JavaScript Library instead of the solution described below. Click here to get started.

 

The following content should only be utilised by merchants processing Account Checks that are Mail or Telephone Order (MOTO), Merchant Initiated Transactions (MIT), or using other workflows that are exempt from the PSD2 mandate.

Status attention
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.

 

Failure to submit these fields will result in a “60025” (Invalid request) error being returned in the response. Click here for further information.

Info
  • Account Checks are only available for certain acquiring banks. Before you begin, please contact our Support Team and ensure your acquiring bank supports this functionality.
  • Account Checks can only be performed for card-based payment methods.

 


 

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 – or Account check request – 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 tokenized 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 our Webservices API.

 

Configure the ACCOUNTCHECK request

You will need to ensure your ACCOUNTCHECK request includes the following fields:

 

Field specification

  Field Format Description
credentialsonfile
XPath: /operation/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.

 

Info
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.
Warning
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.

 


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

accountcheck= {
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["ACCOUNTCHECK"],
    "sitereference": "test_site12345",
    "baseamount": "0",
    "orderreference": "My_Order_123",
    "accounttypedescription": "MOTO",
    "pan": "4111111111111111",
    "expirydate": "12/2020",
    "securitycode": "123",
    "billingpremise": "789",
    "billingpostcode": "TE45 6ST",
    "credentialsonfile": "1"
}

strequest = securetrading.Request()
strequest.update(accountcheck)
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' => '[email protected]',
'password' => 'Password1^',
);

$requestData = array(
'currencyiso3a' => 'GBP',
'requesttypedescriptions' => array('ACCOUNTCHECK'),
'sitereference' => 'test_site12345',
'baseamount' => '0',
'orderreference' => 'My_Order_123',
'accounttypedescription' => 'MOTO',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'billingpremise' => '789',
'billingpostcode' => 'TE45 6ST',
'credentialsonfile' => '1'
);

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

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["ACCOUNTCHECK"],
  "sitereference": "test_site12345",
  "baseamount": "0",
  "orderreference": "My_Order_123",
  "accounttypedescription": "MOTO",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "billingpremise": "789",
  "billingpostcode": "TE45 6ST",
  "credentialsonfile": "1"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["ACCOUNTCHECK"],"sitereference":"test_site12345","baseamount":"0","orderreference":"My_Order_123","accounttypedescription":"MOTO","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123","billingpremise":"789","billingpostcode":"TE45 6ST","credentialsonfile":"1"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="ACCOUNTCHECK">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">0</amount>
      <postcode>TE45 6ST</postcode>
      <premise>789</premise>
      <payment>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
        <expirydate>12/2020</expirydate>
      </payment>
    </billing>
    <operation>
      <accounttypedescription>MOTO</accounttypedescription>
      <sitereference>test_site12345</sitereference>
      <credentialsonfile>1</credentialsonfile>
    </operation>
  </request>
</requestblock>

 

About Credentials on File

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

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

 

Handling the response

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

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

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:

 

1. Customer-Initiated Transaction (CIT)

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.

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

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"}

 


 

2. Merchant-Initiated Transaction (MIT)

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.

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

 

Info
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.
Warning
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 = "[email protected]"
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' => '[email protected]',
  '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 [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"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":"[email protected]","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>[email protected]</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>