Initiating a Payment

Overview

Once a consent is authorised, your backend can initiate payments on behalf of the customer using the Account on File API.

Each payment must reference an authorised consent_id and comply with the limits defined in the consent's control parameters. Payment initiation is performed server-to-server using your API credentials and does not have to involve any customer interaction.

Idempotency

The API uses the Idempotency-Key header to ensure that payment initiation requests are processed exactly once. Use a unique key for each intended payment.

If the same request is retried with the same Idempotency-Key, Lean will not create a duplicate. Instead, the API will return the same payment resource that was generated during the initial request.

Request

curl -L 'https://sandbox.leantech.me/payments/account-on-file' \
-H 'idempotency-key: KG5LxwFBepaKHyUD' \
-H 'Content-Type: application/json' \
-H 'Authorization: ••••••' \
-d '{
    "consent_id": "2a4ab530-9e92-4dd4-bfbb-c43a3c4d3207",
    "amount": 130.52,
    "purpose": "FIS",
    "reference": "ACME-ACCOUNT-LINK-2025-001",
    "creditor_reference": "INV-2025-004321",
    "risk_details": {
        "transaction_indicators": {
            "channel": "WEB"
        },
        "debtor_indicators": {
            "geo_location": {
                "latitude": 25.2048,
                "longitude": 55.2708
            }
        }
    }
}'

{
  "id": "341c3308-408d-48d9-ae44-c98eb1aa9a6f",
  "status": "CREATED",
  "consent_id": "123e4567-e89b-12d3-a456-426655440000",
  "amount": {
    "currency": "AED",
    "value": 130.52
  },
  "reference": "ACME-ACCOUNT-LINK-2025-001"
}

Payment status lifecycle

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

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
• even after an initially successful initiation followed by a reversal detected by payment status tracking before final reporting.

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 sends an HTTPS POST request to your configured webhook endpoint.

Configure webhook subscriptions in the Webhooks section of the Application Dashboard.