TRANSACTIONQUERY

Michael Buckley

August 24, 2023 12:44

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.
Read this article to learn more.

If you would like to retrieve information on requests and transactions you have previously submitted, you can submit a TRANSACTIONQUERY request.

Process overview

Your system will need to submit a TRANSACTIONQUERY request to Trust Payments. Trust Payments will then return a response containing the requested information, if a matching request has been found.

For example, you can request information on all transactions processed on your Site Reference between 6pm and 9pm, or find out whether or not a transaction has been settled.

Filters

The TRANSACTIONQUERY request consists primarily of filters. Think of filters as search criteria; the response returned will contain information meeting the specified filters.

For example, a filter with orderreference “100100” would return details of all matching requests with that reference (if any exist and have been processed on your site reference).

And specifying a starttimestamp and endtimestamp will return details of all requests processed on your account between the specified times.

Multiple records can be returned in a single response

We recommend being as specific as reasonably possible in your request, by submitting as many filters as required, in order to avoid returning an excessive number of records in the response.

You can also submit multiple values for each given filter. e.g. You can submit a filter for transactionreference values “23-9-1” and “23-9-2”, and any requests matching these values will be returned in the response. (We include an example of this case below)

TRANSACTIONQUERY request

For the TRANSACTIONQUERY request to be processed successfully, you need to submit at least one valid filter.

Request example

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

query = {
  "requesttypedescriptions": ["TRANSACTIONQUERY"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "currencyiso3a": [{"value":"GBP"}],
    "transactionreference": [{"value":"23-9-1"},{"value":"23-9-2"}]
  }
}

strequest = securetrading.Request()
strequest.update(query)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => 'webservices@example.com',
  'password' => 'Password1^',
);

$requestData = array(
  'requesttypedescriptions' => array('TRANSACTIONQUERY'),
  'filter' => array(
    'sitereference' => array(array('value' => 'test_site12345')),
    'currencyiso3a' => array(array('value' => 'GBP')),
    'transactionreference' => array(array('value' => '23-9-1'),array('value' => '23-9-2'))
  )
);

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

?>

curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "requesttypedescriptions": ["TRANSACTIONQUERY"],
    "filter":{
      "sitereference": [{"value":"test_site12345"}],
      "currencyiso3a": [{"value":"GBP"}],
      "transactionreference": [{"value":"23-9-1"},{"value":"23-9-2"}]
    }
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["TRANSACTIONQUERY"],
    "filter":{
      "sitereference":[{"value":"test_site12345"}],
      "currencyiso3a":[{"value":"GBP"}],
      "transactionreference":[{"value":"23-9-1"},{"value":"23-9-2"}]
    }
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="TRANSACTIONQUERY">
    <filter>
      <sitereference>test_site12345</sitereference>
      <currencyiso3a>GBP</currencyiso3a>
      <transactionreference>23-9-1</transactionreference>
      <transactionreference>23-9-2</transactionreference>
    </filter>
  </request>
</requestblock>

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

Field specification

The following table lists all fields that you can include in the filter when processing a TRANSACTIONQUERY request.

Although none of the following filter fields are required, at least one filter must be submitted for the request to be processed successfully. For this reason, most of the fields have been marked below as conditional.

An exception to this behaviour is the sitereference filter, which cannot be submitted on its own; it must be accompanied by at least one other filter. This restriction is enforced to reduce load on our servers.

Field	Format	Description
accounttypedescription XPath: /filter/accounttypedescription	Alpha (20)	The source of the transaction. For an e-commerce AUTH Request, the value should be “ECOM”. For Mail Order or Telephone Order (MOTO) requests, the value should be “MOTO”. For a recurring transaction, the value should be “RECUR”.
billingemail XPath: /filter/billingemail	Email (255)	The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingfirstname XPath: /filter/billingfirstname	Alphanumeric including symbols (127)	The customer’s billing first name.
billinglastname XPath: /filter/billinglastname	Alphanumeric including symbols (127)	The customer’s billing last name.
billingpostcode XPath: /filter/billingpostcode	Alphanumeric including symbols (25)	The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.
billingpremise XPath: /filter/billingpremise	Alphanumeric including symbols (20)	The number or name of the premise of the customer’s billing address.
billingstreet XPath: /filter/billingstreet	Alphanumeric including symbols (20)	The street name of the customer’s billing address.
completiontimestamp XPath: /filter/completiontimestamp	Date Time YYYY-MM-DD HH:MM:SS	This refers to when a pre-auth from a POS terminal with no funds currently scheduled for settlement is updated to allow settlement, by performing a completion request.
currencyiso3a XPath: /filter/currencyiso3a	Alpha (3)	The transaction currency. Click here for a full list of currency codes.
customerip XPath: /filter/customerip	IP address (39)	The customer’s IP address.
endtimestamp XPath: /filter/endtimestamp	Date Time YYYY-MM-DD HH:MM:SS	Only requests processed before the timestamp specified will be returned. (Unlike with other filters, you can only submit one endtimestamp in a request)
orderreference XPath: /filter/orderreference	Alphanumeric including symbols (25)	Unique reference number supplied by the merchant for the request.
pan XPath: /filter/pan	Numeric (12-19)	This is the card number printed on the front of the customer’s card.
parenttransactionreference XPath: /filter/parenttransactionreference	Alphanumeric including hyphens (25)	Unique reference of the parent request.
paymenttypedescription XPath: /filter/paymenttypedescription	Alpha (20)	The customer’s card type (e.g. “VISA” or “MASTERCARD”).
requesttypedescription XPath: /filter/requesttypedescription	Alpha (20)	The request type associated with transaction. For example, “AUTH” or “REFUND”. Click here for a full list of request types.
sitereference XPath: /filter/sitereference	Alpha (50)	The site reference that processed the transaction. The sitereference filter must be submitted with at least one other filter, otherwise an error will be returned.
starttimestamp XPath: /filter/starttimestamp	Date Time YYYY-MM-DD HH:MM:SS	Only requests processed after the timestamp specified will be returned. (Unlike with other filters, you can only submit one starttimestamp in a request)
transactionreference XPath: /filter/transactionreference	Alphanumeric including hyphens (25)	The unique reference associated with the transaction, assigned by Trust Payments.

