TRANSACTIONQUERY for 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.
Read this article to learn more.


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.

Python PHP cURL Raw JSON Raw XML
import securetrading

stconfig = securetrading.Config()
stconfig.username = ""
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

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.

Python PHP Raw JSON Raw XML
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 ''
u 'found': u '1',
u 'requesttypedescription': u 'TRANSACTIONQUERY'


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
X4-EN.png errorcode
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.

X4-EN.png transactionactive
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”).
X4-EN.png requesttypedescription
XPath: /record/@type
Alpha (20) This will be “SUBSCRIPTION”.
X4-EN.png sitereference
XPath: /record/operation/sitereference
& underscore (50)
The site reference the subscription is being processed through.
X4-EN.png subscriptionbegindate
XPath: /record/billing/subscription/begindate
Date YYYY-MM-DD For information on the use of subscription fields, please refer to our Subscription Engine documentation.
X4-EN.png subscriptionfinalnumber
XPath: /record/billing/subscription/finalnumber
Numeric (5)
X4-EN.png subscriptionfrequency
XPath: /record/billing/subscription/frequency
Numeric (11)
X4-EN.png subscriptionnumber
XPath: /record/billing/subscription/number
Numeric (5)
X4-EN.png subscriptiontype
XPath: /record/billing/subscription/@type
Alpha (10)
X4-EN.png subscriptionunit
XPath: /record/billing/subscription/unit
Alpha (10)
X4-EN.png transactionreference
XPath: /record/transactionreference
Alphanumeric including
hyphens (25)
The transaction reference value associated with the SUBSCRIPTION request.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request