Recurring Payments status lifecycles

This guide describes the lifecycle of a schedule, scheduled payments and an initiated payment : the status enums, what each status means, and how resources move between them.

There are two levels of state to track, from the plan down to individual executions:

• The schedule status gates everything: payments are only attempted while the schedule is ACTIVE.
• Each scheduled payment is an individual entity that progresses independently as its due date arrives; its terminal status is determined by the outcome of payment initiation attempts in relation to the scheduled payment entity .
• A SUCCEEDED scheduled payment attempt produces an initiated AoF payment, which then follows the standard payment status lifecycle and emits the standard payment.created and payment.updated events
• When the final scheduled payment of a bounded schedule reaches a terminal state, the schedule itself moves to COMPLETED.

Schedule statuses

A schedule is the resource you register and link to an AUTHORISED Account-on-File consent. Its status controls whether payments are attempted on their due dates.

stateDiagram-v2
    PENDING --> ACTIVE
    ACTIVE --> PAUSED
    PAUSED --> ACTIVE
    ACTIVE --> COMPLETED
    ACTIVE --> CANCELLED
    PAUSED --> CANCELLED
    PENDING --> CANCELLED
    ACTIVE --> CONSENT_BLOCKED
    PAUSED --> CONSENT_BLOCKED
    PENDING --> CONSENT_BLOCKED
    CONSENT_BLOCKED --> CANCELLED

• Registration. A newly registered schedule starts in PENDING or ACTIVE — read the status returned by the create call rather than assuming.
• Pause and resume are client-driven. Only you can move a schedule between ACTIVE and PAUSED, via POST /schedules/v1/{schedule_id}/pause and /resume. Both accept an optional reason for your audit trail
• CONSENT_BLOCKED is consent-driven, not client-driven. You cannot set or clear it through the Payment scheduler API — it reflects the state of the underlying AoF consent. Watch consent.status.updated webhooks to know when this happens, then run a re-consent journey with the customer and register a new schedule against the new consent.
• Use links, not assumptions. Every schedule response includes a links object in which cancel, pause and resume appear only when that action is currently available. Drive your UI and your API calls from these links instead of encoding the transition rules yourself.

Scheduled payment statuses

Each schedule entity is made up of individual scheduled payment entities — one per planned occurrence (a due date and an amount). Each moves through its own lifecycle as its due date approaches and execution runs. For each scheduled payment Lean will execute up to 5 reattempts if initial and successive payments fail. You will receive payment status web hook events for each reattempt that is performed.

The scheduled payment entity status model has its own unique status model detailed in the state diagram below.

stateDiagram-v2
    PLANNED --> SCHEDULED
    SCHEDULED --> PROCESSING
    PROCESSING --> COMPLETED
    PROCESSING --> FAILED
    PLANNED --> SKIPPED
    SCHEDULED --> SKIPPED
    SCHEDULED --> EXPIRED
    PLANNED --> CANCELLED
    SCHEDULED --> CANCELLED

• The happy path is PLANNED → SCHEDULED → PROCESSING → COMPLETED.
• Five terminal states. Once a scheduled payment reaches COMPLETED, FAILED, SKIPPED, EXPIRED or CANCELLED, it never changes again. A failed occurrence is not re-created — handle recovery (retry, dunning, customer outreach) in your own flows.
• In-flight payments and cancellation. We do not recommend cancelling a payment that is in PROCESSING because the payment may still complete at the bank. However if try you attempt to cancel a scheduled payment that is already in PROCESSING after cancelling, reconcile via GET /schedules/v1/{schedule_id}/payments.

Account-on-file consent and payment statuses

A SUCCEEDED scheduled payment attempt produces an initiated AoF payment, which then follows the standard payment status lifecycle and emits the standard payment.created and payment.updated web hook events. Read our Payment status lifecycle guide for more details.

The underling consent Account-on-file consent relies on the same consent statuses and consent status web hooks. Read out Account-on-file consent status lifecycle guide for more details

Ensure that you implement web hook-driven state sync on payment.created / payment.updated, resolve the payment to its scheduled payment entity and update local status. Also ensure that you implement consent.status.updated handling for CONSENT_BLOCKED recovery (customer notification + re-consent journey).