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 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.
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.
|
|
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 (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. |
|
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. |
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 '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 'webservices@example.com',
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 'webservices@example.com',
u 'settlestatus': u '0'
}],
u 'found': u '2',
u 'requesttypedescription': u 'TRANSACTIONQUERY'
}]
}
array(3) {
["requestreference"] => string(9) "W72-pg3q2he9"
["version"] => string(4) "1.00"
["responses"] => 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) "webservices@example.com"
["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) "webservices@example.com"
["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":"webservices@example.com",
"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":"webservices@example.com",
"settlestatus":"0"
}],
"found":"2",
"requesttypedescription":"TRANSACTIONQUERY"
}],
"secrand":"uISZfw8wKWR"
}
<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>webservices@example.com</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>webservices@example.com</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>
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.