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

Process overview

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

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","AUTH","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)
	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. Click here for a full list of available currencies.
	requesttypedescriptions	List	This must be set to [“THREEDQUERY”,”AUTH”,”SUBSCRIPTION].
	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.
	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.
	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)	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.
	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.
	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 after the AUTH has been settled (settlestatus “100”).

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.

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

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 Portal 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 Portal 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 Portal, 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 Portal, or by submitting a TRANSACTIONUPDATE request (you can re-enable a subscription at a later time, if needed).