Contents

Transaction queries

 

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.

 

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 Secure Trading. Secure Trading 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.

Info

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 = "[email protected]"
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' => '[email protected]',
  '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 [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": ["TRANSACTIONQUERY"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "currencyiso3a": [{"value":"GBP"}],
    "transactionreference": [{"value":"23-9-1"},{"value":"23-9-2"}]
  }
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONQUERY"],"filter":{"sitereference":[{"value":"test_site12345"}],"currencyiso3a":[{"value":"GBP"}],"transactionreference":[{"value":"23-9-1"},{"value":"23-9-2"}]}}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
  <alias>[email protected]</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.

Note that 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, all fields have been marked below as conditional.

 

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 customer’s billing postcode.
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.
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 (255) 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.
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 Secure Trading.

 

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

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 'response': [{
      u 'transactionstartedtimestamp': u '2019-12-17 09:36:21',
        u 'errormessage': u 'Ok',
        u 'errorcode': u '0',
        u 'records': [{
            u 'transactionstartedtimestamp': u '2019-12-17 09:35:03',
            u 'sitereference': u 'test_site12345',
            u 'interface': u 'PASS-JSON-JSON',
            u 'livestatus': u '0',
            u 'issuer': u 'SecureTrading Test Issuer1',
            u 'dccenabled': u '0',
            u 'settleduedate': u '2019-12-17',
            u 'errorcode': u '0',
            u 'baseamount': u '1050',
            u 'tid': u '27882788',
            u 'securityresponsepostcode': u '0',
            u 'transactionreference': u '72-9-80005',
            u 'merchantname': u 'Test Merchant',
            u 'paymenttypedescription': u 'VISA',
            u 'accounttypedescription': u 'ECOM',
            u 'fraudrating': u '0',
            u 'splitfinalnumber': u '1',
            u 'acquirerresponsecode': u '00',
            u 'requesttypedescription': u 'AUTH',
            u 'expirydate': u '10/2022',
            u 'securityresponsesecuritycode': u '2',
            u 'currencyiso3a': u 'GBP',
            u 'authcode': u 'TEST22',
            u 'settlebaseamount': u '1050',
            u 'errormessage': u 'Ok',
            u 'issuercountryiso2a': u 'US',
            u 'merchantcountryiso2a': u 'GB',
            u 'maskedpan': u '411111######1111',
            u 'securityresponseaddress': u '0',
            u 'operatorname': u '[email protected]',
            u 'settlestatus': u '0'
        }, {
            u 'transactionstartedtimestamp': u '2019-12-17 09:35:10',
            u 'sitereference': u 'test_site12345',
            u 'interface': u 'PASS-JSON-JSON',
            u 'livestatus': u '0',
            u 'issuer': u 'SecureTrading Test Issuer1',
            u 'dccenabled': u '0',
            u 'settleduedate': u '2019-12-17',
            u 'errorcode': u '0',
            u 'baseamount': u '1050',
            u 'tid': u '27882788',
            u 'securityresponsepostcode': u '0',
            u 'transactionreference': u '72-9-80006',
            u 'merchantname': u 'Test Merchant',
            u 'paymenttypedescription': u 'VISA',
            u 'accounttypedescription': u 'ECOM',
            u 'fraudrating': u '0',
            u 'splitfinalnumber': u '1',
            u 'acquirerresponsecode': u '00',
            u 'requesttypedescription': u 'AUTH',
            u 'expirydate': u '10/2022',
            u 'securityresponsesecuritycode': u '2',
            u 'currencyiso3a': u 'GBP',
            u 'authcode': u 'TEST03',
            u 'settlebaseamount': u '1050',
            u 'errormessage': u 'Ok',
            u 'issuercountryiso2a': u 'US',
            u 'merchantcountryiso2a': u 'GB',
            u 'maskedpan': u '411111######1111',
            u 'securityresponseaddress': u '0',
            u 'operatorname': u '[email protected]',
            u 'settlestatus': u '0'
        }],
        u 'found': u '2',
        u 'requesttypedescription': u 'TRANSACTIONQUERY'
    }]
}
array(3) {
  ["requestreference"] => string(9) "W72-pg3q2he9"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(6) {
      ["transactionstartedtimestamp"] => string(19) "2019-12-17 09:36:21"
      ["errormessage"] => string(2) "Ok"
      ["errorcode"] => string(1) "0"
      ["records"] => array(2) {
          [0] => array(31) {
              ["transactionstartedtimestamp"] => string(19) "2019-12-17 09:35:03"
              ["sitereference"] => string(14) "test_site12345"
              ["interface"] => string(14) "PASS-JSON-JSON"
              ["livestatus"] => string(1) "0"
              ["issuer"] => string(26) "SecureTrading Test Issuer1"
              ["dccenabled"] => string(1) "0"
              ["settleduedate"] => string(10) "2019-12-17"
              ["errorcode"] => string(1) "0"
              ["baseamount"] => string(4) "1050"
              ["tid"] => string(8) "27882788"
              ["securityresponsepostcode"] => string(1) "0"
              ["transactionreference"] => string(10) "72-9-80005"
              ["merchantname"] => string(13) "Test Merchant"
              ["paymenttypedescription"] => string(4) "VISA"
              ["accounttypedescription"] => string(4) "ECOM"
              ["fraudrating"] => string(1) "0"
              ["splitfinalnumber"] => string(1) "1"
              ["acquirerresponsecode"] => string(2) "00"
              ["requesttypedescription"] => string(4) "AUTH"
              ["expirydate"] => string(7) "10/2022"
              ["securityresponsesecuritycode"] => string(1) "2"
              ["currencyiso3a"] => string(3) "GBP"
              ["authcode"] => string(6) "TEST22"
              ["settlebaseamount"] => string(4) "1050"
              ["errormessage"] => string(2) "Ok"
              ["issuercountryiso2a"] => string(2) "US"
              ["merchantcountryiso2a"] => string(2) "GB"
              ["maskedpan"] => string(16) "411111######1111"
              ["securityresponseaddress"] => string(1) "0"
              ["operatorname"] => string(23) "[email protected]"
              ["settlestatus"] => string(1) "0"
            }
            [1] => array(31) {
              ["transactionstartedtimestamp"] => string(19) "2019-12-17 09:35:10"
              ["sitereference"] => string(14) "test_site12345"
              ["interface"] => string(14) "PASS-JSON-JSON"
              ["livestatus"] => string(1) "0"
              ["issuer"] => string(26) "SecureTrading Test Issuer1"
              ["dccenabled"] => string(1) "0"
              ["settleduedate"] => string(10) "2019-12-17"
              ["errorcode"] => string(1) "0"
              ["baseamount"] => string(4) "1050"
              ["tid"] => string(8) "27882788"
              ["securityresponsepostcode"] => string(1) "0"
              ["transactionreference"] => string(10) "72-9-80006"
              ["merchantname"] => string(13) "Test Merchant"
              ["paymenttypedescription"] => string(4) "VISA"
              ["accounttypedescription"] => string(4) "ECOM"
              ["fraudrating"] => string(1) "0"
              ["splitfinalnumber"] => string(1) "1"
              ["acquirerresponsecode"] => string(2) "00"
              ["requesttypedescription"] => string(4) "AUTH"
              ["expirydate"] => string(7) "10/2022"
              ["securityresponsesecuritycode"] => string(1) "2"
              ["currencyiso3a"] => string(3) "GBP"
              ["authcode"] => string(6) "TEST03"
              ["settlebaseamount"] => string(4) "1050"
              ["errormessage"] => string(2) "Ok"
              ["issuercountryiso2a"] => string(2) "US"
              ["merchantcountryiso2a"] => string(2) "GB"
              ["maskedpan"] => string(16) "411111######1111"
              ["securityresponseaddress"] => string(1) "0"
              ["operatorname"] => string(23) "[email protected]"
              ["settlestatus"] => string(1) "0"
            }
        }
        ["found"] => string(1) "2"
        ["requesttypedescription"] => string(16) "TRANSACTIONQUERY"
    }
  }
}
{"requestreference":"W72-pg3q2he9","version":"1.00","response":[{"transactionstartedtimestamp":"2019-12-17 09:36:21","errormessage":"Ok","errorcode":"0","records":[{"transactionstartedtimestamp":"2019-12-17 09:35:03","sitereference":"test_site12345","interface":"PASS-JSON-JSON","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2019-12-17","errorcode":"0","baseamount":"1050","tid":"27882788","securityresponsepostcode":"0","transactionreference":"72-9-80005","merchantname":"Test Merchant","paymenttypedescription":"VISA","accounttypedescription":"ECOM","fraudrating":"0","splitfinalnumber":"1","acquirerresponsecode":"00","requesttypedescription":"AUTH","expirydate":"10\/2022","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST22","settlebaseamount":"1050","errormessage":"Ok","issuercountryiso2a":"US","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"0","operatorname":"[email protected]","settlestatus":"0"},{"transactionstartedtimestamp":"2019-12-17 09:35:10","sitereference":"test_site12345","interface":"PASS-JSON-JSON","livestatus":"0","issuer":"SecureTrading Test Issuer1","dccenabled":"0","settleduedate":"2019-12-17","errorcode":"0","baseamount":"1050","tid":"27882788","securityresponsepostcode":"0","transactionreference":"72-9-80006","merchantname":"Test Merchant","paymenttypedescription":"VISA","accounttypedescription":"ECOM","fraudrating":"0","splitfinalnumber":"1","acquirerresponsecode":"00","requesttypedescription":"AUTH","expirydate":"10\/2022","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST03","settlebaseamount":"1050","errormessage":"Ok","issuercountryiso2a":"US","merchantcountryiso2a":"GB","maskedpan":"411111######1111","securityresponseaddress":"0","operatorname":"[email protected]","settlestatus":"0"}],"found":"2","requesttypedescription":"TRANSACTIONQUERY"}],"secrand":"uISZfw8wKWR"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>Xv18xwv52</requestreference>
  <response type="TRANSACTIONQUERY">
    <record type="AUTH">
      <acquirerresponsecode>00</acquirerresponsecode>
      <operation>
        <splitfinalnumber>1</splitfinalnumber>
        <sitereference>test_site12345</sitereference>
        <interface>CERT-XML-XML</interface>
        <accounttypedescription>ECOM</accounttypedescription>
      </operation>
      <settlement>
        <settleduedate>2019-12-17</settleduedate>
        <settlebaseamount>1050</settlebaseamount>
        <settlestatus>0</settlestatus>
      </settlement>
      <billing>
        <dcc enabled="0"/>
        <amount currencycode="GBP">1050</amount>
        <payment type="VISA">
          <issuer>SecureTrading Test Issuer1</issuer>
          <expirydate>10/2022</expirydate>
          <pan>411111######1111</pan>
          <issuercountry>US</issuercountry>
        </payment>
      </billing>
      <live>0</live>
      <merchant>
        <tid>27882788</tid>
        <merchantcountryiso2a>GB</merchantcountryiso2a>
        <merchantname>Test Merchant</merchantname>
        <operatorname>[email protected]</operatorname>
      </merchant>
      <transactionreference>72-9-80003</transactionreference>
      <timestamp>2019-12-17 09:17:58</timestamp>
      <error>
        <message>Ok</message>
        <code>0</code>
      </error>
      <fraud>
        <rating>0</rating>
      </fraud>
      <authcode>TEST35</authcode>
      <security>
        <postcode>0</postcode>
        <securitycode>2</securitycode>
        <address>0</address>
      </security>
    </record>
    <record type="AUTH">
      <acquirerresponsecode>00</acquirerresponsecode>
      <operation>
        <splitfinalnumber>1</splitfinalnumber>
        <sitereference>test_site12345</sitereference>
        <interface>CERT-XML-XML</interface>
        <accounttypedescription>ECOM</accounttypedescription>
      </operation>
      <settlement>
        <settleduedate>2019-12-17</settleduedate>
        <settlebaseamount>1050</settlebaseamount>
        <settlestatus>0</settlestatus>
      </settlement>
      <billing>
        <dcc enabled="0"/>
        <amount currencycode="GBP">1050</amount>
        <payment type="VISA">
          <issuer>SecureTrading Test Issuer1</issuer>
          <expirydate>10/2022</expirydate>
          <pan>411111######1111</pan>
          <issuercountry>US</issuercountry>
        </payment>
      </billing>
      <live>0</live>
      <merchant>
        <tid>27882788</tid>
        <merchantcountryiso2a>GB</merchantcountryiso2a>
        <merchantname>Test Merchant</merchantname>
        <operatorname>[email protected]</operatorname>
      </merchant>
      <transactionreference>72-9-80004</transactionreference>
      <timestamp>2019-12-17 09:18:00</timestamp>
      <error>
        <message>Ok</message>
        <code>0</code>
      </error>
      <fraud>
        <rating>0</rating>
      </fraud>
      <authcode>TEST06</authcode>
      <security>
        <postcode>0</postcode>
        <securitycode>2</securitycode>
        <address>0</address>
      </security>
    </record>
    <found>2</found>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <timestamp>2019-12-17 09:19:00</timestamp>
  </response>
  <secrand>IDBpVj</secrand>
</responseblock>

 

Info

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:

 


 

Additional resources