Intergrating Recurring Payments

Overview

The Payment scheduler APIs let you register, manage and inspect scheduled payments — recurring or explicitly dated — executed automatically against an AUTHORISED Account-on-File consent. Once a schedule is registered, Lean initiates each payment on its due date on your behalf. No per-payment API call and no customer interaction is required.

The Recurring Payments API is an add-on to your existing Account-on-File integration. It does not replace any part of it — schedules are executed through the Account-on-File consent your customer has already authorized.

Schedule types

Register a schedule - POST/schedules/v1

1. Registers a new schedule against an existing, authorized consent. This is the only write call needed to set up recurring collection — Lean handles payment initiation from here.

   1. RECURRING definition — type, recurrence.unit (DAY / WEEK / MONTH / YEAR), amount (value ≥ 1, currency), optional start_date, optional end_date (open-ended when omitted).

      Recurring definition

      {
        "reference": "SUBSCRIPTION-4711",
        "purpose": "GDS",
        "consent_id": "123e4567-e89b-12d3-a456-426655440000",
        "schedule": {
          "type": "RECURRING",
          "recurrence": { "unit": "MONTH" },
          "amount": { "value": 100.00, "currency": "AED" },
          "start_date": "2026-08-01",
          "end_date": "2027-07-01"
        }
      }

   2. EXPLICIT definition — type and an executions array; each entry has execute_on (date), amount, and an optional per-execution reference that overrides the schedule-level default for that payment.

      Explicit definition

      {
        "consent_id": "123e4567-e89b-12d3-a456-426655440000",
        "purpose": "LNC",
        "schedule": {
          "type": "EXPLICIT",
          "executions": [
            { "execute_on": "2026-08-01", "amount": { "value": 100.00, "currency": "AED" } },
            { "execute_on": "2026-09-01", "amount": { "value": 200.00, "currency": "AED" }, "reference": "INSTALLMENT-2" }
          ]
        }
      }

• Persist schedule_id against the customer and consent in your database — you need it for every subsequent call.
• Only register schedules against consents in the AUTHORISED state. Gate this on the consent.status.updated webhook, not on the redirect outcome alone.
• amount.value must be ≥ 1.

List schedules - GET/schedules/v1

2. Returns a paginated list of schedules for your application. Filter with consentId (uuid) and/or status, plus standard page / size pagination parameters.

   Each summary includes schedule_id, consent_id, type, status, created_at, a plan_summary, and next_payment (the next upcoming execution, when one is scheduled).

   plan_summary is shaped by type:

   • Recurring — amount, period_unit, start_date, end_date.
   • Explicit — planned_count, first_payment_date, last_payment_date.

   Use consentId filtering to render all schedules attached to a consent — e.g. before a customer revokes a consent, show them which active schedules will stop.

Get schedule details - GET/schedules/v1/{schedule_id}

3. Returns the full details of a single schedule: schedule_id, consent_id, application_id, type, status, plan_summary, pending_payment (the currently pending scheduled payment, when one exists), created_at and updated_at.
   1. pending_payment gives you the id, due date, amount and reference of the payment that will be attempted next — useful for "your next payment" UI.
   2. Call this endpoint (or use /history) after lifecycle actions to confirm state, in addition to acting on web hooks.

Payment status and Consent status web hooks

4. Recurring Payments is built on top of Account-on-File: every scheduled payment is executed against an authorized AoF consent. As a result, there are no schedule-specific web hook events — Recurring Payments emits the same payment.created / payment.updated and consent.status.updated events as your existing Account-on-File integration.
   1. See guides on Payment status web hooks and Consent status web hooks for more details