Contents

Schedule a subscription with a free trial

 

Process overview

Request types

When reading this document, you will need to be aware of two different types of request that are processed:

  • Firstly, 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.
  • Secondly, a SUBSCRIPTION request is processed, which is used to tell our subscription engine when to process the subsequent automated payments.
Update the Drop-In View Controller

  • You will need to modify typeDescriptions to include ACCOUNTCHECK and SUBSCRIPTION.
  • You will need to update the payload within the JWT to contain additional fields specific to Subscriptions.
The transaction

When the customer taps “Pay” on your checkout form, 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.

External
Subscription without free trial

If you need the first payment to be processed immediately, click here for documentation on an alternative process that supports this.

 


 

Update the Drop-In View Controller

Request types

You will need to modify typeDescriptions to include ACCOUNTCHECK and SUBSCRIPTION, as shown in the following example:


let dropInVC = ViewControllerFactory.shared.dropInViewController(
	jwt: jwt,
	typeDescriptions: [.accountCheck, .subscription],
	payButtonTappedClosureBeforeTransaction: { (controller: DropInController) in},
	successfulPaymentCompletion: {
		(
			jwt: String,
			responses: [JWTResponseObject],
			successMessage: String,
			cardReference: TPCardReference?
		)
	in},
	transactionFailure: {
		(
			jwt: String?,
			responses: [JWTResponseObject]?,
			errorMessage: String,
			error: NSError?
		)
	in}
)

 

Update the JWT

You will need to update the payload within the JWT to contain additional fields that provide the information needed to schedule the subscription following the ACCOUNTCHECK.

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"},"iat":"1567701632","iss":"jwt.user"}

 

Field specification

Key

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.

Click here for a full list of available currencies.

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

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

and subscriptionfinalnumber = 12
There will be 11 payments in total (The initial ACCOUNTCHECK + 11 subscription payments)

(The initial ACCOUNTCHECK counts against the final number)

Note: If the 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 ACCOUNTCHECK 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).

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

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.

 

 


 

Response

As with a standard payment, you will need to decode the JWT returned and check the fields contain the correct information in regards to subscription timing and amount, and in particular, that the transactionactive field contains the value you are expecting.

 

The response is divided into two parts:

 


{"iat":1561549076,"payload":{"requestreference":"A0dcb11e6","version":"1.00","response":[{"transactionstartedtimestamp":"2017-09-27 15:11:14","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2017-09-27","errorcode":"0","baseamount":"1050","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"1-2-345678","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"ACCOUNTCHECK","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST50","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","credentialsonfile":"1","settlestatus":"0"},{"transactionstartedtimestamp":"2020-01-01 00:00:00","parenttransactionreference":"23-9-80025","livestatus":"0","errorcode":"0","orderreference":"My_Order_123","subscriptionfinalnumber":"12","subscriptionunit":"MONTH","transactionreference":"1-2-345679","paymenttypedescription":"VISA","transactionactive":"2","baseamount":"1050","subscriptiontype":"RECURRING","accounttypedescription":"RECUR","requesttypedescription":"SUBSCRIPTION","currencyiso3a":"GBP","subscriptionbegindate":"2020-01-01","maskedpan":"411111######1111","errormessage":"Ok","subscriptionnumber":"2","subscriptionfrequency":"1","operatorname":"[email protected]"}],"secrand":"PAGPFy57L"}}

 

 

Managing the subscription

Start of the automated payments

The first automated payment will be processed as follows:

 

Keeping track of your subscriptions

 

 

Updating the subscription

 


 

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 using MyST. 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” using MyST (you can re-enable a subscription at a later time, if needed).