Contents

AUTH Subscription

Process overview

This subscription process consists of three parts:

1
Submit combined AUTH SUBSCRIPTION request

This immediately processes the first payment and then schedules future payments in our subscription engine.

2
Subscription is active

All subsequent payments are processed automatically by our subscription engine.

3
Finishing the subscription

In the initial request, you can define a finite number of payments (using the subscriptionfinalnumber field), after which our subscription engine will discontinue automatic payments. Alternatively you can allow payments to continue indefinitely and manually disable the subscription when needed.

Alternative processes for your consideration

Before you get started, you may find the following alternative process is better suited to your requirements:

 


 

1. Submit combined AUTH SUBSCRIPTION request

In order to process the first payment immediately, and request that a series of subscription payments be scheduled in our subscription engine, your system will need to submit a request following the specifications outlined below.

 

Request example

When the AUTH SUBSCRIPTION request is submitted, our system will interpret this as two different requests:


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

authsub = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH","SUBSCRIPTION"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "subscriptiontype": "RECURRING",
  "subscriptionunit": "MONTH",
  "subscriptionfrequency": "1",
  "subscriptionfinalnumber": "12",
  "subscriptionbegindate": "2018-01-01",
  "credentialsonfile": "1",
  "cachetoken": "token_posted_by_st.js"
}

strequest = securetrading.Request()
strequest.update(authsub)
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(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH','SUBSCRIPTION'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'subscriptiontype' => 'RECURRING',
  'subscriptionunit' => 'MONTH',
  'subscriptionfrequency' => '1',
  'subscriptionfinalnumber' => '12',
  'subscriptionbegindate' => '2018-01-01',
  'credentialsonfile' => '1',
  'cachetoken' => 'token_posted_by_st.js'
);

$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": [{
  "currencyiso3a": "GBP",
  "requesttypedescriptions": ["AUTH","SUBSCRIPTION"],
  "sitereference": "test_site12345",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "subscriptiontype": "RECURRING",
  "subscriptionunit": "MONTH",
  "subscriptionfrequency": "1",
  "subscriptionfinalnumber": "12",
  "subscriptionbegindate": "2018-01-01",
  "credentialsonfile": "1",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

Response example

In the response, in addition to following our best practices, you will need to check the fields returned contain the correct information in regards to subscription timing and amount, and in particular, that the transactionactive field contains the value you are expecting. The response is divided into two parts:

Info
If the AUTH response indicates the request was successful, funds for the first payment have been reserved on the customer’s account.

