Process overview
Request types
When reading this document, you will need to be aware of three different types of request that are processed:
- Firstly, a THREEDQUERY request is processed, which is used to perform 3-D Secure authentication.
- Secondly, an ACCOUNTCHECK request is processed, where AVS and Security Code Checks are performed. This acts as a parent to all subsequent automated payments in this series.
Account Checks 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.
- Finally, a SUBSCRIPTION request is processed, which is used to tell our subscription engine when to process the subsequent automated payments.
Update the JWT payload
You will need to update the payload within the JWT to submit the requests outlined above and to also contain additional fields specific to the Subscription process.
The transaction
When the customer taps “Pay” on your checkout form, the customer is authenticated with 3-D Secure. Following this, an ACCOUNTCHECK is processed and future payments are scheduled in our subscription engine. Funds will not be reserved on the customer’s account immediately. The first payment will be processed automatically by our subscription engine at a later time, at the intervals designated in your request. All payments are processed automatically by our subscription engine. The number of subsequent payments to be processed is defined in the JWT.
Subscription with immediate payment
If you need the first payment to be processed immediately, click here for documentation on an alternative process that supports this.
Configuration
Update the JWT
You will need to update the JWT payload to contain additional fields that provide the information needed to schedule the subscription following the initial request.
Example
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencycode":"GBP",
"sitereference":"test_site12345",
"subscriptiontype":"RECURRING",
"subscriptionunit":"MONTH",
"subscriptionfrequency":"1",
"subscriptionnumber":"1",
"subscriptionfinalnumber":"12",
"subscriptionbegindate":"2020-01-01",
"credentialsonfile":"1",
"requesttypedescriptions":["THREEDQUERY","ACCOUNTCHECK","SUBSCRIPTION"]
},
"iat":"1567701632",
"iss":"jwt.user"
}
Field specification
| Field | Format | Description | |
| 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) Note: No funds are reserved as part of the ACCOUNTCHECK. The first payment will either be processed on the specified subscriptionbegindate or after the first interval has passed (e.g. 1 MONTH or 7 DAY). |
|
| credentialsonfile | Numeric (1) |
Submit value “1” to indicate the credentials submitted in the initial request are being stored for subsequent subscription payments. Note: Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use. Click here for further information. If your system fails to submit this value in the request, our system will automatically attempt to flag the request with the correct credentialsonfile value. If you are processing a new subscription using previously-stored credentials, you must still submit credentialsonfile = 1, to indicate the credentials will continue to be stored for payments in this specific subscription sequence. |
|
| currencyiso3a | Alpha (3) |
The currency assigned to each payment in the subscription sequence. |
|
| requesttypedescriptions | List | This must be set to [“THREEDQUERY”,”ACCOUNTCHECK”,”SUBSCRIPTION”]. | |
| subscriptionbegindate | Date YYYY-MM-DD |
This field refers to the when the first automated payment will be processed. From there onward, we will use the data submitted in the subscriptionunit and subscriptionfrequency fields to automatically process the subscription payments at regular intervals.
e.g. If a subscription request is submitted on 5th January 2018 the interval is 1 MONTH (subscriptionfrequency = 1 and subscriptionunit = MONTH) and subscriptionbegindate is 2018-01-08, the first automated payment will be processed on 8th January 2018, and all subsequent payments will be processed on the 8th of each month. If you do not submit the subscriptionbegindate, we will use the subscriptionunit and subscriptionfrequency fields above to automatically schedule the first automated payment. Monthly subscriptions scheduled at the end of the month are processed on the 28th day. If the date of the first automated payment is the 29th, 30th or 31st day, all subsequent payments will be processed on the 28th day in subsequent months. This is to prevent issues for subscription payments on months that have fewer days than others. |
|
| subscriptionfinalnumber | Numeric (5) |
This is used to set the number of payments to be processed over the course of the subscription: When processing a combined ACCOUNTCHECK SUBSCRIPTION request: If subscriptionnumber = 1 Note: If the subscriptionfinalnumber value is “0”, the subscription engine will schedule payments indefinitely until the user manually sets the subscription to Inactive. |
|
| subscriptionfrequency | Numeric (11) |
Combined with unit, the frequency defines how frequently payments are processed. e.g. For one payment every 7 days: subscriptionfrequency = 7 and subscriptionunit = DAY e.g. For one payment every 2 months: subscriptionfrequency = 2 and subscriptionunit = MONTH |
|
| subscriptionnumber | Numeric (5) |
|
|
| subscriptiontype | Alpha (11) |
This field indicates the type of subscription to be processed. Your system can submit these two values:
*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. |
|
| subscriptionunit | Alpha (5) |
This field represents the unit of time between each subscription. This can be either “DAY” or “MONTH”. Note: It is imperative that this field is submitted to the gateway in CAPITALS (“DAY” or “MONTH”). |
|
| 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 within 24 hours, providing the ACCOUNTCHECK didn’t encounter an error. |
Handling the response
After the customer has completed the payment session, you will receive a single response JWT consisting of the THREEDQUERY, ACCOUNTCHECK and SUBSCRIPTION responses.
Every JWT returned from the SDK should be verified before continuing. We provide a parsing utility that makes it easier to convert the JWT to a transaction response object. Click here for an example on how to use this.
-
When checking the THREEDQUERY response:
- We recommend following the checks outlined on the JSON Web Token page to check the response.
-
When checking the ACCOUNTCHECK response:
- It is important that this request is successful (check the errorcode is “0”). Otherwise, our subscription engine will not schedule payments.
-
When checking the SUBSCRIPTION response:
- It is important that this request is successful (check the errorcode is “0”). Any other errorcode values indicate that the subscription has not been scheduled.
- The subscription-specific fields (as described here) should reflect the values submitted in the request. These dictate how frequently automated payments are to be processed by the subscription engine, the amount the customer will be debited and when the subscription will complete.
Managing the subscription
Start of the automated payments
The first automated payment will be processed as follows:
- If subscriptionbegindate has been specified, the first automated payment will be processed on this date.
- If subscriptionbegindate has not been specified, the first automated payment will be processed after the interval specified in the request has passed (e.g. 1 MONTH or 7 DAY).
Keeping track of your subscriptions
-
You can sign into MyST and monitor your scheduled subscriptions from there. You can view payments that have been processed already and also view future payments that have been scheduled in our subscription engine.
Click here for further information.
-
You can opt in to receive email reports or URL notifications whenever automated subscription payments have been processed on your account.
Click here for further information.
-
You can submit a TRANSACTIONQUERY request, passing through the transactionreference returned in the SUBSCRIPTION section of the initial response. The TRANSACTIONQUERY response returned includes fields that hold information about future scheduled payments.
Click here for further information.
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:
-
You can sign into MyST and manage your scheduled subscriptions from there.
Click here for further information.
-
You can submit a TRANSACTIONUPDATE request, passing through the transactionreference returned in the SUBSCRIPTION section of the initial response.
Click here for further information.
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).