Only the filters above can be submitted. If a filter submitted does not exactly match any of the supported values listed above, it will not be used to perform the search. For this reason, it is important that you ensure any filters included are spelt correctly and that you thoroughly test your solution to ensure the expected records are returned.

TRANSACTIONQUERY response

Once you have successfully submitted a TRANSACTIONQUERY request, you will be returned a response that is divided into separate records.

Each record will contain a varying number of response fields, which depend on the request type indicated in the record. For example, if the record has a requesttypedescription of “AUTH“, then you would need to refer to the field specification in the Authorisation.

Additionally, the response contains a field called found, which indicates the number of records that match the filters specified in the request. If found has a value of “0”, no records have been found using your specified filters.

For example, here is a simplified example of the structure of the response, consisting of 2 records (both are type “AUTH”):

{
u 'requestreference': u 'W72-pg3q2he9',
u 'version': u '1.00',
u 'responses': [{
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'found': u '2',
u 'records': [{
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'authcode': u 'TEST22',
u 'baseamount': u '1050',
u 'cavv': u 'dHJ1c3RwYXltZW50c2F1dGhlbnQ',
u 'currencyiso3a': u 'GBP',
u 'dccenabled': u '0',
u 'debtrepayment': u '0',
u 'eci': u '05',
u 'enrolled': u 'Y',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'expirydate': u '10/2022',
u 'fraudrating': u '0',
u 'interface': u 'PASS-JSON-JSON',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'issuercountryiso2a': u 'US',
u 'livestatus': u '0',
u 'maskedpan': u '411111######1111',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'operatorname': u 'webservices@example.com',
u 'paymenttypedescription': u 'VISA',
u 'requesttypedescription': u 'AUTH',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '2',
u 'settlebaseamount': u '1050',
u 'settleduedate': u '2019-12-17',
u 'settlestatus': u '0',
u 'sitereference': u 'test_site12345',
u 'splitfinalnumber': u '1',
u 'status': u 'Y',
u 'threedversion': u '2.2.0',
u 'tid': u '27882788',
u 'transactionreference': u '72-9-80005',
u 'transactionstartedtimestamp': u '2019-12-17 09:35:03'
}, {
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'authcode': u 'TEST03',
u 'baseamount': u '1050',
u 'cavv': u 'dHJ1c3RwYXltZW50c2F1dGhlbnR',
u 'currencyiso3a': u 'GBP',
u 'dccenabled': u '0',
u 'debtrepayment': u '0',
u 'eci': u '05',
u 'enrolled': u 'Y',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'expirydate': u '10/2022',
u 'fraudrating': u '0',
u 'interface': u 'PASS-JSON-JSON',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'issuercountryiso2a': u 'US',
u 'livestatus': u '0',
u 'maskedpan': u '411111######1111',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'operatorname': u 'webservices@example.com',
u 'paymenttypedescription': u 'VISA',
u 'requesttypedescription': u 'AUTH',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '2',
u 'settlebaseamount': u '1050',
u 'settleduedate': u '2019-12-17',
u 'settlestatus': u '0',
u 'sitereference': u 'test_site12345',
u 'splitfinalnumber': u '1',
u 'status': u 'Y',
u 'threedversion': u '2.2.0',
u 'tid': u '27882788',
u 'transactionreference': u '72-9-80006',
u 'transactionstartedtimestamp': u '2019-12-17 09:35:10'
}],
u 'requesttypedescription': u 'TRANSACTIONQUERY',
u 'transactionstartedtimestamp': u '2019-12-17 09:36:21'
}]
}

