Contents

Account checks

 

An ACCOUNTCHECK request allows a card to be validated by checking the cardholder’s first line of address, the cardholder’s postcode and the security code, to ensure the details entered by the customer are valid. Click here to learn more about the checks performed.

 

Requirements

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

 

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

 

Update your payment form

You can update your payment form to instruct our JavaScript library to process an Account check prior to performing a standard transaction. This is done by specifying custom requestTypes, as shown in the example below:


<html>
<head>
</head>
<body>
  <div id="st-notification-frame"></div>
  <form id="st-form" action="https://www.example.com" method="POST">
    <div id="st-card-number" class="st-card-number"></div>
    <div id="st-expiration-date" class="st-expiration-date"></div>
    <div id="st-security-code" class="st-security-code"></div>
    <button type="submit" id="st-form__submit" class="st-form__submit">
      Pay securely
    </button>
  </form>
 <script src=<DOMAIN>/js/v2/st.js></script>
 <script> 
  (function() {
   var st = SecureTrading({  
    jwt: 'INSERT YOUR JWT HERE'
    });  
   st.Components({"requestTypes":["ACCOUNTCHECK","THREEDQUERY","AUTH"]}); 
  })(); 
 </script>
</body>
</html>

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

 

Account checks (API)

 

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.

Info
If you are already processing e-commerce payments using our JavaScript Library, your existing solution can be updated to also submit Account Check requests with minimal changes to the mark-up. Click here to learn more.

 


 

An ACCOUNTCHECK request allows a card to be validated by checking the cardholder’s first line of address, the cardholder’s postcode and the security code, to ensure the details entered by the customer are valid.

 

Process overview

    1. Merchant submits ACCOUNTCHECK request.
    2. Trust Payments validates the request and contacts the bank.
    3. The acquiring bank will contact the card issuer to perform AVS and security code checks.
    4. Trust Payments receives results of the request and passes this back to the merchant.
    5. Merchant receives and interprets this response.

 

Warning
No funds are reserved by ACCOUNTCHECK requests

The customer’s account is not debited when an ACCOUNTCHECK request is performed.

Info
Similar to standard AUTH requests, AVS and Security Code Checks are performed on ACCOUNTCHECK requests. We recommend reading our documentation on these checks before proceeding.

 

Requirements

      • 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.
Info
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” errorcode being returned in the response.

Click here for further information.

 

ACCOUNTCHECK request

The fields required in an ACCOUNTCHECK request are the same as a standard AUTH request. The difference is that the baseamount can be “0”. You can also submit any field that you can submit in an AUTH request and these will be inherited by any subsequent child requests.

 

The following is an example of an ACCOUNTCHECK request:


#!/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": "ECOM",
    "pan": "4111111111111111",
    "expirydate": "12/2020",
    "securitycode": "123",
    "billingpremise": "789",
    "billingpostcode": "TE45 6ST"
}

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' => 'ECOM',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'billingpremise' => '789',
'billingpostcode' => 'TE45 6ST'
);

$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": "ECOM",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "billingpremise": "789",
  "billingpostcode": "TE45 6ST"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["ACCOUNTCHECK"],"sitereference":"test_site12345","baseamount":"0","orderreference":"My_Order_123","accounttypedescription":"ECOM","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123","billingpremise":"789","billingpostcode":"TE45 6ST"}]}
<?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>ECOM</accounttypedescription>
      <sitereference>test_site12345</sitereference>
    </operation>
  </request>
</requestblock>

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

 

ACCOUNTCHECK response

The ACCOUNTCHECK response has the same structure as a standard AUTH response, except for the requesttypedescription value returned being “ACCOUNTCHECK”.

Inheritance

 

It is possible to take the value of the transactionreference field returned in the ACCOUNTCHECK response and submit this in the parenttransactionreference field of a new request, such as an AUTH. The new request will inherit billing and delivery details from the ACCOUNTCHECK (including the card details required for the payment), which means you are not required to submit this information again.

Info
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.

