Contents

Transaction queries

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 transactionreference “1-20-4” would return details of the request with that reference (if it is exists and has 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

You can specify as many filters as required. We recommend being as specific as reasonably possible, in order to avoid returning an excessive number of records in the response.

A maximum of 500 records can be returned in a single response.

 

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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/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"}]
  }
}]}'

 

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.

 

Key

Field name Type Length Request Description
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 Email 255 The customer’s billing email address. Maximum length of 255 (maximum of 64 characters before the ”@” symbol).
billingfirstname Alphanumeric including
symbols
127 The customer’s billing first name.
billinglastname 127 The customer’s billing last name.
billingpostcode 25 The customer’s billing postcode.
billingpremise 20 The number or name of the premise of the customer’s billing address.
billingstreet 20 The street name of the customer’s billing address.
currencyiso3a Alpha 3 The currency that the transaction will be processed in (three character currency code). Click here for a full list of currency codes.
customerip IP address 39 The IP address of the customer.
endtimestamp Date Time YYYY-MM-DD HH:MM:SS 19 Only requests processed before the timestamp specified will be returned.

Must be in the format YYYY-MM-DD HH:MM:SS.

orderreference Alphanumeric including
symbols
255 Unique reference number supplied by the merchant for the initial request.
pan Numeric 12-19 This is the card number printed on the front of the customer’s card.
parenttransactionreference Alphanumeric including
hyphens
25 Unique reference of the parent request.
paymenttypedescription Alpha 20 The customer’s card type (e.g. “VISA” or “MASTERCARD”). Click here for a full list of payment types.
requesttypedescription Alpha 20 The request type associated with transaction. For example, “AUTH” or “REFUND”. Click here for a full list of request types.
sitereference Alphanumeric including
underscores
50 The site reference that processed the transaction.
starttimestamp Date Time YYYY-MM-DD HH:MM:SS 19 Only requests processed after the timestamp specified will be returned.

