This page explains how to process recurring payments.
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 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
- The customer enters their card details on your secure website or provides their card details over the phone.
- Where card details are entered into your secure website, you must ensure that 3DS authentication is performed.
- 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.
- For high-volume merchants, we strongly recommend that three days before processing a subsequent child request (or where a child request has been declined), 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. Click here for further information.
- Your system can manually submit scheme update and child requests at set intervals (daily, weekly, monthly, yearly) to process new payments. The customer will only be debited after a new child request is submitted.
Benefits of recurring payments
- Payment details need only be provided 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.
Parent request
This section describes the initial request your system will need to process. You can inherit the payment details submitted in this request in subsequent recurring payments.
Configuration of parent request
Expand the relevant section below to learn how to configure the parent request using your preferred interface.
Payment Pages is our fully-hosted checkout solution. If you are unfamiliar with our Payment Pages solution, click here to learn more and get started.
To support the THREEDQUERY then ACCOUNTCHECK flow, Payment Pages customers will need to use the Enhanced Post feature. Click here to learn more.
The THREEDQUERY then AUTH flow is performed by processing a standard, 3-D Secure authenticated transaction using Payment Pages, with additional fields included in the POST, as described below.
<html>
<head>
</head>
<body>
<!--YOUR HTML-->
<form method="POST" action="<DOMAIN>/process/payments/choice">
<input type="hidden" name="credentialsonfile" value="1">
<input type="hidden" name="currencyiso3a" value="USD">
<input type="hidden" name="mainamount" value="100.00">
<input type="hidden" name="sitereference" value="test_site12345">
<input type="hidden" name="sitesecurity" value="hee879a9ab97753b3a768925d50842f10e19fea03fef0b820026b6df92d415866">
<input type="hidden" name="sitesecuritytimestamp" value="2019-05-28 14:22:37">
<input type="hidden" name="stprofile" value="default">
<input type="hidden" name="subscriptionnumber" value="1">
<input type="hidden" name="subscriptiontype" value="RECURRING">
<input type="hidden" name="version" value="2">
<input type="submit" value="Pay">
</form>
</body>
</html>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
| Field | Format | Description | |
| Required | mainamount | Numeric (14) |
The amount associated with this request in main units, with decimal places being separated by commas/decimal point. e.g. £10.99 would be submitted as “10.99” and ¥246 would be submitted as “246”. This amount will be immediately 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. |
| Required | 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. |
| Required | currencyiso3a | Alpha (3) | The transaction currency. This must remain the same in all future child requests processed that inherit from this parent request. |
| Required | 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. |
| Required | sitesecurity |
Site security hash |
Used to submit the request site security hash in the POST. |
| Required | sitesecuritytimestamp |
Date YYYY-MM-DD hh:mm:ss |
As accurately as possible, the timestamp that reflects when the customer’s payment session was initiated. The customer will have 3 hours from the specified time to complete the payment.
Additional considerations:
|
| Required | stprofile |
Alphanumeric (20)
|
Used to specify the styling used to render the Payment Pages. When using the default appearance, this is set to “default”. Click here for further information. |
| Required | subscriptionnumber | Numeric (5) |
Submit “1” to denote the first request in the recurring sequence.
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. |
| Required | 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. Installments are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. 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. |
| Conditional | 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. |
Response
You will need to ensure your system stores the transactionreference field returned in the browser redirect at the end of the checkout session (if configured), and/or the URL notification (if configured), as this must be referenced in the child request that is submitted later.
Our JavaScript Library provides resources to help you quickly build your own streamlined checkout solution on the web. If you are unfamiliar with our JavaScript Library solution, click here to learn more and get started.
- Both the [“THREEDQUERY”,”AUTH”] and [“THREEDQUERY”,”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",
"credentialsonfile":"1",
"currencyiso3a":"GBP",
"requesttypedescriptions":["THREEDQUERY","AUTH"]
"sitereference":"test_site12345",
"subscriptionnumber":"1",
"subscriptiontype":"RECURRING"
},
"iat":1559033849,
"iss":"jwt.user"
}
Field specification
| Field | Format | Description | |
| Required | accounttypedescription | Alpha (20) |
Submit "ECOM" to indicate an e-commerce transaction. We recommend contacting our Support Team for advice on which account type values are supported on your site reference. |
| Required | 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. |
| Required | 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. |
| Required | currencyiso3a | Alpha (3) | The transaction currency. This must remain the same in all future child requests processed that inherit from this parent request. |
| Required | requesttypedescriptions | List |
The request types to be processed. For the parent, this should be either [“THREEDQUERY”,”AUTH”] or [“THREEDQUERY”,”ACCOUNTCHECK”] |
| Required | 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. |
| Required | subscriptionnumber | Numeric (5) |
For the parent [“THREEDQUERY”,”AUTH”] or [“THREEDQUERY”,”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. |
| Required | 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. Installments are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. 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. |
| Conditional | 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. |
Response
The response JWT returned follows the same specification as when processing a standard payment. Of particular importance, your system will need to store the transactionreference returned, as this must be referenced in the child request that is submitted later. Click here to learn about decoding the JWT response.
Our Mobile SDK provides resources to help you quickly build a streamlined checkout solution into your mobile app. If you are unfamiliar with our Mobile SDK solution, click here to learn more and get started.
- Both the [“THREEDQUERY”,”AUTH”] and [“THREEDQUERY”,”ACCOUNTCHECK”] parent requests follow a similar specification to that of a standard payment processed using our Mobile SDK, 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",
"credentialsonfile":"1",
"currencyiso3a":"GBP",
"requesttypedescriptions":["THREEDQUERY","AUTH"]
"sitereference":"test_site12345",
"subscriptionnumber":"1",
"subscriptiontype":"RECURRING",
"termurl":"https://payments.securetrading.net/process/payments/mobilesdklistener"
},
"iat":1559033849,
"iss":"jwt.user"
}
Field specification
| Field | Format | Description | |
| Required | accounttypedescription | Alpha (20) |
Submit "ECOM" to indicate an e-commerce transaction. We recommend contacting our Support Team for advice on which account type values are supported on your site reference. |
| Required | 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. |
| Required | 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 redentialsonfile 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. |
| Required | currencyiso3a | Alpha (3) | The transaction currency. This must remain the same in all future child requests processed that inherit from this parent request. |
| Required | requesttypedescriptions | List |
The request types to be processed. For the parent, this should be either [“THREEDQUERY”,”AUTH”] or [“THREEDQUERY”,”ACCOUNTCHECK”] |
| Required | 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. |
| Required | subscriptionnumber | Numeric (5) |
For the parent [“THREEDQUERY”,”AUTH”] or [“THREEDQUERY”,”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. |
| Required | 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. Installments are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. 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. |
| Required | termurl | URL (1024) |
This URL is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS. You must submit the following URL in this field when performing 3-D Secure: https://payments.securetrading.net/process/payments/mobilesdklistener |
| Conditional | 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. |
Response
The response JWT returned follows the same specification as when processing a standard payment. Of particular importance, your system will need to store the transactionreference returned, as this must be referenced in the child request that is submitted later. Click here to learn about decoding the JWT response.
Our Webservices API is a powerful server-to-server payment processing solution that supports multiple message types. If you are unfamiliar with our Webservices API, click here to learn more and get started.
- The example below is an AUTH request that can be used to process the first payment in the recurring sequence.
- The accounttypedescription is "ECOM" to indicate the transaction was performed using your website.
- If you need to start a recurring payment agreement without processing a payment, you can change the requesttypedescriptions value to "ACCOUNTCHECK".
#!/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",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123",
"cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=",
"eci":"05",
"enrolled":"Y",
"status":"Y",
"threedversion":"2.2.0", "threeddirectorytransactionreference":"f00e1111-0011-00a6-ab00-a00000a00000",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "1",
"credentialsonfile": "1"
}
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',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'cavv' => 'Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=',
'eci' => '05',
'enrolled' => 'Y',
'status' => 'Y',
'threedversion' => '2.2.0',
'threeddirectorytransactionreference' => 'f00e1111-0011-00a6-ab00-a00000a00000',
'subscriptiontype' => 'RECURRING',
'subscriptionnumber' => '1',
'credentialsonfile' => '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": [{
"currencyiso3a": "GBP",
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"baseamount": "1050",
"orderreference": "My_Order_123",
"accounttypedescription": "ECOM",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123",
"cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=",
"eci":"05",
"enrolled":"Y",
"status":"Y",
"threedversion":"2.2.0",
"threeddirectorytransactionreference":"f00e1111-0011-00a6-ab00-a00000a00000",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "1",
"credentialsonfile": "1"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"currencyiso3a":"GBP",
"requesttypedescriptions":["AUTH"],
"sitereference":"test_site12345",
"baseamount":"1050",
"orderreference":"My_Order_123",
"accounttypedescription":"ECOM",
"pan":"4111111111111111",
"expirydate":"12/2020",
"securitycode":"123",
"cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=",
"eci":"05",
"enrolled":"Y",
"status":"Y",
"threedversion":"2.2.0",
"threeddirectorytransactionreference":"f00e1111-0011-00a6-ab00-a00000a00000",
"subscriptiontype":"RECURRING",
"subscriptionnumber":"1",
"credentialsonfile":"1"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<merchant>
<orderreference>My_Order_123</orderreference>
</merchant>
<billing>
<payment>
<expirydate>12/2020</expirydate>
<pan>4111111111111111</pan>
<securitycode>123</securitycode>
</payment>
<amount currencycode="GBP">1050</amount>
<subscription type="RECURRING">
<number>1</number>
</subscription>
</billing>
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
<credentialsonfile>1</credentialsonfile>
</operation>
<threedsecure>
<cavv>Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=</cavv>
<eci>05</eci>
<enrolled>Y</enrolled>
<status>Y</status>
<version>2.2.0</version>
<directorytransactionreference>f00e1111-0011-00a6-ab00-a00000a00000</directorytransactionreference>
</threedsecure>
</request>
</requestblock>
| Field | Format | Description | |
| Required | accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) |
Submit "ECOM" to indicate an e-commerce transaction. |
| Required | baseamount XPath: /billing/amount |
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. Where performing an ACCOUNTCHECK, you must include the maximum amount to be processed in any subsequent child transaction. |
| Required | credentialsonfile XPath: /operation/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. |
| Required | currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The transaction currency. This must remain the same in all future child requests processed that inherit from this parent request. |
| Required | enrolled XPath: /threedsecure/enrolled |
Char (1) | Submit ‘Y’ to indicate that card is enrolled. See below for information on handling not-enrolled cards. |
| Required | expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY | The expiry date printed on the card. |
| Required | pan XPath: /billing/payment/pan |
Numeric (12-19) | This is the long number printed on the front of the customer’s card. |
| Required | requesttypedescriptions XPath: /@type |
List |
The request types to be processed. For the parent, this should be either ["AUTH"] or ["ACCOUNTCHECK"] |
| Required | 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. |
| Required | status XPath: /threedsecure/status |
Char (1) |
Indicates whether or not the customer was authenticated on the card issuer’s ACS.
Successful authentication with status "Y" is required. |
| Required | subscriptionnumber XPath: /billing/subscription/number |
Numeric (5) |
For the parent 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. |
| Required | 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. Installments are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. 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. |
| Conditional | billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. Required for gaming merchants. |
| Conditional | billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. Required for gaming merchants. |
| Conditional | cavv XPath: /threedsecure/cavv |
Alphanumeric (56) |
The unique Cardholder Authentication Verification Value (CAVV) associated with the transaction. Always submit this value when it is available. |
| Conditional | eci XPath: /threedsecure/eci |
Alphanumeric (2) |
The ECI (E-Commerce Indicator) security level associated with the transaction. Always submit this value when it is available. |
| Conditional | threedversion XPath: /threedsecure/version |
Numeric (6) |
Version of 3-D Secure used to authenticate the payment. (e.g. “2.2.0”) Always submit this value when it is available. |
| Conditional | threeddirectorytransactionreference XPath: /threedsecure/directorytransactionreference |
Alphanumeric (48) |
Unique DSTransactionId returned by your MPI provider. Always submit this value when it is available. |
| Conditional | subscriptionfinalnumber XPath: /billing/subscription/finalnumber |
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. |
| Optional | securitycode XPath: /billing/payment/securitycode |
Numeric (3-4) |
This is the 3-digit security code printed on the back of the card. (For AMEX cards, this is a 4-digit code found on the front of the card) This field is not strictly required by Trust Payments, but it is highly recommended for the processing of security code checks. Additionally, some banks may decline the payment if the security code is not present. |
Response
The response returned follows the same specification as a standard AUTH response.
Our Webservices API is a powerful server-to-server payment processing solution that supports multiple message types. If you are unfamiliar with our Webservices API, click here to learn more and get started.
- The example below is an AUTH request that can be used to process the first payment in the recurring sequence.
- The accounttypedescription is "MOTO" to indicate the order was placed over the phone.
- If you need to start a recurring payment agreement without processing a payment, you can change the requesttypedescriptions value to "ACCOUNTCHECK".
#!/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": "MOTO",
"currencyiso3a": "GBP",
"baseamount": "1050",
"orderreference": "My_Order_123",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "1",
"credentialsonfile": "1"
}
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' => 'MOTO',
'currencyiso3a' => 'GBP',
'baseamount' => '1050',
'orderreference' => 'My_Order_123',
'billingfirstname' => 'Joe',
'billinglastname' => 'Bloggs',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'securitycode' => '123',
'subscriptiontype' => 'RECURRING',
'subscriptionnumber' => '1',
'credentialsonfile' => '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": [{
"currencyiso3a": "GBP",
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"baseamount": "1050",
"orderreference": "My_Order_123",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"accounttypedescription": "MOTO",
"pan": "4111111111111111",
"expirydate": "12/2020",
"securitycode": "123",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "1",
"credentialsonfile": "1"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"currencyiso3a":"GBP",
"requesttypedescriptions":["AUTH"],
"sitereference":"test_site12345",
"baseamount":"1050",
"orderreference":"My_Order_123",
"billingfirstname":"Joe",
"billinglastname":"Bloggs",
"accounttypedescription":"MOTO",
"pan":"4111111111111111",
"expirydate":"12/2020",
"securitycode":"123",
"subscriptiontype":"RECURRING",
"subscriptionnumber":"1",
"credentialsonfile":"1"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<merchant>
<orderreference>My_Order_123</orderreference>
</merchant>
<billing>
<payment>
<expirydate>12/2020</expirydate>
<pan>4111111111111111</pan>
<securitycode>123</securitycode>
</payment>
<amount currencycode="GBP">1050</amount>
<subscription type="RECURRING">
<number>1</number>
</subscription>
</billing>
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>MOTO</accounttypedescription>
<credentialsonfile>1</credentialsonfile>
</operation>
</request>
</requestblock>
| Field | Format | Description | |
| Required | accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) |
Submit "MOTO" to indicate a Mail Order Telephone Order transaction. (Note that 3-D Secure authentication is not supported for MOTO transactions) |
| Required | baseamount XPath: /billing/amount |
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. Where performing an ACCOUNTCHECK, you must include the maximum amount to be processed in any subsequent child transaction. |
| Required | credentialsonfile XPath: /operation/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. |
| Required | currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The transaction currency. This must remain the same in all future child requests processed that inherit from this parent request. |
| Required | expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY | The expiry date printed on the card. |
| Required | pan XPath: /billing/payment/pan |
Numeric (12-19) | This is the long number printed on the front of the customer’s card. |
| Required | requesttypedescriptions XPath: /@type |
List |
The request types to be processed. For the parent, this should be either ["AUTH"] or ["ACCOUNTCHECK"] |
| Required | 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. |
| Required | subscriptionnumber XPath: /billing/subscription/number |
Numeric (5) |
For the parent 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. |
| Required | 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. Installments are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. 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. |
| Conditional | billingfirstname XPath: /billing/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. Required for gaming merchants. |
| Conditional | billinglastname XPath: /billing/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. Required for gaming merchants. |
| Conditional | subscriptionfinalnumber XPath: /billing/subscription/finalnumber |
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. |
| Optional | securitycode XPath: /billing/payment/securitycode |
Numeric (3-4) |
This is the 3-digit security code printed on the back of the card. (For AMEX cards, this is a 4-digit code found on the front of the card) This field is not strictly required by Trust Payments, but it is highly recommended for the processing of security code checks. Additionally, some banks may decline the payment if the security code is not present. |
Response
The response returned follows the same specification as a standard AUTH 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 and include this in subsequent child requests.
Child request
This section describes the subsequent recurring payment. This section assumes the parent request described earlier has already been processed.
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.
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.
When a parenttransactionreference from a successful parent "AUTH" or "ACCOUNTCHECK" is included in a child request, Trust Payments will provide the required scheme reference data to Visa and Mastercard.
Please contact our Support Team if you need to include scheme reference data from another processor or process child transactions including a PAN and Expiry. Click here to learn more.
Child request 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 in the parenttransactionreference field.
For those using our JavaScript Library or Mobile SDK to process the parent request, the subsequent response JWT returned will also contain the transactionreference of the THREEDQUERY. You must not submit this in the child request. Instead, you must only submit the transactionreference value associated with 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 = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
auth = {
"sitereference": "test_site12345",
"requesttypedescriptions": ["AUTH"],
"accounttypedescription": "RECUR",
"parenttransactionreference": "12-3-4567",
"baseamount": "1050",
"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' => 'webservices@example.com',
'password' => 'Password1^',
);
$requestData = array(
'sitereference": "test_site12345',
'requesttypedescriptions' => array('AUTH'),
'accounttypedescription' => 'RECUR',
'parenttransactionreference' => '12-3-4567',
'baseamount' => '1050',
'subscriptiontype' => 'RECURRING',
'subscriptionnumber' => '2',
'credentialsonfile' => '2'
);
$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": [{
"sitereference": "test_site12345",
"requesttypedescriptions": ["AUTH"],
"accounttypedescription": "RECUR",
"parenttransactionreference": "12-3-4567",
"baseamount": "1050",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "2",
"credentialsonfile": "2"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"sitereference":"test_site12345",
"requesttypedescriptions":["AUTH"],
"accounttypedescription":"RECUR",
"parenttransactionreference":"12-3-4567",
"baseamount":"1050",
"subscriptiontype":"RECURRING",
"subscriptionnumber":"2",
"credentialsonfile":"2"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>RECUR</accounttypedescription>
<parenttransactionreference>12-3-4567</parenttransactionreference>
<credentialsonfile>2</credentialsonfile>
</operation>
<billing>
<amount>1050</amount>
<subscription type="RECURRING">
<number>2</number>
</subscription>
</billing>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
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).
| Field | Format | Description | |
| Required | accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | This must be set to “RECUR”. |
| Required | 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. |
| Required | 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. |
| Required | requesttypedescriptions XPath: /@type |
Alpha (20) | You must submit “AUTH”, as shown in the request example. |
| Required | 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. |
| Required | 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. |
| Required | 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. Installments are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. |
| Optional | baseamount XPath: /billing/amount |
Numeric (13) |
The amount associated with the child 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. |
| Optional | 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. |
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 | |
| Returned | accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Account type “RECUR” will be returned. |
| Returned | baseamount XPath: /billing/amount |
Numeric (13) |
The amount associated with the child 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”. We recommend checking this amount matches the value you are expecting. The amount returned here reflects the amount the customer will be debited on the child payment. |
| Returned | 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. |
| Returned | currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) |
The currency of the transaction. |
| Returned | parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
The transaction reference of the parent transaction. |
| Returned | requesttypedescription XPath: /@type |
Alpha (20) | Request type “AUTH” will be returned. |
| Conditional | 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. Only returned if supported by your acquiring bank. |
| Conditional | tokenisedpayment XPath: /billing/payment/pan/@tokenised |
Numeric (1) |
If this field is returned with value 1, this indicates the transaction was processed using a token. This field is returned if payment was performed using a token. |
| Conditional | tokentype XPath: /billing/payment/pan/@tokentype |
Alphanumeric (50) |
Used to identify the type of token used for this payment (e.g. “VISATOKEN”). This field is returned if payment was performed using a token. |
| Conditional | walletdisplayname XPath: /billing/payment/wallet/displayname |
Alphanumeric (255) |
This normally contains the last four digits of the customer’s card number (e.g. “1111”). This field is returned if payment was performed using a wallet. |
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.
About the acquirer advice code
The acquirer advice code is a numeric value returned if supported by your acquiring bank, indicating if and when further payments can be processed.
Scheme Update
For high-volume merchants, we strongly recommend that three days before processing a subsequent child request (or where a child request has been declined), 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.
Related articles
Subscription Engine
Submit a single request and we will process recurring payments automatically at regular intervals.
Merchant Initiated Transactions (MIT)
Submit ad-hoc requests to process a transaction from previously stored card details without cardholder interaction.
