Recurring payments
This page explains how to process recurring payments.

If you are unsure, please contact our Support Team for assistance.

Process overview
- Customer enters their card details on your secure website.
- You have configured your payment form to use our JavaScript Library, to process an initial request with either [“THREEQUERY”,”AUTH”] or [“THREEQUERY”,”ACCOUNTCHECK”], using the requesttypedescriptions field. We refer to this as the parent request.
- The customer clicks “Pay” and the JavaScript library handles the request.
- Three days prior to processing a new payment, your system manually submits a scheme update request using our Webservices API, to check if the customer’s payment details are still up-to-date.
- When the next payment is due, your system manually processes a child request using our Webservices API, which inherits the previously-stored payment, billing and delivery details and seeks authorisation for a new payment.
- Your system can manually submit scheme update and child requests at various intervals to process new payments. The customer will only be debited after a new child request is submitted.
Benefits
- Payment details need only be entered by the customer once, at time of purchase.
- Process repeat payments for customers without needing to store their card details on your own system for future use. Payment details are stored securely on our servers.
- A recurring payment is only processed when a request has been submitted by your system. This allows for greater control over when payments are processed, as you are able to define your own interval between each payment.

Our subscription solution allows you to submit a single request and we will process recurring payments automatically at regular intervals.
1. Parent request
This section describes the initial request to be submitted by the JavaScript library. You can inherit the payment details submitted in this request in subsequent recurring payments.
Process overview
The parent request submitted by the JavaScript can either be [“THREEQUERY”,”AUTH”] or [“THREEQUERY”,”ACCOUNTCHECK”]. You will need to read the two workflows below and choose the request type that best suits your business requirements:

[“THREEQUERY”,”AUTH”]
3-D Secure authentication is performed.
Checks are performed on the card and billing address.
The first payment is processed immediately.
- Customer enters their card details and agrees to a subscription.
- The JavaScript library submits a [“THREEQUERY”,”AUTH”] request. All payment, billing and delivery details submitted in the request are stored securely in our records for future use.
- 3-D Secure authentication is performed.
- We will then 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.
- Your system receives a response JWT, including the outcome of the request. The response returned contains a unique transaction reference.
- To process the second payment at the next interval agreed with the customer, your system manually submits another AUTH request using our Webservices API (that follows the specification described in “3. Child request” below).

