Contents

Updating subscriptions

In order to update or cancel a subscription, you can submit a TRANSACTIONUPDATE request, passing through the transactionreference of the SUBSCRIPTION.

Info
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 request example

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).


#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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' => 'webservices@example.com',
  '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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
 
?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"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"
            }
}]}'

Warning
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 deactivate the existing subscription and submit a new request, including the transactionreference of the parent (in order to use the same billing details). Submit one of the following requests:

 

  1. Submit a new AUTH SUBSCRIPTION request on the day of the month you would like automated payments to be processed going forward.
  2. Submit a new ACCOUNTCHECK SUBSCRIPTION request, including the subscriptionbegindate that you would like automated payments to be processed going forward.

 

Deactivate subscription request example

In order to deactivate an active subscription, the transactionactive field in the TRANSACTIONUPDATE request must be set to “0“. The following example request is for deactivating an active subscription:


#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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' => 'webservices@example.com',
  '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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
 
?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
},
  "updates":{"transactionactive":"0"}
}]}'

 

Start subscription request example

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

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

#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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' => 'webservices@example.com',
  '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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
 
?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-345679"}]
},
  "updates":{"transactionactive":"1"}
}]}'

Warning
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 activated, 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 deactivate the existing subscription and submit a new request, including the transactionreference of the parent (in order to use the same billing details). Submit one of the following requests:

 

  1. Submit a new AUTH SUBSCRIPTION request on the day of the month you would like automated payments to be processed going forward.
  2. Submit a new ACCOUNTCHECK SUBSCRIPTION request, including the subscriptionbegindate that you would like automated payments to be processed going forward.
Info
A subscription will never process payments if the subscriptionnumber is greater than the subscriptionfinalnumber. In order to reactivate a subscription in such a case, you must also specify a higher subscriptionfinalnumber in the TRANSACTIONUPDATE 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.


{
  u 'requestreference': u 'A3jbd6w7a',
    u 'version': u '1.00',
    u 'responses': [{
      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"
  ["responses"] => 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"
}

 

Field specification

Key

 

The following fields relate to the type of request submitted:

Field name Type Length Request Response Description
errorcode 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 Alphanumeric 255 This is the corresponding message to the above code.Click here for a full list of errorcode and message values.
requesttypedescriptions Alpha 20 * You must submit “TRANSACTIONUPDATE”, as shown in the request example.

*In the response, the field ‘requesttypedescription’ is returned instead e.g. “requesttypedescription”: “TRANSACTIONUPDATE”

sitereference Alphanumeric including
underscore
50 The site reference the subscription is being processed through.
subscriptionfinalnumber 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 deactivated.
subscriptionunit 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.

subscriptionfrequency 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.

transactionactive 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 Alphanumeric including hyphens 25 The transaction reference value associated with the SUBSCRIPTION request.
transactionstartedtimestamp Date time YYYY-MM-DD hh:mm:ss 19 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 1st of each month to the 15th), you must deactivate the existing subscription and submit a new request, passing through the updated subscription details, and including the transactionreference of the parent (in order to use the same billing details). There are two approaches we support in this scenario:

  1. Submit a new AUTH SUBSCRIPTION request on the day of the month you would like automated payments to be processed going forward.
  2. Submit a new ACCOUNTCHECK SUBSCRIPTION request, including the subscriptionbegindate that you would like automated payments to be processed going forward.