Contents

Recurring payments

 

This page explains how to process recurring payments.

Warning
In order to process recurring payments, your merchant ID must be capable of processing recurring or continuous authority payments. If in doubt, we strongly recommend contacting your bank for clarification.

 

Process overview

  1. Customer enters their card details on your secure website.
  2. Your system processes a parent request including either of the following request types: AUTH or ACCOUNTCHECK
  3. When the next payment is due, your system processes a child request that inherits the previously-stored payment, billing and delivery details and seeks authorisation for a new payment.
  4. Your system can submit child requests at various intervals to process new payments. The customer will only be debited after a new request is submitted.

 

Benefits

 

Request SUBSCRIPTION
Alternative solution: Subscriptions

Our subscription solution allows you to submit a single request and we will process recurring payments automatically at regular intervals.

Click here to learn more.

 


 

1. Parent request

This section describes the initial request to be submitted. You can inherit the payment details submitted in this request in subsequent recurring payments.

 

Process overview

The parent request can either be “AUTH” or “ACCOUNTCHECK”. You will need to read the two workflows below and choose the request type that best suits your business requirements:

 

Request AUTH

“AUTH”

 

Checks are performed on the card and billing address.
The first payment is processed immediately.

 

  1. Customer enters their card details and agrees to a subscription.
  2. Your system submits an AUTH request. All payment, billing and delivery details submitted in the request are stored securely in our records for future use.
  3. We will contact the acquiring bank to perform AVS and Security Code Checks, before seeking authorisation for the payment. Funds are reserved immediately on the customer’s bank account.
  4. Your system receives an AUTH response, including the outcome of the request. The response returned contains a unique transaction reference.
  5. To process the second payment at the next interval agreed with the customer, your system submits another AUTH request (that follows the specification described in “2. Child request” below).

Request ACCOUNTCHECK

“ACCOUNTCHECK”

 

Checks are performed on the card and billing address.
Does not process the first payment immediately.

 

Only supported by certain acquiring banks. Please check with our Support team that your chosen acquiring bank supports ACCOUNTCHECKs, before implementing this workflow

 

  1. Customer enters their card details and agrees to a subscription.
  2. Your system submits an ACCOUNTCHECK request. All payment, billing and delivery details submitted in the request are stored securely in our records for future use.
  3. We will contact the acquiring bank to perform AVS and Security Code Checks. Funds are NOT reserved on the customer’s bank account.
  4. Your system receives an ACCOUNTCHECK response with the results of the checks performed. The response returned contains a unique transaction reference.
  5. To process the first payment at the next interval agreed with the customer, your system submits an AUTH request (that follows the specification described in “2. Child request” below).

 

Request example


#!/usr/bin/python
import securetrading

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

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "subscriptiontype": "RECURRING",
  "subscriptionnumber": "1",
  "credentialsonfile": "1",
  "billingpremise": "789",
  "billingpostcode": "TE45 6ST",
  "cachetoken": "token_posted_by_st.js"
}

strequest = securetrading.Request()
strequest.update(auth)
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'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'subscriptiontype' => 'RECURRING',
  'subscriptionnumber' => '1',
  'credentialsonfile' => '1',
  'billingpremise' => '789',
  'billingpostcode' => 'TE45 6ST',
  '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"],
  "sitereference": "test_site12345",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "accounttypedescription": "ECOM",
  "subscriptiontype": "RECURRING",
  "subscriptionnumber": "1",
  "credentialsonfile": "1",
  "billingpremise": "789",
  "billingpostcode": "TE45 6ST",
  "cachetoken": "token_posted_by_st.js"
}]}'

 

Response

The response returned follows the same specification as a standard AUTH or ACCOUNTCHECK response.

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20 The correct account type value for the parent request is dependent on your account configuration. We recommend contacting our Support team for advice on which account type values to submit when processing recurring payments. These values are supported:

  • “ECOM” – e-commerce
  • “MOTO” – Mail or Telephone Order
baseamount Numeric 13 The amount associated with this request in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”.

  • For an initial AUTH request: This amount will be immediately reserved on the customer’s bank account.
  • For an initial ACCOUNTCHECK request: No funds are reserved on the customer’s bank account.

This value will be inherited in all child requests that inherit from this parent request, unless the field is manually overridden.

cachetoken Alphanumeric including hyphen Variable This contains a reference to the customer’s payment details. This is the value posted to your servers after the customer has entered their payment details into your HTML form and clicked “Submit”.
currencyiso3a Alpha 3 The transaction currency. This must remain the same in all future child requests processed that inherit from this parent request.
credentialsonfile Numeric 1 Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use. Following this, you must appropriately identify credentials that are to be stored for later, by assigning a Credentials on File (CoF) flag to signify this. For this reason, you must always submit credentialsonfile with value “1” in the parent request.

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

 