[“THREEQUERY”,”ACCOUNTCHECK”]
3-D Secure authentication is performed.
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
- Customer enters their card details and agrees to a subscription.
- The JavaScript library submits a [“THREEQUERY”,”ACCOUNTCHECK”] request. All payment, billing and delivery details submitted in the request are stored securely in our records for future use.
- 3-D Secure authentication is performed.
- We will contact the acquiring bank to perform AVS and Security Code Checks. Funds are NOT reserved on the customer’s bank account.
- Your system receives a response JWT, including the results of the checks performed. The response returned contains a unique transaction reference.
- To process the first payment at the next interval agreed with the customer, your system manually submits an AUTH request using our Webservices API (that follows the specification described in “3. Child request” below).
Request example
- Both the [“THREEQUERY”,”AUTH”] and [“THREEQUERY”,”ACCOUNTCHECK”] parent requests follow a similar specification to that of a standard payment processed using our JavaScript Library, but are subject to different requirements when employed as part of a recurring payments solution.
- These changes are made within the payload of the JWT.
- Refer to the example and field specification below for further information.
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","credentialsonfile":"1","subscriptiontype":"RECURRING","subscriptionnumber":"1","requesttypedescriptions":["THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
Field specification
Field | Format | 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:
|
![]() |
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”.
This value will be inherited in all child requests that inherit from this parent request, unless the field is manually overridden. |
![]() |
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.
If you are processing a new recurring payments sequence using previously-stored credentials, you must still submit credentialsonfile = 1 in the parent request, to indicate the credentials will be stored to process future child payments in this sequence. The value submitted here is returned in the response JWT. |
![]() |
currencyiso3a | Alpha (3) | The transaction currency. This must remain the same in all future child requests processed that inherit from this parent request. |
![]() |
requesttypedescriptions | List | The request types to be processed. For the parent, this should be either [“THREEQUERY”,”AUTH”] or [“THREEQUERY”,”ACCOUNTCHECK”] |
![]() |
sitereference | Alphanumeric & 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 (5) | For the parent [“THREEQUERY”,”AUTH”] or [“THREEQUERY”,”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. |
![]() |
subscriptionfinalnumber | Numeric (5) | This is used to set the number of payments to be processed over the course of the subscription.
Note: This field is required for certain acquiring banks on the US platform when the subscriptiontype is “INSTALLMENT” (otherwise the field is optional). Contact our Support Team for further information. |
![]() |
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 order over several installments (only supported by certain acquirers; contact our Support Team for further information). Note: If the subscription type is “INSTALLMENT” and you are processing payments on the US platform, certain acquiring banks also require the field subscriptionfinalnumber is submitted. Contact our Support Team for further information. |
Response
The response JWT returned follows the same specification as when processing a standard payment. Click here to learn about decoding the JWT response.
Your progress
After following the instructions above, you should now be ready to manually process repeat payments using our Webservices API. You can take the transactionreference returned in the response JWT and include this in subsequent child requests.
2. Scheme update
Whenever a participating card issuer re-issues a customer’s card, they submit the new account number and expiry date to the Visa Account Updater (VAU) or Mastercard’s Automatic Billing Updater (ABU) systems, as appropriate. In the days preceding a recurring payment, you can manually submit a SCHEMEUPDATE request to Trust Payments using our Webservices API, and we will contact the VAU and ABU to check for updates. If the payment credentials have been updated, we will store the new details and these will be used in future recurring payments.
Benefits

We only support this functionality with supported acquiring banks.
This functionality must be enabled on your site reference(s) before it can be used. Please contact our Support Team to discuss enabling Scheme updates.
Here’s how it works:
- If a scheme update request is submitted prior to processing a child request, and we successfully retrieve updated payment credentials from the VAU or ABU, the subsequent child request described below will be processed using these new details.
- If a scheme update request is submitted prior to processing a child request, and the payment credentials are already up-to-date, the subsequent child request described below will be processed using the existing details stored.
- If you do not submit a scheme update, the child request described below will be processed using the existing details stored.

(This will open in a new tab)
3. Child request


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
- Your system requests that a new payment is processed, by manually submitting an AUTH request using our Webservices API, which includes the transactionreference of the parent AUTH or ACCOUNTCHECK.

- We contact the acquiring bank to seek authorisation for the payment, using the billing and delivery details inherited from the parent AUTH/ACCOUNTCHECK. (Your system does not need to re-submit these details)
- Your system receives an AUTH response, including the results of the request.
Request
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 example and field specification below for further information.
#!/usr/bin/python import securetrading stconfig = securetrading.Config() stconfig.username = "[email protected]" stconfig.password = "Password1^" st = securetrading.Api(stconfig) auth = { "sitereference": "test_site12345", "requesttypedescriptions": ["AUTH"], "accounttypedescription": "RECUR", "parenttransactionreference": "12-3-4567", "subscriptiontype": "RECURRING", "subscriptionnumber": "2", "credentialsonfile": "2" } 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' => '[email protected]', 'password' => 'Password1^', ); $requestData = array( 'sitereference": "test_site12345', 'requesttypedescriptions' => array('AUTH'), 'accounttypedescription' => 'RECUR', 'parenttransactionreference' => '12-3-4567', 'subscriptiontype' => 'RECURRING', 'subscriptionnumber' => '2', 'credentialsonfile' => '2' ); $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": [{ "sitereference": "test_site12345", "requesttypedescriptions": ["AUTH"], "accounttypedescription": "RECUR", "parenttransactionreference": "12-3-4567", "subscriptiontype": "RECURRING", "subscriptionnumber": "2", "credentialsonfile": "2" }]}'
{"alias":"[email protected]","version":"1.00","request":[{"sitereference":"test_site12345","requesttypedescriptions":["AUTH"],"accounttypedescription":"RECUR","parenttransactionreference":"12-3-4567","subscriptiontype":"RECURRING","subscriptionnumber":"2","credentialsonfile":"2"}]}
<?xml version="1.0" encoding="utf-8"?> <requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>RECUR</accounttypedescription> <parenttransactionreference>12-3-4567</parenttransactionreference> <credentialsonfile>2</credentialsonfile> </operation> <billing> <subscription type="RECURRING"> <number>2</number> </subscription> </billing> </request> </requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.

Field specification
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | This must be set to “RECUR”. |
![]() |
baseamount XPath: /billing/amount |
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. |
![]() |
credentialsonfile XPath: /operation/credentialsonfile |
Numeric (1) | This is required for Visa and Mastercard transactions where the merchant is utilising Credentials on File (CoF).
Submit “2” in this field to indicate the payment is using previously-stored credentials. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | If submitted, this must be the same currency used in the parent request.
If not submitted, this value is inherited from the parent request. |
![]() |
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
You must submit the transactionreference value of the AUTH or ACCOUNTCHECK returned in the response JWT of the initial parent request.
You must not submit the transactionreference value associated with the THREEDQUERY. |
![]() |
requesttypedescriptions XPath: /@type |
Alpha (20) | You must submit “AUTH”, as shown in the request example. |
![]() |
sitereference XPath: /operation/sitereference |
Alphanumeric & 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 XPath: /billing/subscription/number |
Numeric (5) | 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 XPath: /billing/subscription/@type |
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 order over several installments (only supported by certain acquirers; contact our Support Team for further information). |
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
Field | Format | Description | |
![]() |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Account type “RECUR” will be returned. |
![]() |
acquireradvicecode XPath: /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 XPath: /billing/amount |
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”. |
![]() |
credentialsonfile XPath: /operation/credentialsonfile |
Numeric (1) | If the credentialsonfile field has been submitted in the request and it is supported by the acquirer processing the transaction, it is returned in the response. |
![]() |
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency of the transaction. Click here for a full list of available currencies. |
![]() |
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
The transaction reference of the parent transaction. |
![]() |
requesttypedescription XPath: /@type |
Alpha (20) | Request type “AUTH” will be returned. |

Summary
Following the instructions above, your system should now be able to manually process repeat payments using our Webservices API, 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.
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.
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)