array(3) {
  ["requestreference"] => string(9) "W72-pg3q2he9"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(6) {
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["found"] => string(1) "2"
      ["records"] => array(2) {
        [0] => array(37) {
          ["accounttypedescription"] => string(4) "ECOM"
          ["acquirerresponsecode"] => string(2) "00"
          ["authcode"] => string(6) "TEST22"
          ["baseamount"] => string(4) "1050"
          ["cavv"] => string(27) "dHJ1c3RwYXltZW50c2F1dGhlbnQ"
          ["currencyiso3a"] => string(3) "GBP"
          ["dccenabled"] => string(1) "0"
          ["debtrepayment"] => string(1) "0"
          ["eci"] => string(2) "05"
          ["enrolled"] => string(1) "Y"
          ["errorcode"] => string(1) "0"
          ["errormessage"] => string(2) "Ok"
          ["expirydate"] => string(7) "10/2022"
          ["fraudrating"] => string(1) "0"
          ["interface"] => string(14) "PASS-JSON-JSON"
          ["issuer"] => string(26) "SecureTrading Test Issuer1"
          ["issuercountryiso2a"] => string(2) "US"
          ["livestatus"] => string(1) "0"
          ["maskedpan"] => string(16) "411111######1111"
          ["merchantcountryiso2a"] => string(2) "GB"
          ["merchantname"] => string(13) "Test Merchant"
          ["operatorname"] => string(23) "webservices@example.com"
          ["paymenttypedescription"] => string(4) "VISA"
          ["requesttypedescription"] => string(4) "AUTH"
          ["securityresponseaddress"] => string(1) "0"
          ["securityresponsepostcode"] => string(1) "0"
          ["securityresponsesecuritycode"] => string(1) "2"
          ["settlebaseamount"] => string(4) "1050"
          ["settleduedate"] => string(10) "2019-12-17"
          ["settlestatus"] => string(1) "0"
          ["sitereference"] => string(14) "test_site12345"
          ["splitfinalnumber"] => string(1) "1"
          ["status"] => string(1) "Y"
          ["threedversion"] => string(5) "2.2.0"
          ["tid"] => string(8) "27882788"
          ["transactionreference"] => string(10) "72-9-80005"
          ["transactionstartedtimestamp"] => string(19) "2019-12-17 09:35:03"
        }
        [1] => array(37) {
          ["accounttypedescription"] => string(4) "ECOM"
          ["acquirerresponsecode"] => string(2) "00"
          ["authcode"] => string(6) "TEST03"
          ["baseamount"] => string(4) "1050"
          ["cavv"] => string(27) "dHJ1c3RwYXltZW50c2F1dGhlbnR"
          ["currencyiso3a"] => string(3) "GBP"
          ["dccenabled"] => string(1) "0"
          ["debtrepayment"] => string(1) "0"
          ["eci"] => string(2) "05"
          ["enrolled"] => string(1) "Y"
          ["errorcode"] => string(1) "0"
          ["errormessage"] => string(2) "Ok"
          ["expirydate"] => string(7) "10/2022"
          ["fraudrating"] => string(1) "0"
          ["interface"] => string(14) "PASS-JSON-JSON"
          ["issuer"] => string(26) "SecureTrading Test Issuer1"
          ["issuercountryiso2a"] => string(2) "US"
          ["livestatus"] => string(1) "0"
          ["maskedpan"] => string(16) "411111######1111"
          ["merchantcountryiso2a"] => string(2) "GB"
          ["merchantname"] => string(13) "Test Merchant"
          ["operatorname"] => string(23) "webservices@example.com"
          ["paymenttypedescription"] => string(4) "VISA"
          ["requesttypedescription"] => string(4) "AUTH"
          ["securityresponseaddress"] => string(1) "0"
          ["securityresponsepostcode"] => string(1) "0"
          ["securityresponsesecuritycode"] => string(1) "2"
          ["settlebaseamount"] => string(4) "1050"
          ["settleduedate"] => string(10) "2019-12-17"
          ["settlestatus"] => string(1) "0"
          ["sitereference"] => string(14) "test_site12345"
          ["splitfinalnumber"] => string(1) "1"
          ["status"] => string(1) "Y"
          ["threedversion"] => string(5) "2.2.0"
          ["tid"] => string(8) "27882788"
          ["transactionreference"] => string(10) "72-9-80006"
          ["transactionstartedtimestamp"] => string(19) "2019-12-17 09:35:10"
        }
      }
      ["requesttypedescription"] => string(16) "TRANSACTIONQUERY"
      ["transactionstartedtimestamp"] => string(19) "2019-12-17 09:36:21"
    }
  }
}

