Skip to main content
Version: 0.0.1

Recurring Payments

What are recurring payments?​

Recurring payments charge a previously tokenised payment method on a schedule — for example, a monthly subscription, an annual renewal, or a weekly instalment. Zenith supports recurring payments against stored cards and PayTo mandates.

How the pattern works​

Recurring billing in Zenith follows a two-step pattern:

  1. Tokenise the payment method once. The customer enters their card or bank details on a hosted flow (Hosted Checkout Mode 1 or the REST API tokenisation endpoint) and Zenith returns a token.
  2. Charge the token on your schedule. Each scheduled charge is a normal payment request using the stored token — Zenith processes it as a new transaction and returns the usual result via callback, webhook, and API.

The merchant is responsible for running the schedule. Zenith does not manage subscription cadence, trial periods, or plan logic — those live in your billing system.

Payment methods for recurring​

Card tokenisation​

Card-on-file recurring charges are the most common pattern. Tokenise the card once via Hosted Checkout Mode 1 or the REST API, then charge the token on your schedule. Scheme rules require the first charge to be customer-initiated — subsequent charges are merchant-initiated transactions (MIT) which Zenith flags appropriately to the card networks.

PayTo mandates​

PayTo supports recurring charges via the stored mandate. Unlike card tokenisation, PayTo mandates can be paused or cancelled by the customer in their banking app at any time. Your recurring billing loop must handle mandate state changes by subscribing to the webhook and checking payToStatus before each scheduled charge.

See Payment Methods → PayTo for mandate lifecycle details.

CML charges​

If the customer has a CML entity with a payment method stored with Zenith, you can use their customerReference to take payments via the /v2/payments API.

Handling failed recurring charges​

Declined recurring payments are routine due to events like expired cards, insufficient funds or paused mandates. Your system should:

  • Detect decline reasons from the callback or API response
  • Apply a retry policy appropriate for the decline type (immediate retry for soft declines, deferred retry for insufficient funds, no retry for hard declines)
  • Notify the customer when retries are exhausted and ask them to update their payment method
  • Pause the subscription until a new token is captured
  • Accept unexpected error messages, which may change from time to time

Merchant responsibilities​

  • Maintain the schedule and trigger each charge on time
  • Handle decline retries in your billing system
  • Track mandate/token state via webhooks and periodic API checks
  • Communicate with customers about upcoming charges, failures, and payment method updates
  • Stay compliant with scheme rules for card-on-file and mandate rules for PayTo
Last updated on by Ian Menethil