{
  u 'requestreference': u 'Ar2xj1hjr',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 16:12:00',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        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-80023',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '0',
        u 'accounttypedescription': u 'ECOM',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'ACCOUNTCHECK',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST46',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '2',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '2',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A4cenptwx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(27) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:04:29"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["baseamount"] => string(1) "0"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["securityresponsepostcode"] => string(1) "2"
      ["transactionreference"] => string(10) "72-9-80018"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["orderreference"] => string(12) "My_Order_123"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(12) "ACCOUNTCHECK"
      ["securityresponsesecuritycode"] => string(1)"2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST39"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["securityresponseaddress"] => string(1) "2"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-q3wa45ge","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:16:39","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"0","tid":"27882788","merchantnumber":"00000000","securityresponsepostcode":"2","transactionreference":"23-9-80024","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"ACCOUNTCHECK","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST53","errormessage":"Ok","operatorname":"[email protected]","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"2","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"NunVEQ"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>X575647667</requestreference>
  <response type="ACCOUNTCHECK">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <orderreference>My_Order_123</orderreference>
      <tid>27882788</tid>
      <merchantnumber>00000000</merchantnumber>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>16-9-1</transactionreference>
    <billing>
      <amount currencycode="GBP">0</amount>
      <payment type="VISA">
        <issuer>SecureTrading Test Issuer1</issuer>
        <issuercountry>US</issuercountry>
        <pan>411111######1111</pan>
      </payment>
      <dcc enabled="0"/>
    </billing>
    <authcode>TEST53</authcode>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <timestamp>2013-01-16 10:48:17</timestamp>
    <acquirerresponsecode>00</acquirerresponsecode>
    <security>
      <address>2</address>
      <postcode>2</postcode>
      <securitycode>2</securitycode>
    </security>
    <settlement>
      <settleduedate>2013-01-16</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </response>
  <secrand>bByuPvGz9Hcm</secrand>
</responseblock>

 

The results of account checks are returned in the securityresponseaddress, securityresponsepostcode and securityresponsesecuritycode fields. The specification of these fields are outlined in the table below.

Warning
It is strongly recommended that you check the security fields returned in the response, and manually investigate transactions where the returned securityresponsesecuritycode is “4” (indicating the customer entered a security code that doesn’t match the value found on the back of the card).
Field Format Description
securityresponseaddress
XPath: /security/address
Numeric (1) “0” Not given – Your system did not provide the acquiring bank the information required to perform this check.

“1” Not checked – The acquiring bank did not perform this check on the information you provided in the request.

“2” Matched – The information you provided in the request matches the information obtained by the acquiring bank, from the customer’s payment issuer.

“4” Not matched – The information you provided in the request does not match the information obtained by the acquiring bank, from the customer’s payment issuer.

securityresponsepostcode
XPath: /security/postcode
Numeric (1)
securityresponsesecuritycode
XPath: /security/securitycode
Numeric (1)

 

Payouts

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.

 

Payouts are similar to standard refunds, except they can be performed independently of other transactions. The benefits of performing payouts include:

Info
Payouts are also known as Credit Fund Transfers (CFT) or Original Credit Transfers (OCT).
Info
Payouts processed with Visa Direct are processed online, with the customer’s account typically being credited within 30 minutes.

 

Please contact your account manager to check if you are eligible to enable Visa Direct on your account.

 

Requirements

You will need to have a CFT Merchant Number associated with your Trust Payments account. If you are unsure if your merchant number supports this, we recommend contacting your bank for clarification. Additionally, please ensure you are following any guidelines outlined by your bank before proceeding.

 

Payout request

Using parent transaction

The following is an example of such a request:

Warning
Ensure the submitted accounttypedescription is “CFT”, otherwise a regular REFUND will be processed instead of a payout.

#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
payout= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "accounttypedescription": "CFT",
  "parenttransactionreference": "1-2-345678"
}
  
strequest = securetrading.Request()
strequest.update(payout)
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(
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'test_site12345',
'accounttypedescription' => 'CFT',
'parenttransactionreference' => '1-2-345678'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "accounttypedescription": "CFT",
  "parenttransactionreference": "1-2-345678"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","accounttypedescription":"CFT","parenttransactionreference":"1-2-345678"}]}
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>CFT</accounttypedescription>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 

Without parent

As an alternative to the above, you can also submit a payout request without reference to a parent transaction. In this scenario, you will instead need to submit the customer’s payment details in the payout request. Please see the following example:


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
payout= {
        "requesttypedescriptions": ["REFUND"],
        "sitereference": "test_site12345",
        "accounttypedescription": "CFT",
        "baseamount": "1050",
        "currencyiso3a": "GBP",
        "pan": "4111111111111111",
        "expirydate": "12/2020",
        "securitycode": "123"
}
  
strequest = securetrading.Request()
strequest.update(payout)
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(
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'test_site12345',
'accounttypedescription' => 'CFT',
'baseamount' => '1050',
'currencyiso3a' => 'GBP',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "accounttypedescription": "CFT",
  "baseamount": "1050",
  "currencyiso3a": "GBP",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","accounttypedescription":"CFT","baseamount":"1050","currencyiso3a":"GBP","pan":"4111111111111111","expirydate":"12\/2020","securitycode":"123"}]}
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <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>CFT</accounttypedescription>
    </operation>
  </request>
</requestblock>

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

 

Field specification

Info
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.

 

Field Format Description
accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Must be “CFT”.
baseamount
XPath: /billing/amount
Numeric (13) The refund amount in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”.

(Max length of amount may vary depending on your acquiring bank – Contact your bank for further info)

currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) The currency that the transaction will be processed in.

Click here for a full list of available currencies.

expirydate
XPath: /billing/payment/expirydate
Date MM/YYYY If you would like to process a refund with an updated expiry date, the new value is submitted in this field.
orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (255)
Your unique order reference that can be stored on Trust Payments’s system.

If this is not submitted, it is inherited from the parent AUTH request, provided a parenttransactionreference has been included.

pan
XPath: /billing/payment/pan
Numeric (12-19) This is the long number printed on the front of the customer’s card.

We return a masked version of this PAN in the response, in the field maskedpan. e.g. “411111######1111”

parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
You can submit the transaction reference of the AUTH request that you would like to refund.
requesttypedescriptions
XPath: /@type
Alphanumeric
& hyphens (25)
The request type required is “REFUND”.
securitycode
XPath: /security/securitycode
Numeric (3-4) This is the three digit security code printed on the back of the card.

(For AMEX cards, this is a 4 digit code found on the front of the card)

We strongly recommend submitting this value for the processing of security code checks.

Additionally, some banks may decline the payment if the security code is not present.

sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
A unique reference that identifies your account. You receive this when you first sign up with us.

 

Payout response

The response returned has the same structure as a standard REFUND, except that the accounttypedescription returned is “CFT”:


{
  u 'requestreference': u 'Agv3epv31',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 15:44:33',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'orderreference': u 'My_Order_123',
        u 'tid': u '27880001',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1050',
        u 'accounttypedescription': u 'CFT',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'REFUND',
        u 'securityresponsesecuritycode': u '0',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST REFUND ACCEPTED',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A19beknpr"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(28) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 10:21:13"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["orderreference"] => string(12) "My_Order_123"
      ["tid"] => string(8) "27880001"
      ["merchantnumber"] => string(8) "00000000"
      ["securityresponsepostcode"] => string(1) "0"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["accounttypedescription"] => string(3) "CFT"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(6) "REFUND"
      ["securityresponsesecuritycode"] => string(1) "0"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(20) "TEST REFUND ACCEPTED"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-qc7t4h8a","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:50:37","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1050","tid":"27880001","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"CFT","acquirerresponsecode":"00","requesttypedescription":"REFUND","securityresponsesecuritycode":"0","currencyiso3a":"GBP","authcode":"TEST REFUND ACCEPTED","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"0V2j6j0kl2R1UU"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>X1u3u92dg</requestreference>
  <response type="REFUND">
    <merchant>
      <tid>27880001</tid>
      <merchantnumber>00000000</merchantnumber>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <merchantname>Test Merchant</merchantname>
      <orderreference>My_Order_123</orderreference>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>1-2-345679</transactionreference>
    <billing>
      <amount currencycode="GBP">1050</amount>
      <payment type="VISA">
        <pan>411111######1111</pan>
        <issuercountry>US</issuercountry>
        <issuer>SecureTrading Test Issuer1</issuer>
      </payment>
      <dcc enabled="0"/>
    </billing>
    <timestamp>2019-12-17 11:16:05</timestamp>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <acquirerresponsecode>00</acquirerresponsecode>
    <live>0</live>
    <authcode>TEST REFUND ACCEPTED</authcode>
    <operation>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
      <accounttypedescription>CFT</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2019-12-17</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <security>
      <address>0</address>
      <postcode>0</postcode>
      <securitycode>0</securitycode>
    </security>
  </response>
  <secrand>V1utOQ5A</secrand>
</responseblock>

 

Refunds

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.

 

After processing a payment, it is possible to pay the customer back by submitting a REFUND request. This page will walk you through the process.

 

Process overview

  1. Merchant submits REFUND request.
  2. Trust Payments validates the request and contacts the bank.
  3. Trust Payments processes the refund with the relevant acquirer.
  4. Trust Payments receives results of the request and passes this back to the merchant.
  5. Merchant receives and interprets this response.

 

Requirements

 

REFUND request

Full refund

The following example REFUND request performs a full refund on the specified AUTH:


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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(
  'requesttypedescriptions' => array('REFUND'),
  'sitereference' => 'test_site12345',
  'parenttransactionreference' => '1-2-345678'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678"}]}
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 

Full refund with updated expiry date

The following example REFUND request performs a full refund on the specified AUTH, using a new card expiry date. The new expiry date is submitted in the expirydate field.


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "expirydate": "05/2025"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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(
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678',
'expirydate' => '05/2025'
);

$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": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "expirydate": "05/2025"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","expirydate":"05\/2025"}]}
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <payment>
        <expirydate>05/2025</expirydate>
      </payment>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 