{"requestreference":"W72-pg3q2he9",
  "version":"1.00",
  "response":[{
    "errorcode":"0",
    "errormessage":"Ok",
    "found":"2",
    "records":[{
      "accounttypedescription":"ECOM",
      "acquirerresponsecode":"00",
      "authcode":"TEST22",
      "baseamount":"1050",
      "cavv":"dHJ1c3RwYXltZW50c2F1dGhlbnQ",
      "currencyiso3a":"GBP",
      "dccenabled":"0",
      "debtrepayment":"0",
      "eci":"05",
      "enrolled":"Y",
      "errorcode":"0",
      "errormessage":"Ok",
      "expirydate":"10\/2022",
      "fraudrating":"0",
      "interface":"PASS-JSON-JSON",
      "issuer":"SecureTrading Test Issuer1",
      "issuercountryiso2a":"US",
      "livestatus":"0",
      "maskedpan":"411111######1111",
      "merchantcountryiso2a":"GB",
      "merchantname":"Test Merchant",
      "operatorname":"webservices@example.com",
      "paymenttypedescription":"VISA",
      "requesttypedescription":"AUTH",
      "securityresponseaddress":"0",
      "securityresponsepostcode":"0",
      "securityresponsesecuritycode":"2",
      "settlebaseamount":"1050",
      "settleduedate":"2019-12-17",
      "settlestatus":"0",
      "sitereference":"test_site12345",
      "splitfinalnumber":"1",
      "status":"Y",
      "threedversion":"2.2.0",
      "tid":"27882788",
      "transactionreference":"72-9-80005",
      "transactionstartedtimestamp":"2019-12-17 09:35:03"
    },
    {
      "accounttypedescription":"ECOM",
      "acquirerresponsecode":"00",
      "authcode":"TEST03",
      "baseamount":"1050",
      "cavv":"dHJ1c3RwYXltZW50c2F1dGhlbnR",
      "currencyiso3a":"GBP",
      "dccenabled":"0",
      "debtrepayment":"0",
      "eci":"05",
      "enrolled":"Y",
      "errorcode":"0",
      "errormessage":"Ok",
      "expirydate":"10\/2022",
      "fraudrating":"0",
      "interface":"PASS-JSON-JSON",
      "issuer":"SecureTrading Test Issuer1",
      "issuercountryiso2a":"US",
      "livestatus":"0",
      "maskedpan":"411111######1111",
      "merchantcountryiso2a":"GB",
      "merchantname":"Test Merchant",
      "operatorname":"webservices@example.com",
      "paymenttypedescription":"VISA",
      "requesttypedescription":"AUTH",
      "securityresponseaddress":"0",
      "securityresponsepostcode":"0",
      "securityresponsesecuritycode":"2",
      "settlebaseamount":"1050",
      "settleduedate":"2019-12-17",
      "settlestatus":"0",
      "sitereference":"test_site12345",
      "splitfinalnumber":"1",
      "status":"Y",
      "threedversion":"2.2.0",
      "tid":"27882788",
      "transactionreference":"72-9-80006",
      "transactionstartedtimestamp":"2019-12-17 09:35:10"
    }],
    "requesttypedescription":"TRANSACTIONQUERY",
    "transactionstartedtimestamp":"2019-12-17 09:36:21"
  }],
  "secrand":"uISZfw8wKWR"
}

