Guides
Application DashboardSystem Status
Start typing to search…

Fetching Bank Data: Migrating to Open Finance

If you are an existing Lean client today consuming Lean's legacy Data API solution, this guide explains the steps you need to take to migrate to your integration to Open Finance.

Note, the scope of this guide only relates retail payments (C2M) and what you need to do to migrate from Lean's legacy Payments API solution to Open Finance native 'Single Instant Payments'.

Whats changing

Overview

  • You will continue to use the same APIs and endpoints—but Lean will now power them through Open Finance API connectivity directly with banks, not legacy reverse-engineered connections.
  • You benefit from API-first, regulatory-mandated Open Finance infrastructure, replacing older wrap-around integrations.
  • Your users get a faster, cleaner, fully guided payment journey — no manual inputs, no OTP detours, no “cool-off” delays.
  • You gain full real-time payment lifecycle visibility through richer status events delivered via webhook.
  • A few new backend fields will be required to meet Open Finance standards (clearly documented in the migration guide).
  • A few new SDK functions are introduced to support consent, authentication, and redirect handling, along with some onboarding details to be shared in the DevPortal.

Migration will deliver your users a faster, fully automated end-to-end payment experience with fewer steps and less friction using native smartphone and desktop journeys with smooth app-to-app redirection.

Legacy Data user flow

---UX update--

Data Connect user flow (Open Finance)

---UX update flow for OF data--

📘

Note, the 'Al Tareq' branding in the Open Finance flow is mandatory for all Open Finance based user connections. It is a regulator driven brand initiative designed to foster end user trust and awareness

What you need to do

1. Configuration

Consent copy of purpose and benefit statements

Open Finance requires you to keep your customers informed about the purpose of the payment and the reason for engagement. You can use the Settings tab in the Lean Developer Portal to configure the following items, in both English and Arabic:

  • Purpose statement for both data and payment consents
  • Benefit statement for both data and payment consents

Redirect Urls

The Open Finance payment flow differs from the existing one. After the customer completes authentication and payment authorisation at their bank, Lean will redirect the user to the predefined URL provided during payment initiation. For security reasons, this URL must be preconfigured in the Settings tab of the Lean Developer Portal.

The redirect URL should display the payment result screen provided by the Lean SDK’s captureRedirect function.

3. Bank selection screen

If you use a custom bank selection screen, call GET /banks with customer_id as a query parameter to ensure you display all available banks (both legacy RE and Open Finance).

curl --location 'https://sandbox.leantech.me/banks/v1?customer_id={customer_id}' \
--header 'accept: application/json' \
--header 'Authorization: token
📘

If you don’t currently have your own bank selection screen, we recommend building one using the Create your own bank list guide. This gives you more control and flexibility, especially if you support use cases that span payments and data.

4. Updating Customer Details

It is a regulatory requirement of the CBUAE and Open Finance to include end user’s Emirates ID in any payment initiation request to banks for KYC purposes.

📘

Supported government identifiers for customers include: Emirates ID, National ID and Trade License Number in case of B2B customers.

To provide government identifier details for a new or existing customer, simply pass the data during creation using the /customers/v1/ endpoint.

curl -L -X POST 'https://sandbox.leantech.me/customers/v1/' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiI0NzFjZG...\
-d '{
    "app_user_id": "Your New Customer",
    "government_identifiers": [
        {
            "type": "EMIRATES_ID",
            "value": "784-1232-1232-1232"
        }
    ]
}'

or simply update your existing customer using customers/v1/{customer_id}

curl -L -X PUT 'https://sandbox.leantech.me/customers/v1/{customer_id}' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJraWQiOiI0NzFjZG...\
-d '{
    "app_user_id": "Existing Customer",
    "government_identifiers": [
        {
            "type": "EMIRATES_ID",
            "value": "784-1232-1232-1232"
        }
    ]
}'

5. SDK

Connect Flow

To support the Open Finance flow, Lean requires you to pass the redirect URLs configured in the previous steps into the SDK’s connect function and ensure that payment permissions are enabled. The full list of arguments would look as follows:

Account access

Lean.connect({
  app_token: "YOUR_APP_TOKEN",
  access_token: "<customer_access_token>",
  customer_id: "CUSTOMER_ID",
  permissions: [
    "identity", "accounts", "balance", "transactions", "identities",
    "scheduled_payments", "standing_orders", "direct_debits",
    "beneficiaries"
  ],
  sandbox: true,
  fail_redirect_url: "https://leantech.me/failure",
  success_redirect_url: "https://leantech.me/success",
  account_type: "BUSINESS" | "PERSONAL",
  access_from: "2026-01-05T00:00:00+4:00",
  access_to: "2026-01-07T00:00:00+4:00"
})
❗️

