Getting start with Recurring Payments

Overview

Lean's Payment scheduler lets you create a Lean-managed payment schedule and link it to an authorised, long-lived Account-on-File consent. A single AoF consent then covers both on-demand and automatic recurring payments.

This model supports both customer-present and customer-not-present payment flows, including:

Automatic deposits into a wallet or trading account
Recurring loan repayments
Subscription payments

Prerequisites

Configured application for Open Finance
Created a Payment Destination
Created a Customer with a linked Government Identifier
Completed Account-on-file payments integration
Consent management — the manageConsents() SDK wrapper so customers can view and revoke their consents.

How it works

The Recurring payment flow consists of the following steps:

Create an Account-on-file consent that defines the customer, destination account, currency, validity period and control parameters for future payments.
Generate or fetch payment schedule details with confirmation from your end user in your app
Use authoriseConsent() in the LinkSDK to guide the customer through consent review and redirect them to their bank to authorize consent.
Initiate payments programmatically using backend-to-backend API calls, within the scope of the authorised consent i.e for ad hoc on demand payments
Create and register a new schedule against the AUHTORISED consent with either a fixed amount repeating at the same cadence or explicitly specific dates for automated payments
Receive real-time payment and consent status updates via web hooks as normal

🤔
The Account-on-file consent is the source of authority. A schedule can only be registered against an existing, AUTHORISED consent, and every payment it executes must abide by that consent's control parameters (per-payment and cumulative limits) and validity window as per the configeration of the client.
Design your consent limits with the full lifetime of the schedule and any ad hoc payments in mind — e.g. a 12-month monthly schedule of AED 100 requires a consent that permits at least 12 payments of AED 100 over that period.

Account-on-file with a payment schedule flow diagram

sequenceDiagram
    autonumber
    participant BE as Your Backend
    participant SDK as LinkSDK (Client)
    participant Lean as Lean
    participant Bank as Customer's Bank
    participant WH as Your Webhook Endpoint

    rect rgb(235, 240, 250)
        Note over BE,WH: Prerequisite — Account-on-File integration (one-time per customer)
        BE->>Lean: POST /consents/v1/account-on-file
        Lean-->>BE: 200 · consent id (AWAITING_AUTHORISATION)
        SDK->>Lean: authorizeConsent(consent_id)
        Lean->>Bank: Customer reviews & authorises consent
        Bank-->>SDK: Redirect back → captureRedirect()
        Lean-->>WH: consent.status.updated (AUTHORISED)
    end

    rect rgb(235, 250, 240)
        Note over BE,WH: Step 1 — Register the schedule
        BE->>Lean: POST /schedules/v1 (Idempotency-Key, consent_id, RECURRING or EXPLICIT definition)
        Lean-->>BE: 201 · schedule_id, status ACTIVE, links
    end

    rect rgb(250, 245, 235)
        Note over BE,WH: Step 2 — Automatic execution on each due date (no customer interaction)
        loop For each scheduled payment
            Lean->>Lean: Scheduled payment SCHEDULED → PROCESSING (attempt STARTED)
            Lean->>Bank: Initiate AoF payment under the consent
            Lean-->>WH: payment.created (payment_id)
            Bank-->>Lean: Payment outcome
            Lean-->>WH: payment.updated (final payment status)
            Note over Lean: Scheduled payment → COMPLETED or FAILED
        end
        Note over Lean: After the final planned payment → schedule COMPLETED
    end

    opt Lifecycle management (any time)
        BE->>Lean: POST /schedules/v1/{schedule_id}/pause · /resume · /cancel
        Lean-->>BE: 200 · status PAUSED / ACTIVE / CANCELLED
    end

    opt Notify end user about next payment
        BE->>Lean: GET /schedules/v1/{id} · /upcoming-payments · /payments · /attempts · /history
        Lean-->>BE: Current state
    end