<responseblock version="3.67">
  <requestreference>Xv18xwv52</requestreference>
  <response type="TRANSACTIONQUERY">
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <found>2</found>
    <record type="AUTH">
      <acquirerresponsecode>00</acquirerresponsecode>
      <authcode>TEST35</authcode>
      <billing>
        <amount currencycode="GBP">1050</amount>
        <dcc enabled="0"/>
        <payment type="VISA">
          <expirydate>10/2022</expirydate>
          <issuer>SecureTrading Test Issuer1</issuer>
          <issuercountry>US</issuercountry>
          <pan>411111######1111</pan>
        </payment>
      </billing>
      <error>
        <code>0</code>
        <message>Ok</message>
      </error>
      <fraud>
        <rating>0</rating>
      </fraud>
      <live>0</live>
      <merchant>
        <debtrepayment>0</debtrepayment>
        <merchantcountryiso2a>GB</merchantcountryiso2a>
        <merchantname>Test Merchant</merchantname>
        <operatorname>webservices@example.com</operatorname>
        <tid>27882788</tid>
      </merchant>
      <operation>
        <accounttypedescription>ECOM</accounttypedescription>
        <interface>CERT-XML-XML</interface>
        <sitereference>test_site12345</sitereference>
        <splitfinalnumber>1</splitfinalnumber>
      </operation>
      <security>
        <address>0</address>
        <postcode>0</postcode>
        <securitycode>2</securitycode>
      </security>
      <settlement>
        <settlebaseamount>1050</settlebaseamount>
        <settleduedate>2019-12-17</settleduedate>
        <settlestatus>0</settlestatus>
      </settlement>
      <threedsecure>
        <cavv>dHJ1c3RwYXltZW50c2F1dGhlbnQ</cavv>
        <eci>05</eci>
        <enrolled>Y</enrolled>
        <status>Y</status>
        <threedversion>2.2.0</threedversion>
      </threedsecure>
      <timestamp>2019-12-17 09:17:58</timestamp>
      <transactionreference>72-9-80003</transactionreference>
    </record>
    <record type="AUTH">
      <acquirerresponsecode>00</acquirerresponsecode>
      <authcode>TEST06</authcode>
      <billing>
        <amount currencycode="GBP">1050</amount>
        <dcc enabled="0"/>
        <payment type="VISA">
          <expirydate>10/2022</expirydate>
          <issuer>SecureTrading Test Issuer1</issuer>
          <issuercountry>US</issuercountry>
          <pan>411111######1111</pan>
        </payment>
      </billing>
      <error>
        <code>0</code>
        <message>Ok</message>
      </error>
      <fraud>
        <rating>0</rating>
      </fraud>
      <live>0</live>
      <merchant>
        <debtrepayment>0</debtrepayment>
        <merchantcountryiso2a>GB</merchantcountryiso2a>
        <merchantname>Test Merchant</merchantname>
        <operatorname>webservices@example.com</operatorname>
        <tid>27882788</tid>
      </merchant>
      <operation>
        <accounttypedescription>ECOM</accounttypedescription>
        <interface>CERT-XML-XML</interface>
        <sitereference>test_site12345</sitereference>
        <splitfinalnumber>1</splitfinalnumber>
      </operation>
      <security>
        <address>0</address>
        <postcode>0</postcode>
        <securitycode>2</securitycode>
      </security>
      <settlement>
        <settlebaseamount>1050</settlebaseamount>
        <settleduedate>2019-12-17</settleduedate>
        <settlestatus>0</settlestatus>
      </settlement>
      <threedsecure>
        <cavv>dHJ1c3RwYXltZW50c2F1dGhlbnR</cavv>
        <eci>05</eci>
        <enrolled>Y</enrolled>
        <status>Y</status>
        <threedversion>2.2.0</threedversion>
      </threedsecure>
      <timestamp>2019-12-17 09:19:00</timestamp>
      <transactionreference>72-9-80004</transactionreference>
    </record>
    <timestamp>2019-12-17 09:19:00</timestamp>
  </response>
  <secrand>IDBpVj</secrand>
</responseblock>

A maximum of 500 records can be returned per response.

The found field will never return a value higher than 500, even if more than 500 requests meet the specified criteria.

Understanding errors

Please ensure you understand the Error Codes returned in the response:

At the highest level of the response, along with transactionstartedtimestamp and found, there is an errorcode. This indicates whether or not the TRANSACTIONQUERY request was successful. If the error code here is not “0”, the TRANSACTIONQUERY request was not successful. You must address the problem and try again.
In addition to this, each record will contain their own errorcode. This indicates whether or not the request represented in the record was successful.
For a full list of error codes used by Trust Payments, click here.

Field specification

The following table lists all fields that can be returned in a given record.

Fields are only returned if the data is available for the request queried.
This can vary depending on request type.