Partial refund

The following example REFUND request performs a partial refund on the specified AUTH. You can specify the amount to be refunded in the baseamount field.


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
refund= {
  "requesttypedescriptions": ["REFUND"],
   "sitereference": "test_site12345",
   "parenttransactionreference": "1-2-345678",
   "baseamount": "2001"
}
  
strequest = securetrading.Request()
strequest.update(refund)
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(
'requesttypedescriptions' => array('REFUND'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678',
'baseamount' => '2001'
);

$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": "2001",
"request": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "baseamount": "200"
}]}'
{"alias":"[email protected]","version":"2001","request":[{"requesttypedescriptions":["REFUND"],"sitereference":"test_site12345","parenttransactionreference":"1-2-345678","baseamount":"200"}]}
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="REFUND">
    <billing>
      <amount>200</amount>
    </billing>
    <operation>
      <sitereference>test_site12345</sitereference>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
    </operation>
  </request>
</requestblock>

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

 

Field specification

Info
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.

 

Field Format Description
baseamount
XPath: /billing/amount
Numeric (13) The refund amount in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”.

This amount cannot be greater than the final amount settled into your bank account.

You can opt to perform a partial refund by submitting a lower amount here.

If this field is not present, the full amount of the transaction will be refunded. (Max length of amount may vary depending on your acquiring bank – Contact your bank for further info)

chargedescription
XPath: /merchant/chargedescription
Alphanumeric including
symbols (25)
This is a description of the payment that appears on the customer’s bank statement.

Only supported by certain acquiring banks.

Specification of this field will depend on your acquiring bank. For further information, please contact our Support Team.

Valid characters:

  • Uppercase/lowercase A-Z
  • Numbers 0-9
  • Spaces
  • Punctuation: + – _ . @ ( )
expirydate
XPath: /billing/payment/expirydate
Date MM/YYYY If you would like to process a refund with an updated expiry date, the new value is submitted in this field.
orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (255)
Your unique order reference that can be stored on the Trust Payments system.

If this is not submitted, it is inherited from the parent AUTH request.

parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
This field must contain the transaction reference of the AUTH request that you would like to refund.
requesttypedescriptions
XPath: /@type
Alpha (20) The request type required is “REFUND”.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
A unique reference that identifies your account. You receive this when you first sign up with us.

The site reference submitted in the REFUND request must be the same as the site reference used to process the parent AUTH request.

 

REFUND response


{
  u 'requestreference': u 'Ak70u1ujh',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 15:14:00',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        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 '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '2001',
        u 'accounttypedescription': u 'ECOM',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'REFUND',
        u 'securityresponsesecuritycode': u '0',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST REFUND ACCEPTED',
        u 'errormessage': u 'Ok',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'operatorname': u '[email protected]',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "Acdefhwxy"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(28) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 10:06:13"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["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) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "2001"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(6) "REFUND"
      ["securityresponsesecuritycode"] => string(1) "0"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(20) "TEST REFUND ACCEPTED"
      ["errormessage"] => string(2) "Ok"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["operatorname"] => string(23) "[email protected]"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-22rd4301","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:31:48","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"2001","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"REFUND","securityresponsesecuritycode":"0","currencyiso3a":"GBP","authcode":"TEST REFUND ACCEPTED","errormessage":"Ok","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","operatorname":"[email protected]","settlestatus":"0"}],"secrand":"SNQVg"}
<responseblock version="3.67">
  <requestreference>Xk3mvyk5v</requestreference>
  <response type="REFUND">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <orderreference>My_Order_123</orderreference>
      <tid>27882788</tid>
      <merchantnumber>00000000</merchantnumber>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>1-2-345679</transactionreference>
    <billing>
      <amount currencycode="GBP">2001</amount>
      <payment type="VISA">
        <issuer>SecureTrading Test Issuer1</issuer>
        <issuercountry>US</issuercountry>
        <pan>411111######1111</pan>
      </payment>
      <dcc enabled="0"/>
    </billing>
    <authcode>TEST REFUND ACCEPTED</authcode>
    <live>0</live>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <timestamp>2012-10-08 12:46:11</timestamp>
    <acquirerresponsecode>00</acquirerresponsecode>
    <security>
      <address>0</address>
      <postcode>0</postcode>
      <securitycode>0</securitycode>
    </security>
    <settlement>
      <settleduedate>2012-10-08</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <operation>
      <parenttransactionreference>1-2-345678</parenttransactionreference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
  </response>
  <secrand>f</secrand>
</responseblock>

The specification of the REFUND response is the same as the standard AUTH response, except the requesttypedescription field has value “REFUND”. You will need to check the fields returned are correct. In particular, ensure the errorcode is “0” (indicating the request was processed successfully) and that the settlestatus is NOT “2” or “3” (indicating funds will not settle).

 


 

Additional resources

3-D Secure (version 1)

 

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.

 

The following documentation explains how to manually perform 3-D Secure using version 1 through our Webservices API.

The process described below only supports 3-D Secure version 1.
We recommend all merchants utilise 3-D Secure version 2 by using our JavaScript Library.

If you are already processing e-commerce payments using our JavaScript Library, you do not need to follow the process described below, as the JavaScript Library will handle the 3-D Secure process automatically.

 


 

3-D Secure is a protocol designed to reduce fraud and chargebacks during e-commerce transactions. It allows Mastercard and Visa card issuers to provide an extra level of protection, by authenticating the customer’s identity at the point of sale, sometimes by prompting for a previously-agreed PIN and/or password.

Info
For a fully authenticated 3-D Secure transaction, in the event of a dispute at a later date the card issuer will usually take responsibility of the chargeback instead of the merchant. The liability issues involved with 3-D Secure transactions can be found in this FAQ.
.

 

Process overview

1
Check customer enrolment

  • Your system will need to send a THREEDQUERY request using our Webservices API (including the customer’s card details) and interpret the response returned.
  • Trust Payments will check whether the customer’s card is enrolled in 3-D Secure.
2
Authenticate the customer

If the customer is enrolled in 3-D Secure, your system will need to redirect the customer to the card issuer’s server (ACS URL) and handle the customer being redirected to your server (Term URL).

3
Authorisation

Your system will need to send an AUTH request using our Webservices API and interpret the response returned.

 


 

1. Check customer enrolment

To determine whether or not the customer’s card is enrolled in the 3-D Secure scheme, you need to manually submit a THREEDQUERY request using our Webservices API.

 

THREEDQUERY Request

The following example demonstrates how to structure a THREEDQUERY request:


#!/usr/bin/python
import securetrading

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

threedquery= {
  "termurl":"https://termurl.com",
  "accept":"text/html,*/*",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "currencyiso3a":"GBP",
  "requesttypedescriptions": ["THREEDQUERY"],
  "accounttypedescription":"ECOM",
  "sitereference": "test_site12345",
  "baseamount": "1050"
}

strequest = securetrading.Request()
strequest.update(threedquery)
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(
  'termurl' => 'https://termurl.com',
  'accept' => 'text/html,*/*',
  'pan' => '4111111111111111',
  'expirydate' => '12/2020',
  'securitycode' => '123',
  'currencyiso3a' => 'GBP',
  'requesttypedescriptions' => array('THREEDQUERY'),
  'accounttypedescription' => 'ECOM',
  'sitereference' => 'test_site12345',
  'baseamount' => '1050'
);

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "termurl":"https://termurl.com",
  "accept":"text/html,*/*",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123",
  "currencyiso3a":"GBP",
  "requesttypedescriptions": ["THREEDQUERY"],
  "accounttypedescription":"ECOM",
  "sitereference": "test_site12345",
  "baseamount": "1050"
}]}'

 

Here is the specification of the fields included in the THREEDQUERY request described above:

Info
When reading the field specifications included on this page, please ensure that you reference the relevant code examples for your chosen language.

 

Key

Field name Type Length Request Description
accept Alphanumeric 1024 The exact content of the HTTP accept-header field as received from the cardholder’s user agent.
accounttypedescription Alpha 20 This must be submitted as “ECOM” (e-commerce).
baseamount 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)
currencyiso3a Alpha 3 The currency that the transaction will be processed in.

Click here for a full list of available currencies.

expirydate Date MM/YYYY 7 The expiration date printed on the card.
pan
Numeric 12-19 This is the long number printed on the front of the customer’s card.

We return a masked version of this PAN in the response, in the field maskedpan. e.g. “411111######1111”

requesttypedescriptions Alpha 20 The request type required is “THREEDQUERY”.
securitycode
Numeric 3-4 This is the three digit security code printed on the back of the card.
(For AMEX cards, this is a 4 digit code found on the front of the card)This field is not strictly required field by Trust Payments, but it is highly recommended for the processing of security code checks.Additionally, some banks may decline the payment if the security code is not present.
sitereference Alphanumeric including
underscore
50 The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.
termurl URL 1024

More info

  This field value is a URL of a script/file located on your system that is able to manage customers who are returned to your system. It is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS.
useragent Alphanumeric 255 The exact content of the HTTP user-agent header field as received from the cardholder’s user agent. We strongly recommend you submit this field, as failure to do so may forfeit the liability shift.

 

THREEDQUERY Response

This section documents how to interpret a THREEDQUERY response, which is used to indicate whether or not the customer’s card is enrolled in the card issuer’s 3-D Secure scheme.

