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 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).
#!/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 = \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": ["TRANSACTIONUPDATE"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"1-2-345679"}]
},
"updates":{
"baseamount":"100",
"subscriptionfrequency":"7",
"subscriptionunit":"DAY",
"subscriptionfinalnumber":"24"
}
}]
}'
{
"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"
}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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.
#!/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 = \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": ["TRANSACTIONUPDATE"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"0"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"0"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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.
#!/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 = \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": ["TRANSACTIONUPDATE"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"1"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"1"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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.
#!/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":"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' => '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' => '3')
);
$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": ["TRANSACTIONUPDATE"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"3"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"transactionactive":"3"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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.
Update expiry date
You will need to ensure expiry dates on your active subscriptions are valid and up-to-date, as some issuers may decline cards with outdated card expiry dates. You can update the expiry date on a customer’s card for their scheduled subscription payments by submitting a TRANSACTIONUPDATE request with the field expirydate, which contains the new value.
#!/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":{"expirydate":"05/2025"}
}
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('expirydate' => '05/2025')
);
$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": ["TRANSACTIONUPDATE"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"1-2-345679"}]
},
"updates":{"expirydate":"05/2025"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-345679"}]
},
"updates":{"expirydate":"05/2025"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>12-64-1</transactionreference>
</filter>
<updates>
<billing>
<payment>
<expirydate>05/2025</expirydate>
</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. | |
| expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY | Submit a new expirydate to update the value we will use when processing future scheduled subscription payments. | |
| 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:
|
|
| 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 scheduled payments until manually re-enabled. “1” – Active: Allows scheduled payments to continue. “3” – Stopped: Permanently stops scheduled payments. |
|
| 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.
{
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.
|
|
| errormessage XPath: /error/message |
Alphanumeric (255) |
This is the corresponding message to the above code. |
|
| 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 1st of each month to the 15th, 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.
