Skip to main content
A subscription automates future next_in_series payments within the boundaries of a mandate. When subscription_options is provided on a first_in_series session, the platform schedules and executes recurring collections automatically. The mandate is the consent ceiling; the subscription runs within it.
Providing subscription_options is optional.Omitting it creates the mandate but leaves scheduling to the merchant, who must initiate each next_in_series payment manually.An empty subscription_options is valid and creates a subscription with all properties inherited or defaulted from the mandate: active_period inherits from mandate_options.validity_period, amount infers from mandate_options.amount or the original session amount, and scheduled_time defaults to 00:00.If the mandate has no validity_period, the subscription runs indefinitely.
A subscription’s active_period must fall within the mandate’s validity_period.The platform will not execute a payment that would violate any mandate constraint, regardless of what the subscription schedules.

​
Active Period

Defines the date range within which the subscription is active. Payments are only scheduled within this window. A subscription active throughout 2026: 
{
  "subscription_options": {
    "active_period": {
      "start_date": "2026-01-01",
      "end_date": "2026-12-31"
    }
  }
}
If start_date is omitted, the subscription starts immediately (or inherits from mandate_options.validity_period.start_date). If end_date is omitted, it runs indefinitely (or inherits from mandate_options.validity_period.end_date). The active period must fall within mandate_options.validity_period. The mandate remains the authorisation ceiling and cannot be exceeded.

​
Amount

The fixed amount in the smallest currency unit collected for each scheduled payment. Collecting 20.00 ZAR on each scheduled payment: 
{
  "subscription_options": {
    "amount": 2000
  }
}
If omitted, the amount is inferred in order from: mandate_options.amount (if a fixed amount), then the original session amount.

​
Recurrence

The payment cadence is defined in mandate_options, not in subscription_options. This ensures the recurrence is part of the customer’s consent boundary and is available to providers for deriving implicit period windows. For scheduled and on_demand mandates, recurrence is at mandate_options.recurrence. For installment mandates with terms.type: periodic, it is at mandate_options.terms.recurrence. In both cases the subscription engine uses the same recurrence to schedule payments. See Mandates: Recurrence for the full reference and examples.

​
Scheduled Time

The time of day at which scheduled collections are executed. Specified in 24-hour HH:MM format and evaluated in the timezone set by mandate_options.timezone. Defaults to 00:00 if not specified. Collections executed at 9:00 AM each scheduled day: 
{
  "subscription_options": {
    "scheduled_time": "09:00"
  }
}
For full configuration examples, see Subscription Examples.