Info
The acsurl, md and pareq fields are only returned in a THREEDQUERY response for enrolled cards.

 

The example below demonstrates the structure of a THREEDQUERY response, indicating that the customer’s card is enrolled in a 3-D Secure scheme:


{
  u 'requestreference': u 'Aw5mpjtv6',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 16:55:47',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'xid': u 'amh1OCtINGpuemJaVmQreU5YT2Y=',
        u 'pareq': u 'eJxVUmFPw9C12xiQowlCopiIqGji5Yqj25lPCwOutoQKHZzxqOQgF5soqzk=',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'threedversion': u '1.0.2',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345678',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'acsurl': u 'https://webapp.securetrading.net/acs/visa.cgi',
        u 'accounttypedescription': u 'ECOM',
        u 'requesttypedescription': u 'THREEDQUERY',
        u 'md': u 'UEZOVVBqeE5SRDQ4VFVSSVBucE9abUp5WWtTlDR0NLaFVSZUV5aStFPQ==',
        u 'maskedpan': u '411111######0211',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'enrolled': u 'Y',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A2cjnruwy"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(25) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:25:36"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["xid"] => string(28) "ZlcyU1hQcUhmaEtzd2I1SmkrMnM="
      ["pareq"] => string(27) "eJxVUstuwjAQ/BXEHZxjoOrXA=="
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["threedversion"] => string(5) "1.0.2"
      ["tid"] => string(8) 27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["transactionreference"] => string(10) "1-2-345678"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["acsurl"] => string(45) "https://webapp.securetrading.net/acs/visa.cgi"
      ["accounttypedescription"] => string(4) "ECOM"
      ["requesttypedescription"] => string(11) "THREEDQUERY"
      ["md"] => string(72) "UEZOVVBqeVQand2VTFRKzptZGY2RXZXOGQrS2V5Tko5cEk9"
      ["maskedpan"] => string(16) "411111######0211"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["enrolled"] => string(1) "Y"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-08yvq0db","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 16:57:44","livestatus":"0","issuer":"SecureTrading Test Issuer1","xid":"KzRLRmhSUEZ0OWZJSkJIMDU1dDk=","pareq":"eJxVUu9PwjAQ\/NtY9ts6tP8Ac1Rqq+","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","threedversion":"1.0.2","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345678","merchantname":"Test Merchant","paymenttypedescription":"VISA","acsurl":"https:\/\/webapp.securetrading.net\/acs\/visa.cgi","accounttypedescription":"ECOM","requesttypedescription":"THREEDQUERY","md":"UEZOVVBqeE5SRD06bWRzS1dBbnFZY01JRjEwZGOWhrPQ==","maskedpan":"411111######0211","errormessage":"Ok","operatorname":"[email protected]","enrolled":"Y","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"0gqEPDTnCWlvTr6G"}

Info
The md and pareq typically contain values far longer than displayed in the example above and therefore have been abbreviated, for your convenience.

 

Check the error code field value

If the errorcode value returned in the response is not ‘0’, an error has occurred. If an errorcode other than ‘0’ is returned, please consult the table below and attempt to resolve the issue:

Error code Description
0 Request was successful.
30000 Invalid field.
60031 The THREEDQUERY request used a payment type that is not supported by Trust Payments 3-D Secure.
other Other errors will require further investigation. Click here for a full list of possible error codes.

 

If you were unable to resolve the issue, you can instruct your system to perform a standard AUTH without using 3-D Secure.

Warning
When performing an AUTH request without 3-D Secure, this will result in forfeiting the liability shift.

 

Check the enrolled field value

If the enrolled value returned in the response is “Y”, the customer’s card is enrolled in 3-D secure. Please refer to the following table for enrolled values:

Enrolled Description Action
Y The card is enrolled in the card issuer’s 3-D Secure scheme. Send the customer to the card issuer’s Access Control Server (ACS). The URL for the ACS is provided in the acsurl of the THREEDQUERY response.
N The card is not enrolled in the card issuer’s 3-D Secure scheme. Perform an AUTH Request, including the transactionreference returned in the THREEDQUERY response (example can be found below).
U The card’s enrolment in the card issuer’s 3-D Secure scheme could not be determined. This typically indicates a temporary problem with the card issuer’s systems. You can configure your system to resubmit the same THREEDQUERY request. If this continues to fail, submit a standard AUTH request using our Webservices API, including the transactionreference returned in the THREEDQUERY response.

 

Here is the specification of the fields included in the THREEDQUERY response described above:

 

Key

Field name Type Length Response Description
requesttypedescription Alpha 20 “THREEDQUERY” is always returned in the response.
xid Alphanumeric 255 The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments).
enrolled Char 1 Determines if the cardholder is enrolled in a 3-D Secure scheme.

  • “Y” – Card is enrolled.
  • “N” – Card is not enrolled.
  • “U” – Unable to determine if card is enrolled.
pareq Alphanumeric including symbols 2048 The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments).
md Alphanumeric including symbols 1024 Returned if card is enrolled.

The unique 3-D Secure reference for this transaction.

acsurl URL 1024 Returned if card is enrolled.

The URL of the Access Control Server (ACS) to be used in authenticating the cardholder.

threedversion Numeric 6 Only returned for accounts with certain acquiring banks.

The version of the 3-D Secure protocol.

 


 

Your progress

Following the instructions above, your system should now be able to determine whether or not a customer’s card is enrolled in a 3-D Secure scheme. If the customer’s card is enrolled, follow the “Authenticate the customer” section below, otherwise skip ahead to the “Authorisation” section.

 


 

2. Authenticate the customer

 

Info
Only attempt to authenticate the customer if their card is confirmed to be enrolled in a 3-D Secure scheme.

 

If the card is not enrolled, skip ahead to the “Authorisation” section.

 