Must be in the format YYYY-MM-DD HH:MM:SS.

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 'A1wqmc662',
    u 'version': u '1.00',
    u 'responses': [{
      u 'transactionstartedtimestamp': u '2016-12-06 15:00:00',
        u 'errormessage': u 'Ok',
        u 'errorcode': u '0',
        u 'records': [{
          u 'transactionstartedtimestamp': u '2016-12-06 11:00:00',
            u 'sitereference': u 'test_site12345',
            u 'interface': u 'PASS-JSON-JSON',
            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 'orderreference': u 'My_Order_123',
            u 'tid': u '27882788',
            u 'securityresponsepostcode': u '0',
            u 'transactionreference': u '23-9-1',
            u 'merchantname': u 'Test Merchant',
            u 'paymenttypedescription': u 'VISA',
            u 'baseamount': u '1050',
            u 'accounttypedescription': u 'ECOM',
            u 'fraudrating': u '0',
            u 'acquirerresponsecode': u '00',
            u 'requesttypedescription': u 'AUTH',
            u 'expirydate': u '10/2017',
            u 'securityresponsesecuritycode': u '2',
            u 'currencyiso3a': u 'GBP',
            u 'authcode': u 'TEST36',
            u 'settlebaseamount': u '1050',
            u 'errormessage': u 'Ok',
            u 'merchantcountryiso2a': u 'GB',
            u 'maskedpan': u '411111######1111',
            u 'securityresponseaddress': u '0',
            u 'issuercountryiso2a': u 'US',
            u 'operatorname': u 'webservices@example.com',
            u 'settlestatus': u '0'
        }, {
          u 'transactionstartedtimestamp': u '2016-12-06 11:00:00',
            u 'sitereference': u 'test_site12345',
            u 'interface': u 'PASS-JSON-JSON',
            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 'orderreference': u 'My_Order_123',
            u 'tid': u '27882788',
            u 'securityresponsepostcode': u '0',
            u 'transactionreference': u '23-9-2',
            u 'merchantname': u 'Test Merchant',
            u 'paymenttypedescription': u 'VISA',
            u 'baseamount': u '1050',
            u 'accounttypedescription': u 'ECOM',
            u 'fraudrating': u '0',
            u 'acquirerresponsecode': u '00',
            u 'requesttypedescription': u 'AUTH',
            u 'expirydate': u '10/2017',
            u 'securityresponsesecuritycode': u '2',
            u 'currencyiso3a': u 'GBP',
            u 'authcode': u 'TEST19',
            u 'settlebaseamount': u '200',
            u 'errormessage': u 'Ok',
            u 'merchantcountryiso2a': u 'GB',
            u 'maskedpan': u '411111######1111',
            u 'securityresponseaddress': u '0',
            u 'issuercountryiso2a': u 'US',
            u 'operatorname': u 'webservices@example.com',
            u 'settlestatus': u '0'
        }],
        u 'found': u '2',
        u 'requesttypedescription': u 'TRANSACTIONQUERY'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A48adkmtv"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(6) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-06 15:00:00"
      ["errormessage"] => string(2) "Ok"
      ["errorcode"] => string(1) "0"
      ["records"] => array(2) {
          [0] => array(32) {
              ["updatereason"] => string(6)  "settle"
              ["transactionstartedtimestamp"] => string(19) "2016-12-06 11:00:00"
              ["sitereference"] => string(14) "test_site12345"
              ["interface"] => string(14) "PASS-JSON-JSON"
              ["requesttypedescription"] => string(4) "AUTH"
              ["livestatus"] => string(1) "0"
              ["issuer"] => string(26) "SecureTrading Test Issuer1"
              ["dccenabled"] => string(1) "0"
              ["settleduedate"] => string(10) "2016-12-07"
              ["errorcode"] => string(1) "0"
              ["orderreference"] => string(12) "My_Order_123"
              ["baseamount"] => string(4) "1050"
              ["tid"] => string(8) "27882788"
              ["securityresponsepostcode"] => string(1) "0"
              ["transactionreference"] => string(6) "23-9-1"
              ["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"
              ["expirydate"] => string(7) "10/2022"
              ["securityresponsesecuritycode"] => string(1) "2"
              ["currencyiso3a"] => string(3) "GBP"
              ["authcode"] => string(6) "TEST76"
              ["settlebaseamount"] => string(3) "1050"
              ["errormessage"] => string(2) "Ok"
              ["merchantcountryiso2a"] => string(2) "GB"
              ["maskedpan"] => string(16) "411111######1111"
              ["securityresponseaddress"] => string(1) "0"
              ["issuercountryiso2a"] => string(2) "US"
              ["operatorname"] => string(23) "webservices@example.com"
              ["settlestatus"] => string(1) "0"
            }
            [1] => array(32) {
              ["updatereason"] => string(6) "settle"
              ["transactionstartedtimestamp"] => string(19) "2016-12-06 11:00:00"
              ["sitereference"] => string(14) "test_site12345"
              ["interface"] => string(14) "PASS-JSON-JSON"
              ["requesttypedescription"] => string(4) "AUTH"
              ["livestatus"] => string(1) "0"
              ["issuer"] => string(26) "SecureTrading Test Issuer1"
              ["dccenabled"] => string(1) "0"
              ["settleduedate"] => string(10) "2016-12-07"
              ["errorcode"] => string(1) "0"
              ["orderreference"] => string(12) "My_Order_123"
              ["baseamount"] => string(3) "1050"
              ["tid"] => string(8) "27882788"
              ["securityresponsepostcode"] => string(1) "0"
              ["transactionreference"] => string(6) "23-9-2"
              ["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"
              ["expirydate"] => string(7) "10/2022"
              ["securityresponsesecuritycode"] => string(1) "2"
              ["currencyiso3a"] => string(3) "GBP"
              ["authcode"] => string(6) "TEST27"
              ["settlebaseamount"] => string(3) "200"
              ["errormessage"] => string(2) "Ok"
              ["merchantcountryiso2a"] => string(2) "GB"
              ["maskedpan"] => string(16) "411111######1111"
              ["securityresponseaddress"] => string(1) "0"
              ["issuercountryiso2a"] => string(2) "US"
              ["operatorname"] => string(23) "webservices@example.com"
              ["settlestatus"] => string(1) "0"
            }
        }
        ["found"] => string(1) "2"
        ["requesttypedescription"] => string(16) "TRANSACTIONQUERY"
    }
  }
}
{
  "requestreference": "W23-b6m1wubf",
  "version": "1.00",
  "response": [{
    "transactionstartedtimestamp": "2016-12-06 15:00:00",
    "errormessage": "Ok",
    "errorcode": "0",
    "records": [{
      "updatereason": "settle",
      "transactionstartedtimestamp": "2016-12-06 11:00:00",
      "sitereference": "test_site12345",
      "interface": "PASS-JSON-JSON",
      "requesttypedescription": "AUTH",
      "livestatus": "0",
      "issuer": "SecureTrading Test Issuer1",
      "dccenabled": "0",
      "settleduedate": "2016-12-07",
      "errorcode": "0",
      "baseamount": "1050",
      "tid": "27882788",
      "securityresponsepostcode": "0",
      "transactionreference": "23-9-1",
      "merchantname": "Test Merchant",
      "paymenttypedescription": "VISA",
      "orderreference": "My_Order_123",
      "accounttypedescription": "ECOM",
      "fraudrating": "0",
      "splitfinalnumber": "1",
      "acquirerresponsecode": "00",
      "expirydate": "10/2022",
      "securityresponsesecuritycode": "2",
      "currencyiso3a": "GBP",
      "authcode": "TEST65",
      "settlebaseamount": "1050",
      "errormessage": "Ok",
      "merchantcountryiso2a": "GB",
      "maskedpan": "411111######1111",
      "securityresponseaddress": "0",
      "issuercountryiso2a": "US",
      "operatorname": "webservices@example.com",
      "settlestatus": "0"
    }, {
      "updatereason": "webservices@example.com",
      "transactionstartedtimestamp": "2016-12-06 11:00:00",
      "sitereference": "test_site12345",
      "interface": "PASS-JSON-JSON",
      "requesttypedescription": "AUTH",
      "livestatus": "0",
      "issuer": "SecureTrading Test Issuer1",
      "dccenabled": "0",
      "settleduedate": "2016-12-07",
      "errorcode": "0",
      "baseamount": "1050",
      "tid": "27882788",
      "securityresponsepostcode": "0",
      "transactionreference": "23-9-2",
      "merchantname": "Test Merchant",
      "paymenttypedescription": "VISA",
      "orderreference": "My_Order_123",
      "accounttypedescription": "ECOM",
      "fraudrating": "0",
      "splitfinalnumber": "1",
      "acquirerresponsecode": "00",
      "expirydate": "10/2022",
      "securityresponsesecuritycode": "2",
      "currencyiso3a": "GBP",
      "authcode": "TEST85",
      "settlebaseamount": "200",
      "errormessage": "Ok",
      "merchantcountryiso2a": "GB",
      "maskedpan": "411111######1111",
      "securityresponseaddress": "0",
      "issuercountryiso2a": "US",
      "operatorname": "webservices@example.com",
      "settlestatus": "0"
    }],
    "found": "2",
    "requesttypedescription": "TRANSACTIONQUERY"
  }],
  "secrand": "WP6R1la0A"
}

 

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