Recurring Payment schedule management

Lean's Payment Scheduler allows you to perform backend requests at anytime to update and manage your schedule entities.

• The client can pause, resume or cancel schedule at anytime
• The client can fetch a list of upcoming that returns a paginated list of upcoming (not yet executed) payments for a schedule.
• The client can fetch a paginated list of the scheduled payments belonging to a schedule, optionally
  filtered by status and due-date range.
• The client can update a schedule by cancelling a schedule and creating a new schedule

Pause, Resume and Cancel operations

1. Pause a schedule — POST /schedules/v1/{schedule_id}/pause
   • Pauses an active schedule. No payments are attempted until it is resumed.
   • Pausing does not pause the underlying consent — other AoF payments under the consent are unaffected.
   • Behaviour of payments whose due dates fall inside the paused window: check the schedule's /payments list after resuming — occurrences may be reported as SKIPPED rather than retroactively executed.
2. Resume a schedule — POST /schedules/v1/{schedule_id}/resume
   • Resumes a paused schedule; payments are attempted again from the next due date. Same optional reason body and same response shape as pause, with status returning to ACTIVE.
3. Cancel a schedule — POST /schedules/v1/{schedule_id}/cancel
   • Cancels a schedule permanently. No further payments will be attempted, and cancellation cannot be undone — to restart collection you must register a new schedule.
   • Same optional reason body; response returns status: CANCELLED.
   • Cancelling a schedule does not revoke the consent. If the customer wants to fully withdraw authorisation, revoke the consent as well (via your manageConsents() integration or the Revoke a consent API).
   • Cancel in-flight payments are not clawed back: a payment already in PROCESSING may still complete. Reconcile via /payments after cancelling.

Fetch list of upcoming payments

List upcoming payments — GET /schedules/v1/{schedule_id}/upcoming-payments

• Returns a paginated, forward-looking list of payments that have not yet been executed: due_date, amount and the reference that will be applied. Filter with fromDate / toDate (inclusive).
• This is the projection of the plan — ideal for showing customers their future payment calendar and for pre-notifying them (a common compliance / dunning best practice) ahead of each collection.
• For open-ended recurring schedules, use fromDate/toDate to bound the window rather than paging indefinitely.

Fetch list of scheduled payments

List scheduled payments — GET /schedules/v1/{schedule_id}/payments

• Returns the paginated, stateful record of the schedule's payments — past and pending — each with scheduled_payment_id, occurrence_index (zero-based position within the schedule), due_date, amount, reference, status, attempt_count and updated_at. Filter by status and fromDate / toDate.
• This endpoint is your reconciliation backbone. Filter by status=FAILED daily to feed your dunning/retry process, and status=COMPLETED to confirm collections.
• Distinguish this from /upcoming-payments: upcoming payments are the plan; this endpoint is the ledger of concrete occurrences and their outcomes.

Fetch scheduled payment details

GET /schedules/v1/{schedule_id}/payments/{scheduled_payment_id} returns the current view of a single scheduled payment, including its identity within the schedule, due date, amount, reference, status and number of recorded attempts.

• Returns the current view of a single scheduled payment: identity within the schedule (occurrence_index), due_date, amount, reference, status, attempt_count, created_at and updated_at.

Fetch schedule history

GET /schedules/v1/{schedule_id}/history returns a paginated list of lifecycle events for a schedule. Each event has an event_id, type, timestamp and a type-dependent event payload.

• Use history as your audit trail: when a schedule was created, paused, resumed, cancelled or blocked, and why. Surface it in internal support tools.
• Treat the event payload as schemaless (type-dependent) — parse defensively.