The subscription object

It allows you to define recurring payment cycles on one of your "customers". They are defined by setting a subscription model:

Interval unit (day / week / month)
Interval count (distance between two interval counts)
Interraction count (number of times the cycle is repeated)

This object allows you to easily create subscriptions by deciding on the frequency, the duration, the currency, and the subscription model. It allows you to associate one or more subscriptions to a customer, to register one or more cards per customer and to ensure the continuity of the subscription even in case of a change or a card expiration.

For example, you can manage regular schedules, subscription plans for use or pay-as-you-go models, one-time payments in addition to the subscription.

Concretely, the subscription object allows you to define recurring payment cycles with a subscription on one of your customer. You can create them by defining a subscription model.

The "SubscriptionModel" can be defined as objects representing a cost, a currency and a billing cycle.

You can define one or more SubscriptionModel, depending on the range of services and products you offer.

Useful definitions for this part:

SubscriptionModel: template or subscription plan
Subscription: subscription applied to a customer and following a SubscriptionModel
Invoice: option to use if you need to change the value inside a subscription plan
InvoiceItem: line or item included in the invoice. A bill potentially has multiple lines or items

Tutorial

"SubscriptionModel" creation

If you have at your disposal two types of subscription offers, the first one using the basic features of your service and the other one using the advanced features, you will have to create two plans in other words two SubscriptionModel:

On fo the "basic" model plan
One for the "advanced" model plan

Each SubscriptionModel owns its unique ID. You will have to provide this ID value in the API requests when you proceed to a client subscription to a SubscriptionModel.

You can use the following attributes:

IntervalUnit: day / week / month / year
IntervalCount: number of days or weeks or months or years between 2 payments (example: every 10 days or every 3 months)
InterationCount: number of times the cycle is repeated

Example:

If intervalUnit = mois
AND intervalCount = 3
and interationCount = 4

Which means that your subscription model is set up to charge your customer every 3 months for 4 periods (for a total of a 12-month subscription).

"Customer" creation

Like recurring payment methods, the process chain is simplified by using the Customer object. The Customer object allows you to store metadata such as firstName, lastName, or email address. This proper notion allows you initiate transactions on your customer as part of the plan.

"subscription" creation

To finalise the process, you have to link the Customer and the associated SubscriptionModel plan to a new subscription.

Cycles operation

To process each payment automatically, CentralPay creates an invoice for each billing cycle.

Contents of an Invoice:

Describes what the customer has to pay
Displays when the customers are billed or have been billed
Follows the payment status

invoice can be used to add additional InvoiceItems to a bill (to make a discount for example).

From there, all activities are treated automatically. In order to be informed by notifications, you have to create Webhooks while a subscription creation.

Read more about Tutorial
Français

AutoMATIC mode

When a subscription is created, an automatic process starts.

A subscription is periodically settled and relies on the model determined by the IntervalUnit and IntervalCount parameters.

The first transaction, that could be a 3DS one, and that is equivalent to the first part of a subscription, can be:

Done when the subscription is created (by default)
Done later with the startingDate parameter

Note : if the first transaction fails when a subscription is created, the subscription is cancelled and nothing happens.

The following transactions will be launched at the begining of each subsequent period. Those transactions cannot be 3D secure as the cardholder cannot interact to approve the payment.

For each new period (the first one and the following ones), an invoiceitem and an invoice are automatically created for the subscription. At this stage a hook (INVOICE_CREATED) is triggered and send to the merchant.

Note : a transaction will be managed if our platform receives back a HTTP 200 answer from this event at the time indicated by the merchant (in the set up parameters). An option allows the merchant to switch off the HTTP 200 back.

The merchant can perform manual actions between the receipt of the event and the triggering of the transaction.

Read more about AutoMATIC mode
Français

Subscription life cycle

A successful subscription has an ACTIVEe mode.

When a transaction fails, its status switches to FAILURE mode.

Despite of the number of attempts configured, the merchant has to configure a "final status" for the subscription when all attempts have been executed:

FAILURE: invoices for the following periods continue to be created and transactions can be processed
UNPAID: invoices for the following periods continue to be created but transactions are not processed (note: they can be handled manually by the merchant, see "Manual Mode" below)
CANCELED: subscription is cancelled, so nothing will be dealt with in the subscription.

A subscription status gets back to an "ACTIVE" mode, when the last invoice is payed (successful transaction).

Read more about Subscription life cycle
Français

Denial management service

If a transaction of a subscription is denied, you should process it once again in the future.

Thanks to our denial management service, you are able to charge once again a transaction linked to a bill. This process is based on a certain number of attempts and a timelapse between these attempts (you can set up them in your mercahnt portal):

Number of attempts (1, 2, 3 or 4)
Timelapse between each attempts (1, 3, 5 or 7 days)

Read more about Denial management service

Manual mode

You able to execute manual actions at any time to modify the content in a cycle. Proceed this way:

Create a InvoiceItem linked to an existing susbcription. It will be taken into account from the next invoice issued, whether it is created manually or automatically. It can also be directly linked to an invoice, but only if you use certain criteria (see API). This feature allows you to insert in the invoice a line with a positive amount (to increase the invoice amount) or a negative amount (in order to decrease the amount).
Create an "out of period" invoice: the "periodic" invoices are already created by the "automatic" mode, which allows the merchant to create an invoice not included in that period.
Delete an unprocessed InvoiceItem (not linked yet to an invoice)
Cancel a subscription: either immediately or at the end of the current period
Reactivate a subscription that has been identified as "cancelled" at the end of the current period
Close an invoice: no more automatic transactions will be processed
Re-open an invoice: this reactivates automatic transactions
Trigger a payment on an invoice: transactions are made by the automatic system, but this action allows the merchant to immediately force a transaction. Referring to the automatic mode, these "manual" payments do not count as an attempt. This action can be done on a closed invoice.
Update certain data (please refer to the API) of a SubscriptionModel, a subscription, an invoice or/and an InvoiceItem.

Read more about Manual mode
Français

Subscription with Acceptance rules

If you plan to use an acceptance rule, this diagram will help you.

If an acceptance rule triggers a 3DS authentication, you'll receive a 307 HTTP that content the result of a 3DS check Enrollement + your subscriptionId / InvoiceId.
To validate and finalise the subscription, you'll have to POST the subscriptionId and InvoiceId + the 3DS paRes after the cardholder complete its authentication.

Read more about Subscription with Acceptance rules