Contents

Re-authorisation using Visa Token Service (VTS)

 

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

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

  1. A returning customer agrees to a new purchase on your site.
  2. Your system will need to submit a new AUTH request that includes the parenttransactionreference field.
  3. Before processing the payment, Trust Payments uses the parenttransactionreference to retrieve the customer’s unique token
  4. Trust Payments submits a payment request to the acquiring bank, including the customer’s token.
  5. The acquiring bank contacts Visa, who will be able to identify the customer from the token and contact their card issuer.
  6. The card issuer will either approve or decline the transaction and returns their response to Visa.
  7. Visa returns a response back to the acquiring bank and Trust Payments.
  8. 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.
  9. 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 = "[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",
  "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' => '[email protected]',
  '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 [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",
  "parenttransactionreference": "1-23-45"
}]}'
{"alias":"[email protected]","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>[email protected]</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 'response': [{
      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 '[email protected]',
        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"
  ["response"] => 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) "[email protected]"
      ["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":"[email protected]","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>[email protected]</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: /billing/amount
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.