Processing child transactions using Visa Token Service (VTS)

Visa Token Service (VTS) is a security feature provided by Visa that tokenizes the cards of customers.

Click here to learn more about VTS, and how to enable on your site reference(s).

Once enabled, you can process new AUTH requests through our Webservices API that include the tokens provided by Visa, rather than directly including sensitive card details, as described below.

Processing a transaction with a token

You are required to authenticate all VTS tokenised payments using EMV 3-D Secure (3DS).
Click here to learn more about 3DS.

A returning customer agrees to a new purchase on your site.
Your system will need to submit a new AUTH request that includes the parenttransactionreference field.
Before processing the payment, Trust Payments uses the parenttransactionreference to retrieve the customer’s unique token
Trust Payments submits a payment request to the acquiring bank, including the customer’s token.
The acquiring bank contacts Visa, who will be able to identify the customer from the token and contact their card issuer.
The card issuer will either approve or decline the transaction and returns their response to Visa.
Visa returns a response back to the acquiring bank and Trust Payments.
Trust Payments will return an AUTH response to your system. You will need to check the contents of the response to determine whether or not the transaction was successful.
Your checkout page will need to display the most relevant success / error message in the customer’s browser.

Example of AUTH request using VTS

#!/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",
  "parenttransactionreference": "1-23-45"
}

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',
  'parenttransactionreference' => '1-23-45'
);

$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",
    "parenttransactionreference": "1-23-45"
  }]
}'

{
  "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-23-45"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <billing>
      <amount currencycode="GBP">1050</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>1-23-45</parenttransactionreference>
    </operation>
  </request>
</requestblock>

Field specification

Field

Format

Description

parenttransactionreference
XPath: /operation/parenttransactionreference

Alphanumeric
& hyphens (25)

The transactionreference of the previous successfully-authorised AUTH request, processed with a Visa-branded card, from which key details will be inherited.

If the parent transaction was tokenized successfully following the original authorisation, the re-authorisation will be processed using the Visa token in place of the customer’s sensitive card details.
If the parent transaction was not tokenized successfully following the original authorisation, the re-authorisation will be processed using the customer’s sensitive card details (as with a standard non-tokenized payment).

Handling the response

There are additional fields specific to VTS returned in the response. These are shown in the example below:

{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2016-12-07 11:32:44',
u 'livestatus': u '0',
u 'issuer': u 'Test Issuer',
u 'splitfinalnumber': u '1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '23-9-80001',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '1050',
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'AUTH',
u 'securityresponsesecuritycode': u '0',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST36',
u 'errormessage': u 'Ok',
u 'operatorname': u 'webservices@example.com',
u 'securityresponsepostcode': u '0',
u 'maskedpan': u '411111######0930',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0',
u 'parenttransactionreference': u '1-23-45',
u 'tavv': u 'VVVVVVVVVVVVVVVVVVVVVVVVVVV=',
u 'tokenisedpayment': u '1',
u 'tokentype': u 'VISATOKEN',
u 'vaultreference': u '1-1',
u 'walletdisplayname': u '1111'
}]
}

