Updating 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 update or cancel a subscription, you can submit a TRANSACTIONUPDATE request, passing through the transactionreference of the SUBSCRIPTION.

The subscriptionbegindate and subscriptionnumber fields can never be updated.

Request examples

The structure of the request used when updating subscriptions is the same as a standard TRANSACTIONUPDATE request, with the addition of subscription-specific fields. Please refer to the examples below for further information.

Update subscription

This following example request would update the baseamount of the subscription to 100 (£1.00), the frequency of payments to once every 7 days, and the subscriptionfinalnumber to be 24 (which will change the total number of subscriptions processed).

Python
PHP
cURL
Raw JSON
Raw XML

#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
   
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
   },
  "updates":{"baseamount":"100",
             "subscriptionfrequency":"7",
             "subscriptionunit":"DAY",
             "subscriptionfinalnumber":"24"
            }
}
   
strequest = securetrading.Request()
strequest.update(update)
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('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-345679'))
),
'updates' => array(
  'baseamount' => '100',
  'subscriptionfrequency' => '7',
  'subscriptionunit' => 'DAY',
  'subscriptionfinalnumber' => '24'
)
);
 
$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": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
},
  "updates":{"baseamount":"100",
             "subscriptionfrequency":"7",
             "subscriptionunit":"DAY",
             "subscriptionfinalnumber":"24"
            }
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-345679"}]},"updates":{"baseamount":"100","subscriptionfrequency":"7","subscriptionunit":"DAY","subscriptionfinalnumber":"24"}}]}

<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>17-9-2</transactionreference>
    </filter>
    <updates>
      <billing>
        <amount>2000</amount>
        <subscription>
          <finalnumber>12</finalnumber>
          <frequency>1</frequency>
          <unit>MONTH</unit>
        </subscription>
	</billing>
    </updates>
  </request>
</requestblock>

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

Caution: It is possible to increase the subscriptionfinalnumber field, to extend a subscription. However, if this is done after a subscription has completed, all payments that would have been taken if the subscription had been allowed to continue, are immediately processed.

e.g. If a £10/month subscription has completed, and five months after completion, the subscriptionfinalnumber is raised by five, five £10 payments will be processed in the next settlement run (usually within the next 24 hours).

To extend a subscription with the same billing details, without “catching up” with payments, you must stop the existing subscription and submit a new request, including the transactionreference of the parent (in order to use the same billing details). Submit the following request:

Submit a new AUTH SUBSCRIPTION request on the day of the month you would like automated payments to be processed going forward.

Temporarily disable subscription

In order to temporarily disable an active subscription, the transactionactive field in the TRANSACTIONUPDATE request must be set to “0“, as shown in the following example:

Inactive subscriptions can be re-enabled at a later date.

Refer to the Enable subscription section below for an example.

Python
PHP
cURL
Raw JSON
Raw XML

#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
   
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
   },
  "updates":{"transactionactive":"0"}
}
   
strequest = securetrading.Request()
strequest.update(update)
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('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-345679'))
),
'updates' => array('transactionactive' => '0')
);
 
$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": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
},
  "updates":{"transactionactive":"0"}
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-345679"}]},"updates":{"transactionactive":"0"}}]}

<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>12-64-1</transactionreference>
    </filter>
    <updates>
      <billing>
        <payment>
          <active>0</active>
        </payment>
      </billing>
    </updates>
  </request>
</requestblock>

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

Enable subscription

In order to enable a pending or inactive subscription, the transactionactive field in the TRANSACTIONUPDATE request must be set to “1“.

Updating a pending subscription (transactionactive of “2”) to be active will ignore the results of any fraud or duplicate checks on the initial AUTH request.

Python
PHP
cURL
Raw JSON
Raw XML

#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
   
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
   },
  "updates":{"transactionactive":"1"}
}
   
strequest = securetrading.Request()
strequest.update(update)
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('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-345679'))
),
'updates' => array('transactionactive' => '1')
);
 
$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": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
},
  "updates":{"transactionactive":"1"}
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-345679"}]},"updates":{"transactionactive":"1"}}]}

<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>12-64-1</transactionreference>
    </filter>
    <updates>
      <billing>
        <payment>
          <active>1</active>
        </payment>
      </billing>
    </updates>
  </request>
</requestblock>

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

Caution: Upon activating a pre-existing subscription, all payments that would have been taken during the period the subscription was pending or inactive are immediately processed.

e.g. If a £10/month subscription is pending or inactive for four months and then enabled, four £10 payments will be processed in the next settlement run (usually within the next 24 hours).

To continue a subscription with the same billing details, without “catching up” with payments, you must stop the existing subscription and submit a new request, including the transactionreference of the parent (in order to use the same billing details). Submit the following request:

Submit a new AUTH SUBSCRIPTION request on the day of the month you would like automated payments to be processed going forward.

A subscription will never process payments if the subscriptionnumber is greater than the subscriptionfinalnumber. In order to enable a subscription in such a case, you must also specify a higher subscriptionfinalnumber in the TRANSACTIONUPDATE request.

Permanently stop subscription

In order to permanently stop a subscription, the transactionactive field in the TRANSACTIONUPDATE request must be set to “3“, as shown in the following example:

Stopped subscriptions are permanently cancelled and cannot be re-enabled at a later date.

