Querying subscriptions


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.


In order to view details of a subscription that has already been scheduled, you can submit a TRANSACTIONQUERY request, passing through the transactionreference of the SUBSCRIPTION. The response returned includes fields that hold information about future scheduled payments.


Request example

The structure of the request is the same as a standard TRANSACTIONQUERY request.

You must pass through the transaction reference of the original SUBSCRIPTION, and not the transaction references of any authorisations processed automatically by the subscription engine.

import securetrading
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
query = {
  "requesttypedescriptions": ["TRANSACTIONQUERY"],
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"12-3-2"}]
strequest = securetrading.Request()
stresponse = st.process(strequest) #stresponse contains the transaction response

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

$configData = array(
  'username' => '[email protected]',
  'password' => 'Password1^',

$requestData = array(
    'requesttypedescriptions' => array('TRANSACTIONQUERY'),
    'filter' => array(
        'sitereference' => array(array('value' => 'test_site12345')),
        'transactionreference' => array(array('value' => '12-3-2'))

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

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"],
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"12-3-2"}]
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONQUERY"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"12-3-2"}]}}]}
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONQUERY">

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

Response example

After you have successfully submitted a TRANSACTIONQUERY request, you will be returned a response. The response has a similar structure to that of a standard TRANSACTIONQUERY response, with the inclusion of additional subscription fields.

In cases of subscriptionnumber having a higher value than the subscriptionfinalnumber in the response, this represents a completed subscription, and no further authorisations will be processed.

  u 'requestreference': u 'A1wqmc662',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2017-09-28 07:41:14',
        u 'errormessage': u 'Ok',
        u 'errorcode': u '0',
        u 'records': [{
          u 'transactionstartedtimestamp': u '2018-02-01 00:00:00',
          u 'parenttransactionreference': u '23-9-80027',
          u 'interface': u 'PASS-JSON-JSON',
          u 'subscriptionnumber': u '2',
          u 'livestatus': u '0',
          u 'errorcode': u '0',
          u 'baseamount': u '1050',
          u 'sitereference': u 'test_site12345',
          u 'subscriptionfinalnumber': u '12',
          u 'subscriptionunit': u 'MONTH',
          u 'transactionreference': u '1-2-345679',
          u 'paymenttypedescription': u 'VISA',
          u 'transactionactive': u '2',
          u 'orderreference': u 'My_Order_123',
          u 'subscriptiontype': u 'RECURRING',
          u 'accounttypedescription': u 'RECUR',
          u 'updatereason': u 'subscription',
          u 'requesttypedescription': u 'SUBSCRIPTION',
          u 'expirydate': u '10/2031',
          u 'currencyiso3a': u 'GBP',
          u 'subscriptionbegindate': u '2018-01-01',
          u 'maskedpan': u '411111######1111',
          u 'errormessage': u 'Ok',
          u 'subscriptionfrequency': u '1',
          u 'operatorname': u '[email protected]'
        u 'found': u '1',
        u 'requesttypedescription': u 'TRANSACTIONQUERY'
array(3) {
  ["requestreference"] => string(9) "A48adkmtv"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(6) {
      ["transactionstartedtimestamp"] => string(19) "2017-09-28 07:41:14"
      ["errormessage"] => string(2) "Ok"
      ["errorcode"] => string(1) "0"
      ["records"] => array(1) {
          [0] => array(25) {
              ["transactionstartedtimestamp"] => string(19) "2018-02-01 00:00:00"
              ["parenttransactionreference"] => string(10) "23-9-80027"
              ["interface"] => string(14) "PASS-JSON-JSON"
              ["subscriptionnumber"] => string(1) "2"
              ["livestatus"] => string(1) "0"
              ["errorcode"] => string(1) "0"
              ["baseamount"] => string(4) "1050"
              ["sitereference"] => string(14) "test_site12345"
              ["subscriptionfinalnumber"] => string(2) "12"
              ["subscriptionunit"] => string(5) "MONTH"
              ["transactionreference"] => string(10) "1-2-345679"
              ["paymenttypedescription"] => string(4) "VISA"
              ["transactionactive"] => string(1) "2"
              ["orderreference"] => string(12) "My_Order_123"
              ["subscriptiontype"] => string(9) "RECURRING"
              ["accounttypedescription"] => string(5) "RECUR"
              ["updatereason"] => string(12) "subscription"
              ["requesttypedescription"] => string(12) "SUBSCRIPTION"
              ["expirydate"] => string(7) "10/2031"
              ["currencyiso3a"] => string(3) "GBP"
              ["subscriptionbegindate"] => string(10) "2018-01-01"
              ["maskedpan"] => string(16) "411111######1111"
              ["errormessage"] => string(2) "Ok"
              ["subscriptionfrequency"] => string(1) "1"
              ["operatorname"] => string(23) "[email protected]"
        ["found"] => string(1) "1"
        ["requesttypedescription"] => string(16) "TRANSACTIONQUERY"
{"requestreference":"W23-b6m1wubf","version":"1.00","response":[{"transactionstartedtimestamp":"2017-09-28 07:41:14","errormessage":"Ok","errorcode":"0","records":[{"transactionstartedtimestamp":"2018-02-01 00:00:00","parenttransactionreference":"23-9-80027","interface":"PASS-JSON-JSON","subscriptionnumber":"2","livestatus":"0","errorcode":"0","baseamount":"1050","sitereference":"test_site12345","subscriptionfinalnumber":"12","subscriptionunit":"MONTH","transactionreference":"1-2-345679","paymenttypedescription":"VISA","transactionactive":"2","orderreference":"My_Order_123","subscriptiontype":"RECURRING","accounttypedescription":"RECUR","updatereason":"subscription","requesttypedescription":"SUBSCRIPTION","expirydate":"10\/2031","currencyiso3a":"GBP","subscriptionbegindate":"2018-01-01","maskedpan":"411111######1111","errormessage":"Ok","subscriptionfrequency":"1","operatorname":"[email protected]"}],"found":"1","requesttypedescription":"TRANSACTIONQUERY"}],"secrand":"WP6R1la0A"}
<?xml version="1.0" encoding="utf-8"?>
<responseblock version="3.67">
  <response type="TRANSACTIONQUERY">
    <timestamp>2016-03-11 10:05:52</timestamp>
    <record type="SUBSCRIPTION">
        <operatorname>[email protected]</operatorname>
        <payment type="VISA">
        <subscription type=”RECURRING”>
        <amount currencycode="GBP">1000</amount>
      <timestamp>2016-03-05 00:00:00</timestamp>


Field specification

Like a standard TRANSACTIONQUERY response, the response contains an errorcode, and other basic fields relating to the TRANSACTIONQUERY, at the highest level. The response will contain a record, and nested within this record is information on the SUBSCRIPTION. The fields returned within this record are described below:

Field Format Description
XPath: /record/error/code
Numeric (1-5) This provides an indication of whether the initial SUBSCRIPTION request was processed successfully.

  • If the error code is “0” then the SUBSCRIPTION was processed successfully.
  • If the error code is not “0” then the SUBSCRIPTION was not processed successfully.

Click here for a full list of errorcode and message values.

XPath: /record/billing/payment/active
Numeric (1) The subscription status.

“0” – Inactive: Payments suspended until manually overridden (click here for information on updating subscriptions).

“1” – Active: Subscription is active. Payments will be processed at regular intervals.

“2” – Pending (default): Subscription payments on hold until the following condition is met:

  • Subscription payments will only be processed once the first AUTH settles successfully (settlestatus “100”).
XPath: /record/@type
Alpha (20) This will be “SUBSCRIPTION”.
XPath: /record/operation/sitereference
& underscore (50)
The site reference the subscription is being processed through.
XPath: /record/billing/subscription/begindate
Date YYYY-MM-DD For information on the use of subscription fields, please refer to our Subscription Engine documentation.
XPath: /record/billing/subscription/finalnumber
Numeric (5)
XPath: /record/billing/subscription/frequency
Numeric (11)
XPath: /record/billing/subscription/number
Numeric (5)
XPath: /record/billing/subscription/@type
Alpha (10)
XPath: /record/billing/subscription/unit
Alpha (10)
XPath: /record/transactionreference
Alphanumeric including
hyphens (25)
The transaction reference value associated with the SUBSCRIPTION request.