Field	Format	Description
accounttypedescription XPath: /record/operation/accounttypedescription	Alpha (20)	The type of account used to process the request queried: “ECOM” – E-commerce. “MOTO” – Mail or Telephone Order “RECUR” – Recurring transactions
acquireradvicecode XPath: /record/acquireradvicecode	Numeric (1)	A numeric value returned following a repeat payment request, indicating if further payments can be processed. Mapping: 0 – No action required. 1 – New account information available. 2 – Cannot approve at this time. 4 – Do not process further recurring transactions. 8 – Payment blocked by card scheme. Whether this field is returned varies depending on your acquiring bank. Please contact our Support Team if you need assistance.
acquirerresponsecode XPath: /record/acquirerresponsecode	Alphanumeric (255)	Used by your acquirer to indicate the outcome of the request queried. Whether these fields are returned vary depending on your acquiring bank. Please contact our Support Team if you need assistance.
acquirerresponsemessage XPath: /record/acquirerresponsemessage	Alphanumeric (255)
authcode XPath: /record/authcode	Alphanumeric (255)	The authorisation code provided by the issuing bank. This will differ depending on which bank you use. Only returned if the queried transaction was authorised.
authmethod XPath: /record/operation/authmethod	Alpha (11)	Auth methods are used to specify how a transaction is to be processed by the card issuer. Each authmethod has a different set of requirements. Click the following links to learn more: PRE - Pre-authorisation FINAL - Final authorisation INCREMENTAL - Incremental authorisation SPLIT - Split shipment Only returned when an authmethod value has been assigned to the request.
baseamount XPath: /record/billing/amount	Numeric (13)	The amount of the transaction queried in base units, with no commas or decimal points, so £10 is submitted as 1000.
billingcountryiso2a XPath: /record/billing/country	Alpha (2)	The country for the customer’s billing address in ISO2A format. Click here for a full list of country codes. This field is returned if available.
billingcounty XPath: /record/billing/county	Alphanumeric including symbols (127)	The county entered for the customer’s billing address. For US addresses, the state is returned here in a 2-character format (e.g. "NY"). This field is returned if available.
billingemail XPath: /record/billing/email	Email (255)	The customer’s billing email address. This field is returned if available.
billingfirstname XPath: /record/billing/name/first	Alphanumeric including symbols (127)	The customer’s billing first name. This field is returned if available.
billinglastname XPath: /record/billing/name/last	Alphanumeric including symbols (127)	The customer’s billing last name. This field is returned if available.
billingmiddlename XPath: /record/billing/name/middle	Alphanumeric including symbols (127)	The customer’s billing middle name(s). This field is returned if available.
billingpostcode XPath: /record/billing/postcode	Alphanumeric (25)	The postcode entered for the customer’s billing address. This field is returned if available.
billingprefixname XPath: /record/billing/name/prefix	Alphanumeric including symbols (25)	The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). This field is returned if available.
billingpremise XPath: /record/billing/premise	Alphanumeric including symbols (25)	The house number or first line of the customer’s billing address. This field is returned if available.
billingstreet XPath: /record/billing/street	Alphanumeric including symbols (127)	The street entered for the customer’s billing address. This field is returned if available.
billingsuffixname XPath: /record/billing/name/suffix	Alphanumeric including symbols (25)	The suffix of the customer’s billing name (e.g. Bsc). This field is returned if available.
billingtelephone XPath: /record/billing/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. This field is returned if available.
billingtelephonetype XPath: /record/billing/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work This field is returned if available.
billingtown XPath: /record/billing/town	Alphanumeric including symbols (127)	The town entered for the customer’s billing address. This field is returned if available.
cavv XPath: /record/threedsecure/cavv	Alphanumeric (56)	The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction. This field is returned if available.
chargedescription XPath: /record/merchant/chargedescription	Alphanumeric including symbols (25)	This is a description of the queried payment that appears on the customer’s bank statement. This field is returned if available.
credentialsonfile XPath: /record/operation/credentialsonfile	Numeric (1)	The allowed values for this field are 0, 1 and 2. “0” – Not eligible for CoF, or no intention of re-using credentials at a later time. “1” – Transaction credentials flagged as available for future use. “2” – Payment using previously-stored credentials. Only returned when a credentialsonfile value has been assigned to the request.
currencyiso3a XPath: /record/billing/amount/@currencycode	Alpha (3)	The currency of the transaction queried. Click here for a full list of available currencies.
customercountryiso2a XPath: /record/customer/country	Alpha (2)	The country for the customer’s delivery address in ISO2A format. Click here for a full list of country codes. This field is returned if available.
customercounty XPath: /record/customer/county	Alphanumeric including symbols (127)	The county entered for the customer’s delivery address. For US addresses, the state is returned here in a 2-character format (e.g. "NY"). This field is returned if available.
customeremail XPath: /record/customer/email	Email (255)	The customer’s delivery email address. This field is returned if available.
customerfirstname XPath: /record/customer/name/first	Alphanumeric including symbols (127)	The customer’s delivery first name. This field is returned if available.
customerip XPath: /record/customer/ip	IP address (39)	The IP of the customer.
customerlastname XPath: /record/customer/name/last	Alphanumeric including symbols (127)	The customer’s delivery last name. This field is returned if available.
customermiddlename XPath: /record/customer/name/middle	Alphanumeric including symbols (127)	The customer’s delivery middle name(s). This field is returned if available.
customerpostcode XPath: /record/customer/postcode	Alphanumeric (25)	The postcode entered for the customer’s delivery address. This field is returned if available.
customerprefixname XPath: /record/customer/name/prefix	Alphanumeric including symbols (25)	The prefix of the customer’s delivery name (e.g. Mr, Miss, Dr). This field is returned if available.
customerpremise XPath: /record/customer/premise	Alphanumeric including symbols (25)	The house number or first line of the customer’s delivery address. This field is returned if available.
customerstreet XPath: /record/customer/street	Alphanumeric including symbols (127)	The street entered for the customer’s delivery address. This field is returned if available.
customersuffixname XPath: /record/customer/name/suffix	Alphanumeric including symbols (25)	The suffix of the customer’s delivery name (e.g. Bsc). This field is returned if available.
customertelephone XPath: /record/customer/telephone	Alphanumeric including symbols (20)	The customer’s telephone number. This field is returned if available.
customertelephonetype XPath: /record/customer/telephone/@type	Char (1)	The type of telephone number. The options available are: H = Home M = Mobile W = Work This field is returned if available.
customertown XPath: /record/customer/town	Alphanumeric including symbols (127)	The town entered for the customer’s delivery address. This field is returned if available.
dccenabled XPath: /record/billing/dcc/@enabled	Numeric (1)	Indicates if your account is configured for DCC: 1= Yes 0 = No Only returned for card transactions.
debtrepayment XPath: /record/merchant/debtrepayment	Numeric (1)	Indicates if transaction is flagged as debt repayment: 1 – Transaction is flagged as debt repayment. 0 – Transaction is not flagged as debt repayment. Click here to learn more. Only returned for card transactions.
eci XPath: /record/threedsecure/eci	Alphanumeric (2)	The ECI (E-Commerce Indicator) security level associated with the transaction. Click here to learn more about possible ECI values.
enrolled XPath: /record/threedsecure/enrolled	Char (1)	Indicates whether or not the customer’s card is enrolled in a 3-D Secure scheme. Click here to learn more.
errorcode XPath: /record/error/code	Numeric (1-5)	The error code should be used to determine whether the request(s) being queried was successful. If the error code is “0” then the transaction was successful. If the error code is not “0” then the transaction was not successful. Click here for a full list of errorcode and message values.
errordata XPath: /record/error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.
errormessage XPath: /record/error/message	Alphanumeric (255)	This provides a brief explanation as to the cause of the error. For successful transactions, this is returned as “Ok”. Click here for a full list of errorcode and message values.
expirydate XPath: /record/billing/payment/expirydate	Date MM/YYYY	The expiry date printed on the card. Only returned for card transactions.
fraudrating XPath: /record/fraud/rating	Numeric (2)	This field pertains to our internal fraud checks, as documented in this article. This value represents the queried transaction's currently-assigned fraud rating. This feature is opt in. If not enabled on your site reference, 0 will always be returned. If you have opted in: -1 indicates checks are pending. The higher the fraud rating, the greater the number of suspicious characteristics that have been identified by our fraud system. By default, we will notify you of transactions that have a fraud rating of 2 or higher. By default, we will suspend all transactions that have a fraud rating of 5 or higher. Click here to learn more. Only returned for card transactions.
interface XPath: /record/operation/interface	Alphanumeric including symbols (50)	Represents the interface through which the queried request was processed. The following are common examples: "JWT-JWT-JWT" - JavaScript Library or Mobile SDK. "MYST" - MyST (e.g. Refund, Virtual terminal or Payout terminal). "PASS-JSON-JSON" - Webservices API using JSON markup. "PASS-XML-XML" - Webservices API using XML markup.
issuer XPath: /record/billing/payment/issuer	Alphanumeric (255)	The customer’s card issuer. Only returned for card transactions.
issuercountryiso2a XPath: /record/billing/payment/issuercountry	Alpha (2)	The country for the customer’s card issuer. This will be in ISO2A format. Click here for a full list of country codes. Only returned for card transactions.
livestatus XPath: /record/live	Numeric (1)	0 – The queried transaction was processed using a test account. 1 – The queried transaction was processed using a live account.
maskedpan XPath: /record/billing/payment/pan	Alphanumeric including “#” (12-19)	If tokenisedpayment is not returned: The maskedpan field represents the customer’s card number. If tokenisedpayment is returned with value 1: The maskedpan field represents the customer’s unique token number used to perform the queried transaction. The value of maskedpan field is masked in the response. Most of the number is intentionally obscured by “#” characters, e.g. 411111######0211. Only returned for card transactions.
merchantcategorycode XPath: /record/merchant/merchantcategorycode	Alphanumeric (255)	These are details associated with the account used to process the queried transaction. To amend these fields, please contact our Support Team. Values returned depends on your account configuration.
merchantcity XPath: /record/merchant/merchantcity	Alphanumeric (127)
merchantcountryiso2a XPath: /record/merchant/merchantcountryiso2a	Alpha (2)
merchantname XPath: /record/merchant/merchantname	Alphanumeric (255)
merchantstatecode XPath: /record/merchant/merchantstatecode	Alphanumeric (127)
merchantzipcode XPath: /record/merchant/merchantzipcode	Alphanumeric (10)
operatorname XPath: /record/merchant/operatorname	Alphanumeric (255)	The value of this field contains the name of the user that processed the request.
orderreference XPath: /record/merchant/orderreference	Alphanumeric including symbols (25)	The unique order reference for the request queried that is stored on the Trust Payments system. This field is returned if available.
parenttransactionreference XPath: /record/operation/parenttransactionreference	Alphanumeric & hyphens (25)	The transactionreference of a previous request, from which key details have been inherited in the request queried. This field is returned if available.
paymenttypedescription XPath: /record/billing/payment/@type	Alpha (20)	Payment method (e.g. “VISA” or “MASTERCARD”).
requesttypedescription XPath: /record/@type	Alpha (20)	The type of request returned in the record.
retrievalreferencenumber XPath: /record/other/retrievalreferencenumber	Alphanumeric (255)	An ISO term. This is used to reference the source transaction. This field is returned if available. This will vary depending on your acquiring bank. Please contact your bank for further information.
scaexemptionindicator XPath: /record/operation/scaexemptionindicator	Numeric (1)	Returned if queried transaction has been flagged as exempt from EMV 3DS. Click here to learn more. The following values can be returned: 1 – Low value 2 – Transaction Risk Analysis 3 – Trusted Merchant 4 – Secure Corporate payment 5 – Delegated authentication
securityresponseaddress XPath: /record/security/address	Numeric (1)	The result of AVS and Security Code Checks. These contain one of the following values: 0 - Acquirer not provided with info required to perform this check. 1 - Acquirer unable to perform checks on info provided. 2 - Info provided by customer matches that found on card issuer's records. 4 - Info provided by customer does NOT match that found on card issuer's records. Click here to learn more. These fields are returned if available.
securityresponsepostcode XPath: /record/security/postcode	Numeric (1)
securityresponsesecuritycode XPath: /record/security/securitycode	Numeric (1)
settlebaseamount XPath: /record/settlement/settlebaseamount	Numeric (13)	The value of amount to be settled. The amount settled can be updated to be lower than the amount initially authorised using a TRANSACTIONUPDATE request.
settleduedate XPath: /record/settlement/settleduedate	Date YYYY-MM-DD	The date on which the queried transaction will be settled.
settledtimestamp XPath: /record/settlement/settledtimestamp	Date time YYYY-MM-DD hh:mm:ss	The date and time the queried transaction was settled. Only returned if transaction if transaction has been settled.
settlestatus XPath: /record/settlement/settlestatus	Numeric (3)	A numeric value used to indicate the progress of settlement regarding the queried transaction. Click here for a full list of settlestatus values.
sitereference XPath: /record/operation/sitereference	Alphanumeric & underscore (50)	The site reference through which the queried request was processed.
splitfinalnumber XPath: /operation/splitfinalnumber	Numeric (2)	Total number of splits permitted. If you are not performing Split shipment, this will be returned as 1. Click here to learn more about Split shipment. Only returned for card transactions.
stan XPath: /record/other/stan	ISO 8583	The STAN (System Trace Audit Number) associated with the transaction. This follows the ISO 8583 standard. This field is returned if available.
status XPath: /record/threedsecure/status	Char (1)	Indicates whether or not the customer was authenticated on the card issuer’s ACS. Click here to learn more.
threedversion XPath: /record/threedsecure/version	Numeric (6)	Version of 3-D Secure used to authenticate the payment. (e.g. “2.1.0”)
tid XPath: /record/merchant/tid	Alphanumeric (255)	The terminal ID used to process the queried transaction. This is accredited to your merchant number when we setup your account in our systems. Whether this field is returned varies depending on your acquiring bank. Please contact our Support Team if you need assistance.
tokenisedpayment XPath: /record/billing/payment/pan/@tokenised	Numeric (1)	If this field is returned with value 1, this indicates the queried transaction was processed using a token. This field is returned if available.
tokentype XPath: /record/billing/payment/pan/@tokentype	Alphanumeric (50)	Used to identify the type of token used for the queried payment (e.g. “VISATOKEN”). This field is returned if available.
transactionreference XPath: /record/transactionreference	Alphanumeric including hyphens (25)	A unique reference for the queried transaction assigned by Trust Payments. You will need this reference to perform a refund or update the transaction.
transactionstartedtimestamp XPath: /record/timestamp	Date time YYYY-MM-DD hh:mm:ss	The time the queried transaction was processed.
updatereason XPath: /record/settlement/updatereason	Alphanumeric (255)	The most recent party to perform an update on the transaction returned. If the transaction was never updated after the initial request was sent, this field will not be populated. Common examples: The username of user that performed the update. "rulemanager" - Transaction was updated by our Rule manager. "securitypolicy" - Transaction was updated as per the security policy on your account. "settle" - Transaction was updated by our settlement engine. "duplicate" - Transaction was deemed a duplicate and suspended by our duplicate checks. This field is returned if available.
walletdisplayname XPath: /record/billing/payment/wallet/displayname	Alphanumeric (255)	This normally contains the last four digits of the customer’s card number (e.g. “1111”). This field is returned if available.
walletsource XPath: /record/billing/payment/wallet/source	Alphanumeric (20)	Used to identify the type of wallet used for the queried payment (e.g. “APPLEPAY”). This field is returned if available.

Process overview

Filters

Multiple records can be returned in a single response

TRANSACTIONQUERY request

Request example

Field specification

TRANSACTIONQUERY response

A maximum of 500 records can be returned per response.

Understanding errors

Field specification

Articles in this section