Subscription

The subscription service allows you to automatically process recurring transactions on your customer profiles based on a subscription template defined in advance via the CentralPay API or the Merchant Portal. You can then add due dates or modify the amounts on the fly using the Invoice & Invoice Item services.

This service allows you to generate either card transactions or SDD (SEPA Direct Debit) transactions.

Useful definitions for this section: – SubscriptionModel : subscription template (specifying the subscription amount and frequency) – Subscription : subscription appplied to a customer – Invoice : invoice, use this option if you need to change the amount within a subscription plan – InvoiceItem : line item or item included in the invoice. An invoice may contain multiple line items or items

ℹ️ The "Subscription" service is not the only way to process recurring transaction.
Visit the Recurring card transactions page or the Direct debit transactions page for details by payment method.

1. Create a subscription template (subscriptionModel)

Access:

The subcriptionModel allows you to create different types of subscriptions based on the services you offer. For example, if you have two types of subscription plans available—one that includes the basic features of your service and the other that includes advanced features, you will need to create two models:

• One for the “basic” subscription plan
• One for the “advanced” subscription plan

Each “SubscriptionModel” has a unique ID. You will provide this ID in your API requests when you want to apply a subscription to a customer based on that model.

You can use the following attributes:

• amount : amount to be entered in centimes
• intervalUnit : DAY / WEEK / MONTH / YEAR (day / week / month / year)
• intervalCount : the number of « intervalUnit » units between two due dates (e.g., if intervalUnit = DAY and intervalCount = 10, then there will be a transaction every 10 days)
• iterationCount: number of installments (note that the first transaction is not included in this parameter; it is therefore added to this number)

Example:

• amount = 3000
• intervalUnit = DAY
• intervalCount = 3
• iterationCount = 3

This means your subscription template will be set up to bill your customer 30.00 EUR every 3 days for 4 billing cycles (for a total subscription period of 12 days).

2. Create a subscription (subscription)

To create a subscription, you must first create a Customer that contains at least:

• A Card (if you wish to make card transactions)
• Or a Mandate (if you wish to make card transactions via SEPA direct debit)

You can then create a Subscription:

• Depending on your preferred payment method:
  • for card transactions : enter the customer profile ID “customerId”
  • for transactions via SEPA direct debit : enter the mandate SEPA direct debit ID “mandateId” an enter the desired transaction date in “requestedCollectionDate”
  • for transactions between CentralPay accounts : enter the sender’s account ID “walletId”
• Enter the subscription template ID “subscriptionModelId
• Enter your client’s IP address in “endUserIp”
• Enter your CentralPay point-of-sale ID in the “pointOfSaleId” field

Please note that when a subscription is created, your customer automatically receives an email containing the details of their payment schedule. This email also includes a link to our Customer Portal, where they can view the status of their recurring payments, update their credit card or SEPA direct debit information, and cancel a subscription if necessary.

ℹ️ Customers can cancel their subscription at any time through the customer portal provided to them. Be sure to subscribe to the subscription cancellation webhooks. If your subscription includes a minimum commitment period, it is best to use the recurring payment method or ask CentralPay not to share the link to the customer portal.  

Automating retries in case of failure

If a payment fails to be debited, CentralPay will make additional debit attempts based on the settings defined in the Merchant Portal.

Access:

Field behavior:

• Transaction time: the time at which the direct debit payments will be processed by CentralPay
  • Selection of a value between 4 and 23
• First failed invoice payment: What to do in the event of a first failed direct debit
  • Try again in 1, 3, 5, or 7 days = a new attempt to process the transaction on day+X after the initial transaction
  • Stop = the system will immediately perform the final action, without considering the subsequent actions.
• Second failed invoice payment: What to do in the event of a second failed direct debit
  • Try again in 1, 3, 5 or 7 days = a new attempt to process the transaction on day+X after the previous attempt.
  • Stop = the system will immediately perform the final action, without considering the subsequent actions.
• Third failed invoice payment: What to do in the event of a third failed direct debit
  • Try again in 1, 3, 5 or 7 days = a new attempt to process the transaction on day+X after the previous attempt.
  • Stop = the system will immediately perform the final action, without considering the subsequent actions.
• Final action: What to do if the previous actions failed.
  • CANCELED = Subscription cancelation (changing the subscription status to CANCELED)
  • FAILURE = Subscription failure (subscription status changed to FAILURE)
  • UNPAID = Unpaid subscription (subscription status changed to FAILURE + SUBSCRIPTION_UNPAID hook sent)

4. Subscription cancellation functions

There are two ways to cancel a subscription via the API, the Merchant Portal, or the Customer Portal:

• Cancel: the subscription is canceled immediately
• Cancel at the end of the billing period: The subscription will be canceled at the end of the current billing period (so that the subscriber can continue to use your service during their last paid period). When using the API, you must fill in the “atPeriodEnd” field.
  • Note: During this time, you can reactivate your subscription using the “reactivate” feature in Subscriptions.

ℹ️ Subscriptions for which all payments have been made automatically change to CANCELED status.

5. Change the amount of a subscription payment

CentralPay creates an invoice for each billing cycle of a subscription, based on the associated subscription model (subscriptionModel).

You can take manual actions at any time to modify the billing dates (invoices) for a subscription. Below is a list of possible actions:

• Modify the amount of an invoice installment: The invoiceItem service allows you to modify the amount of an invoice installment by entering a positive or negative amount that will be added to the original installment amount. The invoiceItem will be applied to the next subscription installment, whether it is created manually or automatically. You can also specify a particular installment in your request by providing an invoiceId.
• Create an additional payment due date: so-called “recurring” payment due dates (invoices) are created automatically based on your subscription model. You can create additional one-time payment due dates for your subscription by creating an invoice.
• Delete an unprocessed invoiceItem: if it is not yet linked to an invoice
• Close an upcoming payment due date: if you do not want CentralPay to process a payment (and/or its automatic retry attempts), you can close it using the “close” feature on the invoice. If necessary, you can reopen this payment due date using the “reopen” feature on the invoice if it has not been paid or if there are still scheduled retry attempts remaining.
• Forcing a payment due: transactions are processed automatically by the subscription service; however, you can initiate the transaction in advance or retry it manually using the “pay” feature on the invoice. These “manual” payments are not tracked by the automated retry system. This action can be performed on a closed invoice.

6. Complete guide to creating a subscription