Payment statuses

Overview

Payments progress through a lifecycle consisting of a defined set of statuses that reflect their processing stage within Lean and the connected bank. The initial response to your initiation API call will usually contain status: CREATED. Further updates are delivered asynchronously via webhooks.

Payment lifecycle

flowchart LR
    CREATED --> PROCESSING
    CREATED --> FAILED
    PROCESSING --> PROCESSED
    PROCESSING --> FAILED

CREATED - An internal transaction record has been created, but no interaction with the bank has occurred yet. This includes any validation steps required before initiation. Detailed progress within the approval flow may be represented through sub-statuses.

PROCESSING - The transaction has been submitted or is being attempted at the bank. Multiple initiation attempts may occur under this state. More granular progress can be indicated by sub-statuses.

PROCESSED - The final successful state. The payment has been confirmed as completed by the payment status tracking process. Sub-statuses or other technology-specific codes may appear to indicate settlement details.

FAILED - The final unsuccessful state. Failure may occur:

• before any bank initiation (e.g. validation issues),
• after repeated unsuccessful initiation attempts (e.g. bank-unavailable, other technical issues); or
• after successful initiation but the bank rejects the transaction (e.g. declined, insufficient funds, etc.)

Payment lifecycle notifications

Lean uses webhooks to notify your system about any changes in the lifecycle of a payment. These events allow your backend to stay synchronised with Lean’s processing state without the need for frequent polling.

Once a payment is created or its status changes, Lean automatically sends an HTTPS POST request to your configured webhook endpoint (see webhook section for more details).

Webhook

{
   "event_id": "cce42859-055b-4271-b4c0-b94d54a3b894",
   "type": "payment.transaction",
   "message": "A payment object has been updated.",
   "timestamp" : "2025-10-07T10:32:39.691593783Z",
   "payload" : {
        "id": "e4e672fb-7f3c-43ea-be31-84195a65d0d7",
        "application_id": "831517ac-7e19-4436-9a1c-2e083be16902",
        "account_id": "c3a20a69-ffd5-4d95-afae-2ca52e709d05",
        "consent_id": "2a4ab530-9e92-4dd4-bfbb-c43a3c4d3207",
        "customer_id": "2d9dcfc4-0e33-46bb-853a-caee4b6843ee",
        "customer_account_identifier": null,
        "reference": "ACME-ACCOUNT-LINK-2025-001",
        "status": "PROCESSING",
        "sub_status": null,
        "amount": {
            "amount": 130.52,
            "currency": "AED"
        },
        "type": "ACCOUNT_ON_FILE",
        "created_at": "2025-10-07T10:32:30.691593783Z",
        "last_updated_at": "2025-10-07T10:32:33.691593783Z",
        "failure_details": null
    }
}