Schedule subscription with immediate payment for iOS SDK - using Subscription Engine


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 AUTH request is processed, which is used to process the first payment. This acts as a parent to all subsequent automated payments in this series.
  • 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 SUBSCRIPTION and to also contain additional fields specific to this process.

The transaction

When the customer taps “Pay” on your checkout form, the customer is authenticated with 3-D Secure. Following this, a payment is processed immediately and – following Settlement – future payments are scheduled in our subscription engine. All subsequent payments are processed automatically by our subscription engine. The number of subsequent payments to be processed is defined in the JWT.

  Option to defer the first payment

If you are looking to defer the first payment until after the first interval has passed, click here for documentation on an alternative process that supports this.



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 first payment.




Field specification

  Field Format Description
X1-EN.png 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) 
X1-EN.png 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.

X1-EN.png currencyiso3a  Alpha (3)

The currency assigned to each payment in the subscription sequence.

Click here for a full list of available currencies.

X1-EN.png requesttypedescriptions List This must be set to [“THREEDQUERY”,”AUTH”,”SUBSCRIPTION].
X3-EN.png subscriptionbegindate Date YYYY-MM-DD This field refers to 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.
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.

  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.

X1-EN.png 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 AUTH SUBSCRIPTION request:

If subscriptionnumber = 1
and subscriptionfinalnumber = 12
There will be 12 payments in total (The initial AUTH + 11 subscription payments)

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

X1-EN.png 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

X1-EN.png subscriptionnumber Numeric (5)
  • The AUTH should always start with value “1”, unless resuming a previous subscription (e.g. if you are resuming a previously-cancelled subscription that had 3 payments, you can submit “4” here to carry it on).
  • This number is incremented in each subscription payment.
  • This feature allows you to effectively resume a previous subscription, maintaining the number of payments that were previously processed.
X1-EN.png subscriptiontype Alpha (11) 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 order, with payment being collected over several installments (for example, paying £100 a month for an order until it has been paid in full).

*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.

X1-EN.png 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”).

X3-EN.png 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 after the AUTH has been settled (settlestatus “100”).

  Changing the amount for subsequent subscription payments

You can schedule a subscription for a different amount to that of the initial payment (e.g. initial AUTH is for £5.99 and the SUBSCRIPTION is for £9.99 a month).

  • To do this, you will first need to submit a combined AUTH SUBSCRIPTION request as described above, including the baseamount for the initial payment.
  • Then, process a TRANSACTIONUPDATE request, including the transactionreference of the SUBSCRIPTION, and a new baseamount that contains the value the customer is to be billed during the subscription.


Handling the response

After the customer has completed the payment session, you will receive a single response JWT consisting of the THREEDQUERY, AUTH 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 and AUTH responses:
    • We recommend following the checks outlined on the JSON Web Token page to check the response.
    • Our subscription engine will not schedule payments unless the first payment (AUTH) has been settled successfully (settlestatus is “100”). Until this has occurred, the transactionactive field in the SUBSCRIPTION will have the value “2”, indicating the subscription is “Pending”.
  • 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.

  If the AUTH response indicates the request was successful, funds for the first payment have been reserved on the customer’s account.


Managing the subscription

Start of the automated payments


The first payment will be processed immediately after the initial request is submitted. All subsequent payments will be processed automatically by our subscription engine.

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

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request