array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(34) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 09:52:19"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "Test Issuer"
      ["splitfinalnumber"] => string(1) "1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["orderreference"] => string(12) "My_Order_123"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["securityresponsepostcode"] => string(1) "0"
      ["transactionreference"] => string(10) "72-9-80003"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "0"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST31"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "webservices@example.com"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######0930"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
      ["parenttransactionreference"] => string(7) "1-23-45"
      ["tavv"] => string(28) "VVVVVVVVVVVVVVVVVVVVVVVVVVV="
      ["tokenisedpayment"] => string(1) "1"
      ["tokentype"] => string(9) "VISATOKEN"
      ["vaultreference"] => string(3) "1-1"
      ["walletdisplayname"] => string(4) "1111"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "transactionstartedtimestamp":"2016-12-07 15:08:47",
    "livestatus":"0",
    "issuer":"Test Issuer",
    "splitfinalnumber":"1",
    "dccenabled":"0",
    "settleduedate":"2016-12-07",
    "errorcode":"0",
    "baseamount":"1050",
    "tid":"27882788",
    "merchantnumber":"00000000",
    "merchantcountryiso2a":"GB",
    "transactionreference":"23-9-80006",
    "merchantname":"Test Merchant",
    "paymenttypedescription":"VISA",
    "orderreference":"My_Order_123",
    "accounttypedescription":"ECOM",
    "acquirerresponsecode":"00",
    "requesttypedescription":"AUTH",
    "securityresponsesecuritycode":"0",
    "currencyiso3a":"GBP",
    "authcode":"TEST96",
    "errormessage":"Ok",
    "operatorname":"webservices@example.com",
    "securityresponsepostcode":"0",
    "maskedpan":"411111######0930",
    "securityresponseaddress":"0",
    "issuercountryiso2a":"US",
    "settlestatus":"0",
    "parenttransactionreference":"1-23-45",
    "tavv":"VVVVVVVVVVVVVVVVVVVVVVVVVVV=",
    "tokenisedpayment":"1",
    "tokentype":"VISATOKEN",
    "vaultreference":"1-1",
    "walletdisplayname":"1111"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>A3579dkvx</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <orderreference>MyOrder123</orderreference>
      <tid>27882788</tid>
      <merchantnumber>00000000</merchantnumber>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <transactionreference>23-9-80006</transactionreference>
    <security>
      <postcode>0</postcode>
      <securitycode>0</securitycode>
      <address>0</address>
    </security>
    <billing>
      <amount currencycode="GBP">1050</amount>
      <payment type="VISA">
        <vaultreference>1-1</vaultreference>
        <wallet>
          <displayname>1111</displayname>
        </wallet>
        <issuer>Test Issuer</issuer>
        <issuercountry>ZZ</issuercountry>
        <pan tokentype="VISATOKEN" tokenised="1">411111######0930</pan>
      </payment>
      <dcc enabled="0"/>
    </billing>
    <authcode>TEST96</authcode>
    <timestamp>2012-10-08 12:46:02</timestamp>
    <settlement>
      <settleduedate>2012-10-08</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <threedsecure>
      <tavv>VVVVVVVVVVVVVVVVVVVVVVVVVVV=</tavv>
    </threedsecure>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <acquirerresponsecode>00</acquirerresponsecode>
    <operation>
      <splitfinalnumber>1</splitfinalnumber>
      <parenttransactionreference>1-23-45</parenttransactionreference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </response>
  <secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>

Field specification

Field	Format	Description
parenttransactionreference XPath: /operation/parenttransactionreference	Alphanumeric & hyphens (25)	The transactionreference of a previous request, from which key details have been inherited.
tavv XPath: /threedsecure/tavv	Alphanumeric & special characters (32)	Token Authentication Verification Value
tokenisedpayment XPath: /billing/payment/pan/@tokenised	Numeric (1)	A value of “1” indicates the transaction was processed using a token. If the transaction was processed using the card details (not the token) this field will not be returned.
tokentype XPath: /billing/payment/pan/@tokentype	Alpha (50)	This should be returned with the value “VISATOKEN”, to indicate VTS was used.
vaultreference XPath:/billing/payment/vaultreference	Alphanumeric & hyphens (25)	This is a unique reference assigned by Trust Payments to identify the token.
walletdisplayname XPath:/billing/payment/wallet/displayname	Numeric (4)	This is information provided by the card issuer that can be displayed to the customer in order to identify the payment method. This typically includes the last 4 digits of their card number.

About notifications

Visa will periodically provide updates on tokens in scenarios where customers are issued new card numbers or expiry dates, or when tokens expire. URL notifications can be configured on your site reference(s) to be notified when this occurs. To configure these notifications, please contact our Support Team.

Further reading on this topic