About Network Tokens
Network tokenisation is a new method of securely processing transactions where tokens issued by card schemes are used to facilitate payments rather than needing to send sensitive card details in requests to our gateway.
Using network tokens in this way is inherently more secure, as it means sensitive card information is exposed to fewer parties as part of the payment process. Specific network tokens can be restricted by the issuer to exclusively work with authorised shops for a limited time, meaning that even if tokens are compromised in a breach, malicious third parties will be unable to use them to complete unauthorised transactions.
How it works
- The customer enters their card details on a payment form hosted on your website.
- Using the Visa Token Service (VTS) or Mastercard Digital Enablement Service (MDES), you create a network token that represents the customer's card details.
- Using our Webservices API, your server submits a request to our payment gateway that includes the network token supplied by the card schemes.
- Trust Payments seeks authorisation from the acquiring/issuing banks and processes the transactions.
- The network token is stored securely by Trust Payments and can be used to process future transactions without needing to re-send the customer's card details.
Network tokens (token PAN and expiry date) are obtained from the Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES) by token requestors.
Before you can process transactions with network tokens, you must first register as a network token requestor with Visa and Mastercard:
Visa Mastercard (Note: These are links to external sites)
The following documentation explains how to manually submit requests with CoF network tokens using our Webservices API and assumes you have already established procedures with Visa and Mastercard to obtain the aforementioned tokens.
If you are looking for information on how to process e-commerce payments using device network tokens from Apple Pay and Google Pay digital wallets, please refer to the following articles:
Requirements
-
You must obtain the necessary PCI certification when handling sensitive cardholder data. If you are unsure, contact our Support Team for assistance.
-
You must have a process in place to use the Visa Token Service (VTS) and Mastercard Digital Enablement Service (MDES) to obtain the network tokens needed to process transactions using our payment gateway.
-
The use of network tokens necessitates the use of your own library. Our Python and PHP libraries do not support this functionality.
- All customer-initiated e-commerce transactions must use Strong Customer Authentication (SCA) as mandated by the PSD2 mandate. Submitting a valid network token authentication cryptogram (TAVV) by following the instructions below qualifies as SCA.
- Where a card issuer soft declines a customer-initiated authorisation including a valid TAVV, the merchant must either:
- Generate a new TAVV and retry, OR;
- Step up to authenticate the CoF network token using 3DS challenge flow. Learn more.
-
In order to reduce fraud, Visa has mandated that all UK-based merchants with a Merchant Category Code (MCC) of 6012 are required to send additional fields in AUTH and ACCOUNTCHECK requests. Learn more.
Request
Example
To successfully process a request, you must follow the specification below:
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"credentialsonfile":"2",
"currencyiso3a":"GBP",
"expirydate":"01/27",
"pan":"4111111111111111",
"requesttypedescriptions":["AUTH"],
"sitereference":"test_site12345",
"tavv":"insertTavvHere",
"tokenisedpayment":"1",
"tokentype":"VISATOKEN",
"walletdisplayname":"5555"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<billing>
<payment>
<amount currencycode="GBP">1050</amount>
<expirydate>01/2027</expirydate>
<pan tokenised="1" tokentype="VISATOKEN">4111111111111111</pan>
<wallet>
<displayname>5555</displayname>
</wallet>
</payment>
</billing>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<credentialsonfile>2</credentialsonfile>
<sitereference>test_site12345</sitereference>
</operation>
<threedsecure>
<tavv>insertTavvHere</tavv>
</threedsecure>
</request>
</requestblock>
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"RECUR",
"baseamount":"1050",
"credentialsonfile":"2",
"currencyiso3a":"GBP",
"expirydate":"01/27",
"pan":"4111111111111111",
"parenttransactionreference":"12-3-4567",
"requesttypedescriptions":["AUTH"],
"sitereference":"test_site12345",
"subscriptionnumber":"2",
"subscriptiontype":"RECURRING",
"tokenisedpayment":"1",
"tokentype":"VISATOKEN",
"walletdisplayname":"5555"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<billing>
<payment>
<amount currencycode="GBP">1050</amount>
<expirydate>01/2027</expirydate>
<pan tokenised="1" tokentype="VISATOKEN">4111111111111111</pan>
<wallet>
<displayname>5555</displayname>
</wallet>
</payment>
<subscription type="RECURRING">
<number>2</number>
</subscription>
</billing>
<operation>
<accounttypedescription>RECUR</accounttypedescription>
<credentialsonfile>2</credentialsonfile>
<parenttransactionreference>12-3-4567</parenttransactionreference>
<sitereference>test_site12345</sitereference>
</operation>
</request>
</requestblock>
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"credentialsonfile":"2",
"currencyiso3a":"GBP",
"expirydate":"01/27",
"initiationreason": "C",
"pan":"4111111111111111",
"parenttransactionreference":"12-3-4567",
"requesttypedescriptions":["AUTH"],
"sitereference":"test_site12345",
"tokenisedpayment":"1",
"tokentype":"VISATOKEN",
"walletdisplayname":"5555"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<billing>
<payment>
<amount currencycode="GBP">1050</amount>
<expirydate>01/2027</expirydate>
<pan tokenised="1" tokentype="VISATOKEN">4111111111111111</pan>
<wallet>
<displayname>5555</displayname>
</wallet>
</payment>
</billing>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<credentialsonfile>2</credentialsonfile>
<initiationreason>C</initiationreason>
<parenttransactionreference>12-3-4567</parenttransactionreference>
<sitereference>test_site12345</sitereference>
</operation>
</request>
</requestblock>
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"credentialsonfile":"2",
"currencyiso3a":"GBP",
"expirydate":"01/27",
"pan":"4111111111111111",
"parenttransactionreference":"12-3-4567",
"requesttypedescriptions":["REFUND"],
"sitereference":"test_site12345",
"tokenisedpayment":"1",
"tokentype":"VISATOKEN",
"walletdisplayname":"5555"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<billing>
<payment>
<amount currencycode="GBP">1050</amount>
<expirydate>01/2027</expirydate>
<pan tokenised="1" tokentype="VISATOKEN">4111111111111111</pan>
<wallet>
<displayname>5555</displayname>
</wallet>
</payment>
</billing>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<credentialsonfile>2</credentialsonfile>
<parenttransactionreference>12-3-4567</parenttransactionreference>
<sitereference>test_site12345</sitereference>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
When testing these requests, ensure you submit your test sitereference. This ensures that transactions are processed to our test bank and no money will change hands. When you go live, you will need to swap out your test site reference for your live site reference.
Click here for test card numbers you can submit in requests while testing.
When a parenttransactionreference from a successful parent "AUTH" or "ACCOUNTCHECK" is included in the request, Trust Payments will provide the required scheme reference data to Visa and Mastercard.
Please contact our Support Team if you need to include scheme reference data from another processor or process child transactions including a PAN and Expiry. Click here to learn more.
Field specification
The following fields relate to the type of request submitted:
| Field | Format | Description | |
| accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) |
The type of account to be used:
"MOTO" is not supported. |
|
| baseamount XPath: /billing/amount |
Numeric (13) | The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info) | |
| credentialsonfile XPath: /operation/credentialsonfile |
Numeric (1) | You must submit "2" to indicate the payment is being processed using previously-stored credentials. | |
| currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The currency of the transaction. Click here for a full list of available currencies. If the currency is submitted in a child request, it must be the same value as the parent transaction. |
|
| expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY | The network token expiry date. | |
| pan XPath: /billing/payment/pan |
Numeric (12-19) | The network token PAN issued by the network tokenisation service. | |
| requesttypedescriptions XPath: /@type |
Alpha (20) |
The type of request being processed:
|
|
| sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
Identifies your site on the Trust Payments system. If you do not know your site reference, please contact our Support Team. |
|
| tokenisedpayment XPath: /billing/payment/pan/@tokenised |
Numeric (1) |
Defines whether the payment is being processed with a network token. Submit "1" to indicate a network tokenised payment. |
|
| tokentype XPath: /billing/payment/pan/@tokentype |
Alphanumeric (50) |
Specify the type of token. Possible values:
|
|
| walletdisplayname XPath: /billing/payment/wallet/displayname |
Alphanumeric (255) |
Submit the last four digits of the customer’s card number (e.g. “5555”). |
|
| initiationreason XPath: /operation/initiationreason |
Char (1) |
This is required when processing a Merchant Initiated Transaction (MIT). Allows you to assign a reason for a Merchant Initiated Transaction (MIT). Do not submit when processing a Customer Initiated Transaction (CIT). Click here for further information on the different initiationreason values. |
|
| parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
Specify the transactionreference of the request where the network token was created. Key details are inherited from this request. Required when performing REFUND. Recommended for recurring transactions, Merchant-Initiated Transactions (MIT) and Customer-Initiated Transactions (CIT). For MIT and recurring transactions, submit the transactionreference of the first transaction in the sequence. |
|
| subscriptionnumber XPath: /billing/subscription/number |
Numeric (5) |
Required when processing recurring transactions. 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. 2nd transaction is “2”, 3rd 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 transactions. 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. |
|
| tavv XPath: /threedsecure/tavv |
Alphanumeric (56) |
The Visa VTS TAVV or Mastercard DSRP Cryptogram. For Customer-Initiated Transactions (CIT): Either tavv is required OR the EMV 3DS authentication information must be submitted instead as described in this article. For recurring transactions, Merchant-Initiated Transactions (MIT) or REFUND: Do not submit tavv. |
|
| authmethod XPath: /operation/authmethod |
Alpha (11) |
Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click the following links to learn more: The contents of authmethod do not affect the settlement status of the transaction. Settlement status can be controlled using settlestatus and settleduedate. Click here to learn more about the settlement process. Not applicable to REFUND. |
|
| operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. By default, this is the Web Services username included in the request. This can be overridden with a custom value by passing through this field in the request (optional). | |
| orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25)Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction. |
Your unique order reference that can be stored on the Trust Payments system.
Note: This can be updated at a later time (only if transaction is pending settlement). |
Response
The response returned mostly follows the same specification as a standard AUTH response, with additional considerations listed in the table below:
AUTH field specification Info on handling responses| Field | Format | Description | |
| tavv XPath: /threedsecure/tavv |
Alphanumeric (56) |
The Visa VTS TAVV or Mastercard DSRP Cryptogram. |
|
| tokenisedpayment XPath: /billing/payment/pan/@tokenised |
Numeric (1) |
This field is returned with value "1", indicating that the transaction was processed using a token. |
|
| tokentype XPath: /billing/payment/pan/@tokentype |
Alphanumeric (50) |
Used to identify the type of token used for this payment (e.g. "VISATOKEN"). |
|
| walletdisplayname XPath: /billing/payment/wallet/displayname |
Alphanumeric (255) |
This contains the walletdisplayname submitted in the request. |
Related articles
AUTH
Specification for processing AUTH requests using our Webservices API and interpreting the responses returned.
REFUND
Specification for processing REFUND requests using our Webservices API and interpreting the responses returned.
Recurring payments
Specification for processing a sequence of recurring transactions using our Webservices API.
Merchant Initiated Transactions (MIT)
Submit a request to process a transaction from previously-stored card details using our Webservices API.
