Contents

Subscription engine

You can schedule payments to be processed at regular intervals on your behalf by utilising our subscription engine. This is achieved by submitting a single request to our system by following the specification outlined in this topic. Our subscription engine is activated once per day, automatically processing any payments previously-scheduled on your account.

Thumbs up
Subscription payments require no further input from your system to be processed successfully at regular intervals, providing the initial request is processed successfully and has followed our specification.

 


 

Process overview

What will the customer see?

  • During the checkout process, your website prompts the customer for address and card details.
  • Your checkout asks the customer to agree to a subscription, and clearly states when payments will be processed and how much the customer will pay.
  • Once the customer agrees to the subscription, they can click “Pay” and will be shown a confirmation page.

 

How does it work behind the scenes?

  1. Your server submits a request to schedule the subscription.
  2. We return a response and this is checked by your server.
  3. We do the rest: Payments are automatically processed at the intervals specified in the initial request.

 


 

Requirements

 


 

Subscription fields

To schedule the subscription in our subscription engine, you will need to understand the definition of each subscription field.

 

subscriptionunit

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”).

 

subscriptionfrequency

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

Unless specified otherwise, subscriptions start with subscriptionnumber = 1 by default. The subscriptionnumber is automatically incremented in every subsequent subscription payment until it exceeds the value of the subscriptionfinalnumber field, when no further payments will be attempted. A completed subscription is represented by a subscriptionnumber that is higher than the corresponding subscriptionfinalnumber.

Info
We allow you to start a subscription from a higher value than 1. This is to allow you to continue the processing of a previous subscription, while retaining the number of payments that have already been processed.

 

New subscriptions should always start with subscriptionnumber = 1. Only start with a higher value when resuming a previous subscription, with the same payment details.

 

subscriptionfinalnumber

Presuming the subscriptionnumber starts at 1, this number is the total number of payments to be processed over the course of the subscription.

Note: If the value is “0”, the subscription engine will schedule payments indefinitely until the user manually sets the subscription to Inactive.

 

subscriptiontype

This field indicates the type of subscription to be processed. Your system can submit these two values:

  • RECURRING is used when the customer is performing a recurring payment for a new product/service each time (for example, a magazine subscription). For most merchants, the subscriptiontype should be set to “RECURRING”.
  • INSTALLMENT is only used in select cases with certain acquirers. It is designed for when a customer is purchasing a single item, with payment being collected over several installments (for example, paying £100 a month for an item until it has been paid in full).

Note: Installments are only accepted by certain acquirers. For further info, please contact your bank.

 

subscriptionbegindate

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 (as described above) 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.
e.g. In the same scenario as above, but without submitting the subscriptionbegindate, the first automated payment would be processed on 5th February 2018 (1 MONTH after the original request). All subsequent payments will be processed on the 5th of each month.

 


 

Subscription processes

 

We support two different subscription processes:

1
AUTH SUBSCRIPTION

Submitting a combined “AUTH” and “SUBSCRIPTION” request.

 

When the initial request is submitted, the first payment will be processed immediately. After this payment has been settled (settlestatus “100”), we will schedule payments based on the intervals specified in the request, and all subsequent payments will be processed automatically at regular intervals.

 

Click here for further information.

2
ACCOUNTCHECK SUBSCRIPTION

Submitting a combined “ACCOUNTCHECK” and “SUBSCRIPTION” request.

 

When the initial request is submitted, AVS and security code checks will be performed on the customer’s details. No funds will be reserved on the customer’s card. We will schedule payments based on the intervals specified in the request. The first payment will be processed automatically by our subscription engine after the first interval has passed, and all subsequent payments will also be processed automatically at regular intervals.

 

Click here for further information.