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.

#!/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"}],
    "transactionreference": [{"value":"12-3-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')),
    'transactionreference' => array(array('value' => '12-3-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"}],
      "transactionreference": [{"value":"12-3-2"}]
    }
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["TRANSACTIONQUERY"],
    "filter":{
      "sitereference":[{"value":"test_site12345"}],
      "transactionreference":[{"value":"12-3-2"}]
    }
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="TRANSACTIONQUERY">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>12-3-2</transactionreference>
    </filter>
  </request>
</requestblock>

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 '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 'webservices@example.com'
}],
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) "webservices@example.com"
        }
      }
      ["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":"webservices@example.com"
    }],
    "found":"1",
    "requesttypedescription":"TRANSACTIONQUERY"
  }],
  "secrand":"WP6R1la0A"
}

<responseblock version="3.67">
  <requestreference>X78030262</requestreference>
  <response type="TRANSACTIONQUERY">
    <found>1</found>
    <timestamp>2016-03-11 10:05:52</timestamp>
    <record type="SUBSCRIPTION">
      <merchant>
        <orderreference>My_Order_123</orderreference>
        <operatorname>webservices@example.com</operatorname>
      </merchant>
      <transactionreference>1-2-345679</transactionreference>
      <billing>
        <payment type="VISA">
          <expirydate>10/2031</expirydate>
          <active>2</active>
          <pan>4111########1111</pan>
        </payment>
        <subscription type=”RECURRING”>
          <finalnumber>12</finalnumber>
          <begindate>2016-02-05</begindate>
          <number>2</number>
          <frequency>1</frequency>
          <unit>MONTH</unit>
        </subscription>
        <amount currencycode="GBP">1000</amount>
      </billing>
      <timestamp>2016-03-05 00:00:00</timestamp>
      <live>0</live>
      <error>
        <message>Ok</message> 
        <code>0</code>
      </error>
      <operation>
        <parenttransactionreference>23-9-80027</parenttransactionreference>
        <interface>CERT-XML-XML</interface>
        <sitereference>test_site12345</sitereference>
        <accounttypedescription>RECUR</accounttypedescription>
      </operation>
      <settlement>
        <updatereason>subscription</updatereason>
      </settlement>
    </record>
    <error>
      <message>Ok</message> 
      <code>0</code>
    </error>
  </response>
  <secrand>SC48</secrand>
</responseblock>

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
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.
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”).
requesttypedescription XPath: /record/@type	Alpha (20)	This will be “SUBSCRIPTION”.
sitereference XPath: /record/operation/sitereference	Alphanumeric & underscore (50)	The site reference the subscription is being processed through.
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.
subscriptionfinalnumber XPath: /record/billing/subscription/finalnumber	Numeric (5)
subscriptionfrequency XPath: /record/billing/subscription/frequency	Numeric (11)
subscriptionnumber XPath: /record/billing/subscription/number	Numeric (5)
subscriptiontype XPath: /record/billing/subscription/@type	Alpha (10)
subscriptionunit XPath: /record/billing/subscription/unit	Alpha (10)
transactionreference XPath: /record/transactionreference	Alphanumeric including hyphens (25)	The transaction reference value associated with the SUBSCRIPTION request.

Further reading on this topic