The value submitted here is returned in the response.

requesttypedescriptions Alpha 20  * Submit either “ACCOUNTCHECK” or “AUTH” (see above for info on the distinction between these two types of parent requests). This value is returned in the response.

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

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.
subscriptiontype Alpha 11 This is the type of subscription:

“RECURRING” is for when the customer is making a recurring payment for a new product/service each time.

“INSTALLMENT” is for when a customer is purchasing a single item over several installments (only supported by certain acquirers; contact our Support team for further information).

subscriptionnumber Numeric 1
  • For the parent AUTH request: Submit “1”.
  • For the parent ACCOUNTCHECK request: Submit “1”.

In each subsequent child request, the number submitted must be incremented by 1. For example the second request is “2”, the third is “3”, etc.

 


Your progress

After following the instructions above, you should now be ready to manually process repeat payments. Take the transactionreference returned in the parent response and include this in subsequent child requests by following the instructions below.

 


 

2. Child request

Info
This section describes the subsequent recurring payment. This section assumes you have already processed a parent request as described earlier.
Warning
Before processing a child request, you must ensure that the parent request has completed successfully. Investigate any issues raised and if assistance is required, contact our Support team.

 

About declines: Mastercard has mandated that in cases where a recurring payment has been declined by the card issuer, your system must not retry the request more than once per day for the next 31 days. After this period has passed, your system must not send further requests for the affected customer.

 

Process overview

  1. Your system requests that a new payment is processed by submitting an AUTH request that includes the transactionreference of the parent.
  2. We contact the acquiring bank to seek authorisation for the payment, using the billing and delivery details inherited from the parent request. (Your system does not need to re-submit these details)
  3. Your system receives an AUTH response, including the results of the request.

 

Request examples

The request type submitted for the child request must be “AUTH” (submitted in the requesttypedescriptions field). The AUTH child request follows a similar specification to a standard AUTH request, but is subject to different requirements when employed as part of a recurring payments solution. Refer to the examples and field specification below for further information.

 

Process a new payment inheriting all details from the parent


#!/usr/bin/python
import securetrading

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

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "RECUR",
  "parenttransactionreference": "12-3-4567",
  "subscriptiontype": "RECURRING",
  "subscriptionnumber": "2",
  "credentialsonfile": "3",
  "initiationreason": "A"
}

strequest = securetrading.Request()
strequest.update(auth)
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'),
  'accounttypedescription' => 'RECUR',
  'parenttransactionreference' => '12-3-4567',
  'subscriptiontype' => 'RECURRING',
  'subscriptionnumber' => '2',
  'credentialsonfile' => '3',
  'initiationreason' => 'A'
);

$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": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "RECUR",
  "parenttransactionreference": "12-3-4567",
  "subscriptiontype": "RECURRING",
  "subscriptionnumber": "2",
  "credentialsonfile": "3",
  "initiationreason": "A"
}]}'

Info
The example above assumes that the previous request was the first to be processed, therefore the subscriptionnumber is assigned value “2”. Subsequent child requests are processed with the same structure, incrementing this number each time (i.e. next payment in sequence would be “3”, then “4” and so on).

 

Process a new payment with updated details

The following example is for a child request that inherits all payment, billing and delivery details from a parent, except the expiry date has been updated with a new value.


#!/usr/bin/python
import securetrading

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

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "RECUR",
  "parenttransactionreference": "12-3-4567",
  "subscriptiontype": "RECURRING",
  "subscriptionnumber": "2",
  "credentialsonfile": "3",
  "initiationreason": "A",
  "expirydate": "10/2031"
}

strequest = securetrading.Request()
strequest.update(auth)
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'),
  'accounttypedescription' => 'RECUR',
  'parenttransactionreference' => '12-3-4567',
  'subscriptiontype' => 'RECURRING',
  'subscriptionnumber' => '2',
  'credentialsonfile' => '3',
  'initiationreason' => 'A',
  'expirydate' => '10/2031'
);

$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": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "RECUR",
  "parenttransactionreference": "12-3-4567",
  "subscriptiontype": "RECURRING",
  "subscriptionnumber": "2",
  "credentialsonfile": "3",
  "initiationreason": "A",
  "expirydate": "10/2031"
}]}'

 

 

Field specification
At the bottom of this page, we provide a full list of fields that can be overridden in child requests. Refer to the “Additional notes” section below.

 

