v1

latestOpenAPI 3.1.02026-07-2478315484.9 KB

Payments Account On File

Initiate an AoF payment

Endpoint responsible for initiating an AoF payment against an existing, authorized consent.

post/payments/v1/account-on-file

Headers

Idempotency-Keystring required

Unique key used to ensure idempotency of requests. Must be unique per operation.

Request body

consent_idstring uuid required

An id of an authorized consent that should be used to authorize this payment

amountnumber required

The amount to be paid.

purpose'FIS' | 'TCS' | 'MWP' | 'OAT' | 'IFS' | 'RNT' | 'LNC' | 'PIN' | 'GDS'

A category code that relates to the type of services or goods that corresponds to the underlying purpose of the payment.
The code must conform to the payment purpose code list.
Supported values:

FIS – Financial services
TCS – Telecommunication services
MWP – Mobile wallet card payments
OAT – Own account transfer
IFS – Information services
RNT – Rent payments
LNC – Loan charges
PIN – Personal investments
GDS – Goods bought or sold

referencestring nullable

The reference submitted to the bank as a reference when initiating a payment. Can be used for reconciliation.

creditor_referencestring nullable

Clients identifier that can be used in their ERP systems

Example request

{
  "consent_id": "123e4567-e89b-12d3-a456-426655440000",
  "amount": 130.52,
  "purpose": "GDS",
  "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
      }
    }
  }
}

Response

Indicates that request was processed and payment initiation request was sent to the bank. This does not mean that the payment was successful!

idstring uuid required

The unique identifier for the payment.

account_idstring uuid required

The account id that the payment is being made to.

application_idstring required

The application id that the payment is being made to.

consent_idstring uuid required

The consent id that the payment is being made under.

status'CREATED' | 'PROCESSING' | 'PROCESSED' | 'FAILED' required

Reflects the latest known state of processing in Lean’s systems and bank.

Possible values:

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.

Notes:

CREATED and PROCESSING are transitional states.
PROCESSED and FAILED are terminal states.
Sub-statuses provide additional context.

sub_statusstring

Provides additional detail about the current lifecycle stage of the payment. It can represent intermediate workflow steps, bank-specific responses or system conditions that further qualify the main status.

referencestring

A reason or reference in relation to a payment. Passed as a part of OF creditor_reference. This value will be used as default reference for payments made with this consent.

type'ACCOUNT_ON_FILE' required

Product type

sender_customer_idstring uuid required

The customer id of the sender.

created_atstring date-time required

The date and time when the payment was created.

last_modified_atstring date-time required

The date and time when the payment was last modified.

Example response

{
  "amount": {
    "currency": "AED"
  }
}