Querying subscriptions

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 = "webs[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 = Securetradingapi($configData);
$response = $api->process($requestData);

curl --user [email protected]:Password1^ -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"}],
    "currencyiso3a": [{"value":"GBP"}],
    "transactionreference": [{"value":"12-3-2"}]


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 'responses': [{
      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"
  ["responses"] => 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"


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 name Type Length Response Description
errorcode 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.

sitereference Alphanumeric including
50 The site reference the subscription is being processed through.
requesttypedescription Alpha 20   This will be “SUBSCRIPTION”.
transactionreference Alphanumeric including hyphens  25 The transaction reference value associated with the SUBSCRIPTION request.
subscriptiontype Alpha  10 For information on the use of subscription fields, please refer to the Subscription engine page.
subscriptionfinalnumber Numeric 5
subscriptionunit Alpha 5
subscriptionfrequency Numeric 11
subscriptionbegindate Date
 transactionactive 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 conditions are met:

  • If initial request was an AUTH SUBSCRIPTION:
    Subscription payments will only be processed once the first AUTH settles successfully (settlestatus “100”).
  • If initial request was an ACCOUNTCHECK SUBSCRIPTION:
    Provided that the ACCOUNTCHECK was successful, the transactionactive will be updated to the value “1” within 24 hours, indicating the subscription is “Active”.