Response

The response returned follows the same specification as a standard AUTH response, with the exception of the additional field acquireradvicecode that can be returned (see the field specification below for further information).

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20 This must be set to “RECUR”. This is returned in the response. 
acquireradvicecode Numeric 1 A numeric value returned from the acquiring bank, which is used to indicate whether further payments can be processed. A full mapping of these values can be found in the “Additional notes” section at the bottom of this page.
baseamount Numeric 13 The amount associated with this payment in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”. If you don’t submit this field, the amount processed will be inherited from the preceding parent request.
currencyiso3a Alpha 3 If submitted, this must be the same currency used in the parent request.
credentialsonfile Numeric 1 This is required for Visa and Mastercard transactions where the merchant is utilising Credentials on File (CoF).

For child requests, two values are supported:

  • “2” – A scheduled payment using previously-stored credentials.
  • “3” – An unscheduled payment using previously-stored credentials.

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

The value submitted here is returned in the response.

initiationreason Char 1 This is required for transactions where the merchant is utilising Credentials on File (CoF).

Allows you to assign a reason for re-using previously-stored credentials. As such, this field only needs to be submitted for Merchant Initiated Transactions (MIT).

This field only needs to be submitted when the payment is unscheduled.

The allowed values for this field are “A”, “D”, “S”, “T” and “X”:

  • “A” – Reauthorisation
  • “D” – Delayed Charges
  • “S” – Resubmission
  • “T” – Account top up
  • “X” – No-show (for a hotel booking)

Note: Visa may introduce new values to this list in the future. For further information on these fields, please refer to Visa’s own documentation.

parenttransactionreference Alphanumeric including hyphens 25 You must submit the transactionreference value returned in the parent response. After processing the child request, this value is returned in the parenttransactionreference field of the child response.
requesttypedescriptions Alpha 20  * You must submit “AUTH”, as shown in the request example.

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

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.
subscriptionnumber Numeric 1 This is used to identify a payment’s position within a sequence of recurring transactions.

For each subsequent payment, the number submitted should be incremented by 1 (without gaps).

e.g. 2nd transaction is “2”, 3rd is “3”, then “4” etc.

(You should only increment this number if the previous recurring payment request was successful)

We do not impose limits on the number of payments made against a card.

subscriptiontype Alpha 11 This is the type of subscription:

“RECURRING” is for when the customer is making a recurring payment for a new product/service each time.

“INSTALLMENT” is for when a customer is purchasing a single item over several installments (only supported by certain acquirers; contact our Support team for further information).

 

Info
Mastercard has mandated that in cases where a recurring payment has been declined by the card issuer, you must not retry more than once per day for the next 31 days. After this period has passed, your system must not send further requests for the affected customer.

 


Summary

Following the instructions above, your system should now be able to manually process repeat payments, without needing to re-submit any of the customer’s billing or payment credentials. As always, we strongly recommend thoroughly testing your solution to ensure recurring payments are being processed as expected, before performing live payments on your production system. Please read on for additional information you may find useful when developing a recurring payments solution.

 


 

3. Additional notes

Below are some additional notes to consider when processing recurring payments.

 

Acquirer advice code mapping

The acquirer advice code is a numeric value returned if supported by your acquiring bank, indicating if further payments can be processed. The codes are mapped as follows:

Code Description Action
0 N/A

(Mastercard only)

No action required
1 “New account information available”

The bank has reason to believe that the customer’s card details are out-of-date (e.g. the expiry date has passed).

(Mastercard only)

Please check with the customer that their card details are still correct. This field is advisory and we will allow you to re-process even if the card details are not updated, however the acquiring bank may not accept the payment. You may find it useful to contact your bank in such cases for clarification.
2 “Cannot approve at this time” Try again later. If you are continuing to have difficulties, please contact your acquiring bank.
4 “Do not try again” Do not process further recurring transactions.
8 “Payment blocked by card scheme”

 

3-D secure liability shift

By processing the first AUTH with 3-D Secure, the subsequent recurring payments may also be covered by the benefits of the schemes, depending on your acquirer. Please contact your bank for further information on recurring payments and 3-D Secure.

Click here further information on processing 3-D Secure payments.

 

Payment Pages

If processing your initial parent request through Payment Pages, please ensure your POST to us includes the following:

subscriptionnumber=1

subscriptiontype=RECURRING     (or INSTALLMENT)

 

Updatable fields

When submitting a child request with updated details, the following fields can be overridden with new values:

Field specification
For a full specification of these fields, please refer to the Authorisations page.