If you do need to continue the subscription, you will need to submit an entirely new AUTH SUBSCRIPTION request.

Python
PHP
cURL
Raw JSON
Raw XML

#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
   
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
   },
  "updates":{"transactionactive":"3"}
}
   
strequest = securetrading.Request()
strequest.update(update)
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('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-345679'))
),
'updates' => array('transactionactive' => '3')
);
 
$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": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
},
  "updates":{"transactionactive":"3"}
}]}'

{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-345679"}]},"updates":{"transactionactive":"3"}}]}

<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <sitereference>test_site12345</sitereference>
      <transactionreference>12-64-1</transactionreference>
    </filter>
    <updates>
      <billing>
        <payment>
          <active>3</active>
        </payment>
      </billing>
    </updates>
  </request>
</requestblock>

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

Field specification

The following fields relate to the type of request submitted:

Field	Format	Description
requesttypedescriptions XPath: /@type	Alpha (20)	You must submit “TRANSACTIONUPDATE”, as shown in the request example.
sitereference XPath: /filter/sitereference	Alphanumeric & underscore (50)	The site reference the subscription is being processed through.
subscriptionfinalnumber XPath: /updates/billing/subscription/finalnumber	Numeric (5)	subscriptionfinalnumber represents the position of the last payment in a series of subscription payments. Once this number has been reached, no further payments will be processed. Updating this field will change the amount of subscription payments processed in total. Example of updates we support: Changing how many subscription payments will be processed: Updating the subscriptionfinalnumber field from 6 to 10 will result in 4 additional payments being scheduled. Changing a subscription so that it will continue indefinitely: Updating the subscriptionfinalnumber field from 6 to 0 will result in the subscription continuing indefinitely until it is disabled manually.
subscriptionfrequency XPath: /updates/billing/subscription/frequency	Numeric (11)	subscriptionfrequency is the number of units that should occur before the next authorisation is processed. It is used in conjunction with the subscriptionunit field to determine the interval between payments. e.g. updating subscriptionfrequency from 2 to 5, when subscriptionunit is set to “DAY”, changes subscriptions from being processed every 2 days to every 5 days.
subscriptionunit XPath: /updates/billing/subscription/unit	Alpha (5)	subscriptionunit represents the unit of time used to schedule payments (“DAY” or “MONTH”). It is used in conjunction with the subscriptionfrequency field to determine the interval between payments. e.g. updating subscriptionunit from “DAY” to “MONTH”, when subscriptionfrequency is 2, changes subscriptions from being processed every 2 days to every 2 months.
transactionactive XPath: /updates/billing/payment/active	Numeric (1)	You can update the subscription status to one of the following two values: “0” – Inactive: Suspends future payments until manually re-enabled. “1” – Active: Allows subscription payments to continue.
transactionreference XPath: /filter/transactionreference	Alphanumeric including hyphens (25)	The transaction reference value associated with the SUBSCRIPTION request.

Response example

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

Python
PHP
Raw JSON
Raw XML

{
  u 'requestreference': u 'A3jbd6w7a',
    u 'version': u '1.00',
    u 'response': [{
      u 'errorcode': u '0',
      u 'requesttypedescription': u 'TRANSACTIONUPDATE',
      u 'transactionstartedtimestamp': u '2017-09-28 09:32:42',
      u 'errormessage': u 'Ok'
    }]
}

array(3) {
  ["requestreference"] => string(9) "A057aegmt"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(4) {
      ["errorcode"] => string(1) "0"
      ["requesttypedescription"] => string(17) "TRANSACTIONUPDATE"
      ["transactionstartedtimestamp"] => string(19) "2017-09-28 09:32:42"
      ["errormessage"] => string(2) "Ok"
    }
  }
}

{"requestreference":"W23-tkrxwkc6","version":"1.00","response":[{"errorcode":"0","requesttypedescription":"TRANSACTIONUPDATE","transactionstartedtimestamp":"2017-09-28 09:32:42","errormessage":"Ok"}],"secrand":"SptlJutnBnQ"}

<responseblock version="3.67"> 
  <requestreference>X675136983</requestreference> 
  <response type="TRANSACTIONUPDATE"> 
    <timestamp>2010-03-11 16:38:47</timestamp> 
    <error>
      <message>Ok</message> 
      <code>0</code> 
    </error> 
  </response>
  <secrand>9PyI</secrand>
</responseblock>

Field specification

The following fields relate to the type of request submitted:

Field	Format	Description
errorcode XPath: /error/code	Numeric (1-5)	The error code should be used to determine if the update was successful or not. If the error code is “0” then the update was successful. If the error code is not “0” then the update was not successful. Click here for a full list of errorcode and message values.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
requesttypedescription XPath: /@type	Alpha (20)	“TRANSACTIONUPDATE” is returned in the response.
transactionstartedtimestamp XPath: /timestamp	Date time YYYY-MM-DD hh:mm:ss	The time the request was processed.

Update monthly subscription date

To change the date on which a monthly subscription processes payments (e.g. from the 1^st of each month to the 15^th), you must stop the existing subscription and manually submit a new AUTH request (using our Webservices API) on the day of the month you would like automated payments to be processed going forward. You will need to pass through the transactionreference of the parent in order to inherit billing details.