{
  u 'requestreference': u 'A0dcb11e6',
    u 'version': u '1.00',
    u 'responses': [{
        u 'transactionstartedtimestamp': u '2017-09-27 15:11:14',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2017-09-27',
        u 'errorcode': u '0',
        u 'baseamount': u '1050',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '1-2-345678',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'orderreference': u 'My_Order_123',
        u 'accounttypedescription': u 'ECOM',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST50',
        u 'errormessage': u 'Ok',
        u 'operatorname': u 'webservices@example.com',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######1111',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'credentialsonfile': u '1',
        u 'settlestatus': u '0'
    }, {
        u 'transactionstartedtimestamp': u '2018-01-01 00:00:00',
        u 'parenttransactionreference': u '23-9-80025',
        u 'livestatus': u '0',
        u 'errorcode': u '0',
        u 'orderreference': u 'My_Order_123',
        u 'subscriptionfinalnumber': u '12',
        u 'subscriptionunit': u 'MONTH',
        u 'transactionreference': u '1-2-345679',
        u 'paymenttypedescription': u 'VISA',
        u 'transactionactive': u '2',
        u 'baseamount': u '1050',
        u 'subscriptiontype': u 'RECURRING',
        u 'accounttypedescription': u 'RECUR',
        u 'requesttypedescription': u 'SUBSCRIPTION',
        u 'currencyiso3a': u 'GBP',
        u 'subscriptionbegindate': u '2018-01-01',
        u 'maskedpan': u '411111######1111',
        u 'errormessage': u 'Ok',
        u 'subscriptionnumber': u '2',
        u 'subscriptionfrequency': u '1',
        u 'operatorname': u 'webservices@example.com'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["responses"] => array(2) {
    [0] => array(29) {
        ["transactionstartedtimestamp"] => string(19) "2017-09-27 15:11:14"
        ["livestatus"] => string(1) "0"
        ["issuer"] => string(26) "SecureTrading Test Issuer1"
        ["splitfinalnumber"] => string(1) "1"
        ["dccenabled"] => string(1) "0"
        ["settleduedate"] => string(10) "2017-09-27"
        ["errorcode"] => string(1) "0"
        ["baseamount"] => string(4) "1050"
        ["tid"] => string(8) "27882788"
        ["merchantnumber"] => string(8) "00000000"
        ["merchantcountryiso2a"] => string(2) "GB"
        ["transactionreference"] => string(10) "1-2-345678"
        ["merchantname"] => string(13) "Test Merchant"
        ["paymenttypedescription"] => string(4) "VISA"
        ["orderreference"] => string(12) "My_Order_123"
        ["accounttypedescription"] => string(4) "ECOM"
        ["acquirerresponsecode"] => string(2) "00"
        ["requesttypedescription"] => string(4) "AUTH"
        ["securityresponsesecuritycode"] => string(1) "2"
        ["currencyiso3a"] => string(3) "GBP"
        ["authcode"] => string(6) "TEST50"
        ["errormessage"] => string(2) "Ok"
        ["operatorname"] => string(23) "webservices@example.com"
        ["securityresponsepostcode"] => string(1) "0"
        ["maskedpan"] => string(16) "411111######1111"
        ["securityresponseaddress"] => string(1) "0"
        ["issuercountryiso2a"] => string(2) "US"
        ["credentialsonfile"] => string(1) "1"
        ["settlestatus"] => string(1) "0"
      }
      [1] =>array(20) {
        ["transactionstartedtimestamp"] => string(19) "2018-01-01 00:00:00"
        ["parenttransactionreference"] => string(10) "1-2-345679"
        ["livestatus"] => string(1) "0"
        ["errorcode"] => string(1) "0"
        ["orderreference"] => string(12) "My_Order_123"
        ["subscriptionfinalnumber"] => string(2) "12"
        ["subscriptionunit"] => string(5) "MONTH"
        ["transactionreference"] => string(9) "23-64-101"
        ["paymenttypedescription"] => string(4) "VISA"
        ["transactionactive"] => string(1) "2"
        ["baseamount"] => string(4) "1050"
        ["subscriptiontype"] => string(9) "RECURRING"
        ["accounttypedescription"] => string(5) "RECUR"
        ["requesttypedescription"] => string(12) "SUBSCRIPTION"
        ["currencyiso3a"] => string(3) "GBP"
        ["subscriptionbegindate"] => string(10) "2018-01-01"
        ["maskedpan"] => string(16) "411111######1111"
        ["subscriptionnumber"] => string(1) "2"
        ["subscriptionfrequency"] => string(1) "1"
        ["operatorname"] => string(23) "webservices@example.com"
    }
  }
}
{
  "requestreference": "W23-wt77f0n8",
  "version": "1.00",
  "response": [{
    "transactionstartedtimestamp": "2017-09-27 15:11:14",
    "livestatus": "0",
    "issuer": "SecureTrading Test Issuer1",
    "splitfinalnumber": "1",
    "dccenabled": "0",
    "settleduedate": "2017-09-27",
    "errorcode": "0",
    "baseamount": "1050",
    "tid": "27882788",
    "merchantnumber": "00000000",
    "merchantcountryiso2a": "GB",
    "transactionreference": "1-2-345678",
    "merchantname": "Test Merchant",
    "paymenttypedescription": "VISA",
    "orderreference": "My_Order_123",
    "accounttypedescription": "ECOM",
    "acquirerresponsecode": "00",
    "requesttypedescription": "AUTH",
    "securityresponsesecuritycode": "2",
    "currencyiso3a": "GBP",
    "authcode": "TEST50",
    "errormessage": "Ok",
    "operatorname": "webservices@example.com",
    "securityresponsepostcode": "0",
    "maskedpan": "411111######1111",
    "securityresponseaddress": "0",
    "issuercountryiso2a": "US",
    "credentialsonfile": "1",
    "settlestatus": "0"
  }, {
    "transactionstartedtimestamp": "2018-01-01 00:00:00",
    "parenttransactionreference": "1-2-345679",
    "livestatus": "0",
    "errorcode": "0",
    "orderreference": "My_Order_123",
    "subscriptionfinalnumber": "12",
    "subscriptionunit": "MONTH",
    "transactionreference": "23-64-101",
    "paymenttypedescription": "VISA",
    "transactionactive": "2",
    "baseamount": "1050",
    "subscriptiontype": "RECURRING",
    "accounttypedescription": "RECUR",
    "requesttypedescription": "SUBSCRIPTION",
    "currencyiso3a": "GBP",
    "subscriptionbegindate": "2018-01-01",
    "maskedpan": "411111######1111",
    "errormessage": "Ok",
    "subscriptionnumber": "2",
    "subscriptionfrequency": "1",
    "operatorname": "webservices@example.com"
  }],
  "secrand": "E0ksvyuH5VKg"
}

 

Field specification

Key

Field name Type Length Request Response Description
requesttypedescriptions Alpha 20  * You must submit “AUTH” and “SUBSCRIPTION”, as shown in the request example.

*In the response, the field ‘requesttypedescription’ is returned in both parts of the response e.g. “requesttypedescription”:”AUTH” and “requesttypedescription”: “SUBSCRIPTION”, respectively.

sitereference Alphanumeric including
underscore
50 The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.
accounttypedescription Alpha 20 The source of the transaction.

  • In the request, this value needs to submitted as “ECOM” or “MOTO“. The value submitted will be returned in the AUTH section of the response.
  • Additionally, in the SUBSCRIPTION section of the response, the accounttypedescription value will be returned as “RECUR“.
currencyiso3a  Alpha 3 The currency assigned to each payment in the subscription sequence.

Click here for a full list of available currencies.

baseamount Numeric 13 The amount to be paid at regular intervals, in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
subscriptiontype Alpha  11 For information on the use of subscription fields, please refer to the Subscription engine page.
subscriptionfinalnumber Numeric 5
subscriptionunit Alpha 5
subscriptionfrequency Numeric 11
subscriptionbegindate Date
YYYY-MM-DD
10
subscriptionnumber Numeric 5
  • By default, the AUTH is assigned a value of “1” and the SUBSCRIPTION is assigned a value of “2”.
  • This number is incremented in each subscription payment.
  • You can override the default starting value of “1” in the AUTH with a higher value.
  • This feature allows you to effectively resume a previous subscription, maintaining the number of payments that were previously processed.
  • The AUTH should always start with value “1”, unless resuming a previous subscription, as mentioned above.
transactionactive Numeric 1 The subscription status.

“0” – Inactive: Suspends future payments until manually overridden. (Refer to information on updating subscriptions below)

“1” – Active: Schedules subscription payments immediately, bypassing fraud & duplicate checks (if enabled).

“2” – Pending (default): Schedules subscription payments after the AUTH has been settled (settlestatus “100”).

credentialsonfile Numeric 1   Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use (e.g. by a Subscription or by processing a re-authorisation). Following this, you must appropriately identify credentials that are to be stored for later, by submitting credentialsonfile with value “1”, to indicate the card details will be re-used as part of the subscription.

Note: The Credentials on File (CoF) mandate only applies for new transactions processed after 30th April 2018. Credentials stored before this date do not need to be updated.

transactionreference Alphanumeric including
hyphens
25 This field is returned in both the AUTH and SUBSCRIPTION response, and is used to uniquely identify both.

It is especially important to take note of the transactionreference returned in the SUBSCRIPTION section of the response, as you will need this if you need to perform any queries or updates on the subscription at a later time.

 

Info
Changing the amount for subsequent subscription payments

You can schedule a subscription for a different amount to that of the initial payment (e.g. initial AUTH is for £5.99 and the SUBSCRIPTION is for £9.99 a month).

  • To do this, you will first need to submit a combined AUTH SUBSCRIPTION request as described above, including the baseamount for the initial payment.
  • Then, process a TRANSACTIONUPDATE request, including the transactionreference of the SUBSCRIPTION, and a new baseamount that contains the value the customer is to be billed during the subscription.

 


 

2. Subscription is active

 

Start of the automated payments

Info
Remember!

The first payment will be processed immediately after the initial request is submitted. All subsequent payments will be processed automatically by our subscription engine.

The first automated payment will be processed as follows:

 

 

Keeping track of your subscriptions

 

 

 

 

Updating the subscription

You can perform updates to active subscriptions in order to change customer’s details, or to cancel/modify the subscription payments. There are two ways to do this:

 

 

 


 

3. Finishing the subscription

Subscriptions can enter either one of these two states:

 

Number of payments exceeded

Once the subscriptionnumber exceeds the subscriptionfinalnumber, our subscription engine will stop processing subscription payments indefinitely.

If you do not need to process further payments from the customer, you do not need to take further action.

If you wish to resume/extend a subscription, you can update the subscriptionfinalnumber to a greater value. You can do this by using MyST, or by submitting a TRANSACTIONUPDATE request. With this update complete, payments will resume processing at their original intervals. If payments have been missed while the subscription payments were not being processed, our subscription engine will catch up with missed payments within 24 hours.

 

Subscription continues indefinitely

If the original request was submitted with subscriptionfinalnumber set to “0”, we will continue to process payments indefinitely until you manually deactivate the subscription.

If you wish to deactivate the subscription, you can do so by updating the transactionactive field to be “0”. You can do this by using MyST, or by submitting a TRANSACTIONUPDATE request (you can re-enable a subscription at a later time, if needed).