It’s important that the redirect URLs are whitelisted in Lean Developer Portal


Capturing Redirect

After the authorisation flow completes, Lean redirects the customer to the configured redirect URL, appending a set of query parameters that describe the outcome of the attempt. These parameters include identifiers that your application can use to verify and persist the result.

To present the final authorisation result to the customer, call the captureRedirect() function provided by the Lean Link SDK and pass the parameters received in the redirect.

Lean.captureRedirect({
    app_token: "<your_app_id>",
    bank_identifier: "<from_query_param>",
    consent_attempt_id: "<from_query_param>",
    customer_id: "<from_query_param>",
    granular_status_code: "<from_query_param>",
    status_additional_info: "<from_query_param>",
    sandbox: true,
    access_token: "<customer_scoped_access_token>"  
})

This should result in a screen similar to

-UX updat-

6. Handling Webhooks

Open finance based payments use two separate webhooks to notify you about the change in your entity state. First one is the familiar entity.created which represents creation of payment request with the bank. Second is payment.updated that will carry any subsequent status notification of fetching the

Entity Created Webhook

📘

Note

{
    "type": "entity.created",
    "message": "An entity object has been created.",
    "payload": {
      "id": "79a59cd9-d95c-43ec-9a8f-9a203b9085f2",
      "app_user_id": "OF_user_1",
      "customer_id": "46e347b6-ad9b-4a35-9f68-23de08c182b0",
      "permissions": [
        "transactions",
        "balance",
        "identity",
        "accounts"
      ],
      "bank_details": {
        "logo": "https://cdn.leantech.me/img/bank-assets/uae/glyphs/lean_mock_bank_uae.png",
        "name": "Lean Mock Bank",
        "bank_type": "RETAIL",
        "identifier": "MOCK_OF_UAE",
        "main_color": "#1B4298",
        "account_type": "PERSONAL",
        "background_color": "#ffffff"
      }
    },
    "event_id": "5894d41c-032e-4cbe-84c2-7f76e593943d",
    "timestamp": "2026-01-12T15:07:06.12498602Z"
  }

Entity Data refresh Updated Webhook

📘

Note it's recommended to start fetching the data for the connected entity upon receiving the entity.data.refresh.updated with overall status as FINISHED or per data API per account.

{
  "type": "entity.data.refresh.updated",
  "message": "An entity data refresh state has been updated.",
  "payload": {
    "refresh_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
    "entity_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
    "customer_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
    "status": "PENDING/FINISHED",
    "data_status": {
      "accounts": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
      "identity": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
      "account_data": [
	      {
		      "account_id": "d4718195-fef6-43ff-a3aa-69fc257752ab",
		      "balance": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "identity": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transactions": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "scheduled_payments": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "direct_debits": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "standing_orders": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "beneficiaries": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transaction_availability": {
			      "start": "<DateTime>",
			      "end": "<DateTime>"
			    }
		    },{
		      "account_id": "b5098d49-840d-459e-9ea1-d02901af9b8c",
		      "balance": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "identity": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transactions": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "scheduled_payments": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "direct_debits": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "standing_orders": "PENDING/PARTIAL/SUCCESS/FAILED/UNSUPPORTED",
		      "beneficiaries": "PENDING/SUCCESS/FAILED/UNSUPPORTED",
		      "transaction_availability": {
			      "start": "<DateTime>",
			      "end": "<DateTime>"
			    }
		    }
      ]
    }
  }
}

8. UX/UI guidelines

Branding Requirements

  • Open Finance payment flows must follow Al Tareq branding rules defined by CBUAE / Nebras.
  • The Lean SDK automatically applies compliant Al Tareq branding for all Open Finance–initiated flows.
  • Legacy RE flows are not subject to Al Tareq branding requirements.

Bank Selection Screens

  • If you use a custom bank selection screen, you may continue to do so during migration.
  • Lean will automatically route users to:
    • Open Finance flow if the bank is OF-enabled
    • RE flow if the bank is not yet OF-enabled
  • When a bank is OF-enabled, the default user journey will be Al Tareq–branded, even if the account was previously connected via RE.
  • Once all banks are migrated, your bank selection screen must comply with Al Tareq branding rules.

9. Important things to know

  • Lean can enable Open Finance for the client via adding a dedicated feature flag to the client’s client app. Lean can also technically link specific bank identifiers to this FF/client app to selectively choose which banks are enabled on Open Finance versus RE.

Updated about 1 hour ago