If the customer is enrolled in the card issuer’s 3-D Secure scheme, your system must send the customer’s browser to the card issuer-hosted Access Control Server (ACS) using an HTTPS POST. The URL for the ACS can be found in the acsurl field of the THREEDQUERY response.

On the ACS, the customer will be authenticated, sometimes by prompting for a previously-agreed PIN and/or password. The browser must send data from the termurl, pareq and md in HTML fields ‘TermUrl’, ‘PaReq’ and ‘MD’, respectively (These field names are case sensitive).

 

URL
The size of the ACS page displayed in the customer’s browser is controlled by the ACS provider (cannot be modified by merchants or Trust Payments). As a guideline, Visa and Mastercard both state that the Verified by Visa authentication window should be 390×400 pixels in size

 

Following authentication, the customer will be returned to your servers using an HTTPS POST. You will need to parse this response, as it will contain the ‘PaRes’ and ‘MD’ fields, for constructing the subsequent AUTH Request needed to process the payment.

 

Warning
When the customer’s browser is redirected to your server from the ACS, please be aware that some ACS will also include a field called “realPan”, which contains the customer’s card number in plain text. It is imperative that you do not store the value of realPan on your own server.

 

The following is an example of how to redirect the cardholder to the card issuer’s ACS :


<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01//EN'>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
<title>Processing payment</title>
<style type="text/css">
  h3,h3,h4 { font-family: verdana, arial, sans-serif;
          font-weight: normal;}
  #logo {float: left;}
</style>
</head>
<body OnLoad="document.form.submit();" >
<form name="form" id="form" action="$acsurl" method="POST">
<div>
<input type="hidden" name="PaReq" value="$pareq" />
<input type="hidden" name="TermUrl" value="$termurl" />
<input type="hidden" name="MD" value="$md" />
</div>
<noscript>
<div>
<h3>JavaScript is currently disabled or is not supported by your browser.</h3>
<h4>Please click Submit to continue processing your 3-D Secure transaction.</h4>
<input type="submit" value="Submit">
</div>
</noscript>
</form>
</body>
</html>

 

Referencing 3-D Secure transactions

In most circumstances, your system will need to store data about the transaction in your database while the customer is being authenticated on the card issuer’s ACS, to be retrieved when the customer returns to your system via the termurl. As the 3-D Secure specification requires that only the md and pares fields are returned to your system, it is recommended that the md field is used to look up any corresponding customer session to complete the transaction.

 

Waiting for the customer to return from the ACS

Your system will need to consider the length of time it may take for the customer to enter their details on the card issuer’s ACS. The time the customer will spend on the ACS will depend on a number of factors. Longer wait times may occur when the customer is signing up to a 3-D Secure scheme for the first time, or recovering a forgotten password. While your system needs to allow time for the customer to return, it is entirely possible for the customer to close their browser on the card issuer’s ACS and not return at all. There are no specific regulations as to how long your system must wait for the customer to be redirected from the ACS to your Term URL, but we recommend waiting for no more than two hours.

 

 


Your progress

Following the instructions above, your system should now be able to redirect the browsers of customers with cards enrolled in a 3-D Secure scheme to the ACS for authentication. Your system can now proceed and submit an AUTH request using our Webservices API to process the payment, by following the instructions below.

 


 

3. Authorisation

3-D authorisations are used to seek authorisation for authenticated transactions from your acquiring bank. This is performed by manually submitting an AUTH Request using our Webservices API and interpreting the response returned.

 

AUTH Request

For enrolled cards only

The following example demonstrates how to structure a 3-D AUTH request when the card is enrolled in a 3-D Secure scheme:


#!/usr/bin/python
import securetrading

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

auth= {
  "requesttypedescriptions": ["AUTH"],
  "md":"UEZOVVBqeE5SRDQ4VFVSSVBrRjVXSGhOZFZReVUzVlalBVeE",
  "pares":"eJzVWFmzosgSfudXdPQ8Gt1sbkzYRhQ7KCjI/sYOsimgoL/+lp7Tp5"
}

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(
'requesttypedescriptions' => array('AUTH'),
'md' => 'UEZOVVBqeE5SRDQ4VFVSSVBtSllOVTlMYVdaUlJXWnZVRTA0UVdwVlJXZFpRo5cEk9',
'pares' => 'eJztWEnTqsi2nfMrKqqGxik6UajwJFCOxLb5BNvgHdPneIihB/fq2eNv777/BdaScGg='
);

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["AUTH"],
  "md":"UEZOVVBqeE5SRDVS1FLVG9aenQrRGhaNk1NPQ==",
  "pares":"eJztWMmyq7iynfMVFVVDxyk6Y0OX0U1wTQ=="
}]}'

Info
The md and pares fields typically contain values far longer than displayed in the example above and therefore have been abbreviated for your convenience. When submitting these fields, your system must submit their full values, unmodified.

 

For non-enrolled cards only

For cards that are NOT enrolled in the card issuer’s 3-D Secure scheme (or have unknown enrolment), you will need to submit the following fields in order to inherit transaction information needed to perform the authorisation:


#!/usr/bin/python
import securetrading

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

auth= {
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678"
}

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(
'requesttypedescriptions' => array('AUTH'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678'
);

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

?>
curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["AUTH"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678"
}]}'

Inheritance

 

The example AUTH requests shown above (both enrolled and not-enrolled) contain all the fields that are required for submission. All other information required to seek authorisation will be inherited from the previous THREEDQUERY request stored on our system.

 

We allow the submission of additional fields in the AUTH request that have not been submitted in the THREEDQUERY request (e.g. the customer name, if omitted in the query).

 

Click here for a full list of fields that can be submitted in an AUTH request.

 

Here is the specification of the fields included in the AUTH requests described above:

 

Key

Field name Type Length Request Description
pares Alphanumeric including symbols 1024 Only send if card is enrolled.

Must be the value returned in the pares field of the HTTPS POST from the card issuer’s ACS, otherwise this may forfeit the liability shift.

md Alphanumeric including symbols 65536 Only send if card is enrolled.

The unique 3-D Secure reference for this transaction. Supplied if enrolled is “Y”

parenttransactionreference Alphanumeric including hyphens 25 Only send if card is NOT enrolled.

Unique reference of the parent THREEDQUERY request.

sitereference Alphanumeric including underscore 50 Only send if card is NOT enrolled.

The site reference processing the transaction.

 

AUTH Response

The data returned in the AUTH response will depend on both the card enrollment status,  and whether or not the customer was successfully authenticated on the card issuer’s ACS.

Your system should be able to interpret the response data in each of the following scenarios.

 

Enrolled and authenticated


{
  u 'requestreference': u 'Av87m7xq9',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-08 08:34:48',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'xid': u 'amh1OCtINGpuemJaVmQreU5YT2Y=',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'cavv': u 'Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'status': u 'Y',
        u 'transactionreference': u '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1050',
        u 'eci': u '05',
        u 'accounttypedescription': u 'ECOM',
        u 'tid': u '27882788',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST40',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'maskedpan': u '411111######0211',
        u 'securityresponsepostcode': u '0',
        u 'enrolled': u 'Y',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A278afgrx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(33) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:46:34"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["splitfinalnumber"] => string(1) "1"
      ["xid"] => string(28) "ZlcyU1hQcUhmaEtzd2I1SmkrMnM="
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["status"] => string(1) "Y"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["enrolled"] => string(1) "Y"
      ["eci"] => string(2) "05"
      ["accounttypedescription"] => string(4) "ECOM"
      ["cavv"] => string(28) "Q0FWVkNBVlZDQVZWQ0FWVkNBVlY="
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST30"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["securityresponsepostcode"] => string(1) "0"
      ["maskedpan"] => string(16) "411111######0211"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-n68rw97k","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:21:59","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","xid":"ZldiREFPMW5HYi90UDhxMDJTV2Q=","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","status":"Y","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"1050","enrolled":"Y","eci":"05","accounttypedescription":"ECOM","cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST05","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######0211","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"bsZP"}

 

Enrolled but NOT authenticated


{
  u 'requestreference': u 'Aq2qmp0j3',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-13 11:11:58',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-13',
        u 'errorcode': u '60022',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'status': u 'N',
        u 'transactionreference': u '1-2-345679',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1050',
        u 'accounttypedescription': u 'ECOM',
        u 'requesttypedescription': u 'AUTH',
        u 'currencyiso3a': u 'GBP',
        u 'maskedpan': u '411111######0211',
        u 'errormessage': u 'Unauthenticated',
        u 'operatorname': u '[email protected]',
        u 'enrolled': u 'Y',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '3'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A35ahjnwx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(25) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-13 10:41:57"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["splitfinalnumber"] => string(1) "1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-13"
      ["errorcode"] => string(5) "60022"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["status"] => string(1) "N"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(3) "1050"
      ["accounttypedescription"] => string(4) "ECOM"
      ["requesttypedescription"] => string(4) "AUTH"
      ["currencyiso3a"] => string(3) "GBP"
      ["maskedpan"] => string(16) "411111######0211"
      ["errormessage"] => string(15) "Unauthenticated"
      ["operatorname"] => string(23) "[email protected]"
      ["enrolled"] => string(1) "Y"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "3"
    }
  }
}
{
  "requestreference": "W23-mjuwx1f5",
  "version": "1.00",
  "response": [{
    "transactionstartedtimestamp": "2016-12-13 11:00:44",
    "parenttransactionreference": "1-2-345678",
    "livestatus": "0",
    "issuer": "SecureTrading Test Issuer1",
    "splitfinalnumber": "1",
    "dccenabled": "0",
    "settleduedate": "2016-12-13",
    "errorcode": "60022",
    "tid": "27882788",
    "merchantnumber": "00000000",
    "merchantcountryiso2a": "GB",
    "status": "N",
    "transactionreference": "1-2-345679",
    "merchantname": "Test Merchant",
    "paymenttypedescription": "VISA",
    "baseamount": "1050",
    "accounttypedescription": "ECOM",
    "requesttypedescription": "AUTH",
    "currencyiso3a": "GBP",
    "maskedpan": "411111######0211",
    "errormessage": "Unauthenticated",
    "operatorname": "[email protected]",
    "enrolled": "Y",
    "issuercountryiso2a": "US",
    "settlestatus": "3"
  }],
  "secrand": "3J"

 

Not enrolled


{
  u 'requestreference': u 'Adyw3fdbw',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 16:47:39',
        u 'parenttransactionreference': u '1-2-345678',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345679',
        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 '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST23',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'maskedpan': u '411111######0021',
        u 'securityresponsepostcode': u '0',
        u 'enrolled': u 'N',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A256agnuw"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(29) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 11:53:36"
      ["parenttransactionreference"] => string(10) "1-2-345678"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["splitfinalnumber"] => string(1) "1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["transactionreference"] => string(10) "1-2-345679"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["enrolled"] => string(1) "N"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST08"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["securityresponsepostcode"] => string(1) "0"
      ["maskedpan"] => string(16) "411111######0021"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}
{"requestreference":"W23-fwpp74eu","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:24:51","parenttransactionreference":"1-2-345678","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345679","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"1050","enrolled":"N","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST42","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######0021","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"O3L"}

 

Managing authorisation response

Your system will need to interpret the AUTH response in order to determine if the transaction was successful. The most important field to check in the response is the errorcode.

Error code Description
0 Cardholder was successfully authenticated on the card issuer’s ACS.
Customer’s bank authorised the transaction.
Funds will be transferred.
70000 Cardholder was successfully authenticated on the card issuer’s ACS.
Customer’s bank declined the transaction.
Funds will NOT be transferred.
60022 Cardholder was NOT successfully authenticated on the card issuer’s ACS.
Trust Payments did not contact the acquiring bank to seek authorisation.
Funds will NOT be transferred.
99999 An error code of ‘99999’ indicates an unknown error occurred, which requires manual inspection.
We recommend contacting our Support Team for assistance, providing a copy of the entire request submitted and the response returned.
In the interest of security, ensure you omit or mask sensitive field values, such as card details.
other Click here for a full list of error codes used by Trust Payments.

 

Regardless of the errorcode returned in the response, we strongly recommend that you refer to our best practices and configure your system to perform all of the checks outlined.

 

Here is the specification of the fields that are included in the AUTH responses described above, which are specific to 3-D Secure:

Info
Please note that other fields that can be returned are documented on our page covering AUTH requests.

 

Key

Field name Type Length Response Description
enrolled Char 1 Indicates if the cardholder is enrolled in a 3-D Secure scheme:

  • “Y” – Card is enrolled.
  • “N” – Card is not enrolled.
  • “U” – Unable to determine if card is enrolled.
xid Alphanumeric 255 The unique identifier for the transaction, assigned by the MPI (Merchant Plug-In) (in this case, Trust Payments).
status Char 1 Returned if card is enrolled.

Indicates whether or not the customer was authenticated on the card issuer’s ACS:

  • “Y” – Customer authenticated.
  • “N” – Customer not authenticated.
  • “A” – An authentication attempt occurred but could not be completed.
  • “U” – Unable to perform authentication.
cavv Alphanumeric 32 Returned if card is enrolled and authenticated.

The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction, provided by the card issuer.

eci Alphanumeric 2 Returned if card is enrolled and authenticated.

The ECI (E-Commerce Indicator) security level associated with the transaction.

 

Info
The above fields may be requested by a card issuer in the event of a disputed transaction and are included in the response for your reference.

 

Testing

We recommend that you thoroughly test your solution before processing live payments.
Click here for test card details that you can submit when testing.

 

AVS and security code checks

The Address Verification System and security code checks provide you with a further level of security to a transaction, allowing additional checks regarding the validity of the address and security code information supplied by the customer.

 

Introduction to AVS

A customer’s address is checked against the address that the card issuer holds for that card. The issuing bank will indicate to the acquiring bank whether there is a match between the entered address and the registered card address. The checks performed are focused on the house number and postcode provided by the customer.

 

Introduction to security code checks

The security code is a three or four digit number printed on credit and debit cards. It is not stored by Trust Payments, and also must never be stored by merchants.

Disabled
It is imperative that you never store the customer’s security code.
Please ensure that no log files or databases contain the security code information on your system.

The number is often printed on the back of the card, on the signature strip.

back of card

Alternatively, on American Express cards the security code can be found on the front of the card, on the right–hand side, above the embossed card number.
front of card

The security code that the customer has entered is checked against the security code that the card issuer holds for their card. The issuing bank will indicate to the acquiring bank whether there is a match between the entered security code and the correct security code associated with the card.

 

Process overview

Here is how the AVS and security code checks fit into the standard payment process:

1
The customer agrees to a payment on your website and you submit an AUTH request to Trust Payments. The address and card details are passed on to your bank.
2
Your bank will then contact the customer’s bank to check whether the details entered by the customer matches the details held on their records.
3
These results are returned to Trust Payments, which assigns response codes and returns this information to you in the AUTH response.

Depending on your account configuration, Trust Payments may perform certain actions on the transaction if the results of the AVS and security code checks do not meet a required standard. This behaviour is configured as part of your security policy (scroll down for further information on the security policy).

Info
Some acquirers will use the results of the AVS or security code checks to decline the transaction, if either the address or security code entered by the customer is incorrect. Others will authorise the transaction and allow you to decide whether or not to continue with the transaction.

 

Requirements

 

Supported cards and banks

The availability of the AVS and security code check facility is dependent on the acquiring bank and card issuer, although it should be noted that most cards support this functionality.

The ability to conduct address checks is dependent on the location of your acquiring bank in relation to the location of the issuing bank of the card being presented. Most acquirers do support the process but only on locally issued cards. All UK cards and a number of US cards are address checked by all UK acquirers.

Security code checks are performed on all Visa, Mastercard and American Express branded cards worldwide and the results are checked internationally by all acquirers.

Please contact our Support team for further information on supported acquirers and card types.

 

Required fields

For checks to be successfully performed on the customer’s details, the customer will need to provide their billing postcode, billing premise and their card’s security code.

If this information is not present in the request to Trust Payments, we will return a “Not given” response.

 

Response codes

There are four different possible responses following AVS and security code checks. Each response is assigned a distinct code, as shown in the following table:

Code Description Comment
0 “Not given” Your acquirer was not provided with the information required to perform this check.
1 “Not checked” Your acquirer was unable to perform checks on the information provided.
2 “Matched” The information provided by the customer matches that on the card issuer’s records.
4 “Not matched” The information provided by the customer does NOT match that on the card issuer’s records.

 

Info
A “Not checked” response may be that the card issuer does not support address or security code checking for the card supplied or that the information was not provided. Most foreign cards issued will not be address checked.

Together, the AVS and security code checks consist of three total checks, and we assign a response code for each:

 

Security policy

Your account’s security policy consists of preferences on how we respond to instances where the address (premise & postcode) and security code entered by the customer does not directly match those found on the card issuer’s records. We can automatically suspend transactions that return certain response codes:

Info
By default, we suspend all transactions where the security code check returns a “Not matched” response.

To discuss or make changes to your security policy, please contact the Support team.

You can perform AVS and security code checks without debiting the customer. This is achieved by performing an Account Check. Click here to learn more about Account Checks.

 

Testing

We recommend that you thoroughly test your solution before processing live payments.
Click here for test card details that you can submit when testing.

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116