Contents

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.

Info
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 = "[email protected]"
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' => '[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);
var_dump($response->toArray());

?>
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"],
  "filter":{
    "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">
    <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.

Info
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">
  <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>[email protected]</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 the Subscription engine page.
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.