Skip to main content
A recurring payment is made up of a mandate (the customer’s consent) and an optional subscription (automated collection on a schedule).

​
Two ways to collect

Every recurring payment is underpinned by a mandate: the customer’s consent, captured once during the first payment (first_in_series) via the mandate options (mandate_options). From there, there are two ways to collect against it:
  • Merchant-controlled: you decide when to collect. Create a next_in_series session yourself, whenever you choose, with no further customer interaction. Collection stays constrained by the mandate options (mandate_options) supplied at consent.
  • Automated: the platform decides when to collect, on a schedule you define. Add subscription options (subscription_options) alongside the mandate options (mandate_options) when creating the mandate. Collection is scheduled and executed automatically, still constrained by those same mandate options.
The mandate is the consent ceiling in both cases; the subscription, when present, simply runs within it. See below for the full detail on each.

Mandates

The consent a customer provides for a merchant to initiate future charges.

Subscriptions

Automated collection on a schedule.
This page covers the supported use cases, which combinations are valid, and which payment methods support each.

​
Evolving from one-time to recurring payments

Adding recurring payments is a small extension to an existing one-time payment (type: one_time) integration, not a new integration project. Checkout redirection and payment handling stay the same: only session creation changes, from type: one_time to type: first_in_series with mandate_options, optionally alongside subscription_options for the automated path. For the automated path, store the returned subscription_id for future management (status checks, cancellation). See below for reference on the similarity:

​
Choosing a use case

Two questions narrow the choice:
  1. Did the customer consent to a recurrence? A recurrence is a rhythm the customer agreed to at consent time (for example, monthly on the 1st).
  2. Should the platform automate collection? Or does the merchant trigger each charge manually?
The use cases below map the answers to a concrete setup: a mandate type (mandate_options.type), optionally combined with subscription_options.

​
Use cases

Subscriptions need a mandate with a consented cadence (scheduled or installment); on_demand has none, so subscription_options isn’t available there.
For configuration payloads, see Mandates: Examples and Subscriptions: Examples. For payment method eligibility per mandate type and full per-method behaviour, see Supported Payment Methods.