Lean

Who should use this guideThis guide is intended for merchants who:

Use Payrails as a payment orchestrator
Use Lean for open banking (Open Finance) payments in the UAE
Have access to the Lean application dashboard

Create a Lean integration in Payrails

Log in to the Payrails portal.
Go to Settings → Integrations.
Select Add instance to create a new integration configuration.
Select the workspaces where this integration should be available.

About workspacesWorkspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

Step 1: Choose the integration type

Select Payment.
Continue to the next step.

Step 2: Choose the provider

Select Lean.
Continue to the next step.

A screenshot showing Lean selected as the provider.

Step 3: Configure your Lean integration

What you’ll need from LeanBefore you begin, make sure you can log in to the Lean application dashboard. You’ll copy your app ID and client secret there and set up a webhook.

Integration instance name

An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

In Payrails

Enter an Instance name for your integration, for example merchant_lean.

A screenshot showing the integration instance name field.

Payment methods

In Payrails

Select Lean.

A screenshot showing the Lean payment method selection.

Account details

In Payrails

Field	Value
App ID	Your Lean app ID. Payrails also uses it as your Lean client ID.
Payment Destination ID	Optional. Refer to Configure Lean settings.
Payment Purpose Code	Optional. Refer to Configure Lean settings.

A screenshot showing the Lean account details fields.

Credentials

In Payrails

Field	Value
Client Secret	Your Lean client secret
Webhook Secret	Your Lean webhook secret. Payrails uses it to verify webhooks from Lean.

Payrails sends requests to the Lean sandbox in test mode and to the live environment in live mode, so use the credentials for the matching environment.

A screenshot showing the Lean credential fields.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

Create webhooks in the same mode (test or live) as your Payrails integration.

In Payrails

Copy the Notification URL shown under Account configuration at the top of the integration form.

In Lean

In the Lean application dashboard, add a webhook with the Payrails notification URL.
Subscribe to the payment.initiation and payment.reconciliation.updated events.
Copy the webhook secret into the Webhook Secret field in Payrails.

Request fields for Lean

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to Lean when you include them. For more about meta fields, refer to Meta fields.

Field	Status	Description
`amount`	Required	Sent to Lean as the amount and currency. Use AED, within the limits of the customer’s bank.
`paymentInstrumentData.providerData.leanBankId`	Required	The bank your customer selected, as returned in the Lean bank list.
`meta.customer.email`	Required	Payrails uses it to identify the customer with Lean.
`meta.customer.identityCardType`, `meta.customer.identityCardNumber`	Optional	Sent as the customer’s Emirates ID (`nationalId`) or trade licence number (`tradeLicense`). A trade licence marks the customer as a business.
`meta.customer.name`, `meta.customer.lastName`	Optional	Shown to your customer on the Lean payment screens.
`description`	Optional	Sent as the payment description.
`meta.paymentDestinationID`	Optional	Overrides the Payment Destination ID for this payment.

Lean confirms the transfer after the customer authorizes it, so use manual capture in your workflow. Payrails records the capture when Lean reconciles the payment.

Configure Lean settings

Some Lean integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.

Setting	What it does
Payment Destination ID	The Lean payment destination that receives your payments. To use a different destination for one payment, send `meta.paymentDestinationID` in the authorize request.
Payment Purpose Code	The purpose of the payments made through this account. Payrails sends it to the bank with every payment. Choose None to leave it out. The codes are `FIS` (financial services), `TCS` (telecommunications), `MWP` (mobile wallet card payments), `OAT` (own account transfer), `IFS` (information services), `RNT` (rent), `LNC` (loan charges), `PIN` (personal investments) and `GDS` (goods).

Enable the integration

In Payrails

Select Save account to enable the integration.
Confirm the integration shows as Enabled.

Your Lean integration is now ready to process payments.

Next steps

Run a test payment in AED with a Lean sandbox bank.
Verify that:
- Your customer can pick their bank and authorize the payment.
- The payment status updates correctly in Payrails.
Once verified in test mode, repeat the setup in live mode.

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Lean integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider