Flows Reference

Every Link SDK method maps to a distinct user-facing flow. This page describes each flow in the order you're likely to adopt them, with the backend prerequisites you must have in place and the config fields each flow accepts.

Field descriptions live in Config reference; this page only lists which fields each flow uses.

📘
Before any flow
Every flow requires:

An app_token for your application, obtained from the developer dashboard.

For every flow except pay/checkout: a customer_id for the end user. Create it server-side via POST /customers/v1 — see Creating a customer.

For production flows: a customer-scoped access_token. See Authentication.

Method index

Method	Purpose	Category
`connect`	Link a bank account for data access (and optionally payments).	Data
`pay`	Initiate a bank-to-bank payment.	Payments
`reconnect`	Restore a broken bank connection.	Data
`updatePaymentSource`	Add a new beneficiary to an existing payment source.	Payments
`checkout`	One-off guest payment authorisation (Open Finance).	Payments · Open Finance
`authorizeConsent`	Grant a long-lived Account-on-File consent (Open Finance).	Payments · Open Finance
`manageConsents`	Customer-facing consent management screen.	Data / Payments
`captureRedirect`	Show the outcome screen after an Open Finance redirect.	Open Finance
`verifyAddress`	Proof-of-address check using bank identity data.	Data

connect

Purpose. Links a customer's bank account with Lean. Walks the user through bank selection, authentication, and consent for the permissions you request.

When to use.

Granting data access (identity, accounts, balance, transactions).
Establishing an initial connection that you later extend with payment permissions.

Backend prerequisites.

Customer created via POST /customers/v1 → you have a customer_id.
Customer-scoped access_token (recommended for production).

Config fields.

Field	Required	Notes
`app_token`	✅
`customer_id`	✅
`permissions`	✅	Array of permissions to request. See Config reference → permissions.
`access_token`	—	Customer-scoped JWT.
`bank_identifier`	—	Pre-select a bank, skip the selection screen.
`account_type`	—	`"PERSONAL"` \| `"BUSINESS"` — filter the bank list.
`access_from` / `access_to`	—	ISO 8601 date range for data access.
`end_user_id`, `customer_metadata`	—	Your own correlation identifiers.
`show_consent_explanation`	—	Show extended consent explanation.
`destination_alias`, `destination_avatar`	—	Branding for the destination shown in UI.
`sandbox`, `language`, `customization`, `callback`	—	Shared.

Outcomes.

SUCCESS → a Payment Source / Entity has been created. Lean will send a webhook.
CANCELLED → user closed the SDK before granting consent.
ERROR → inspect secondary_status — see LinkSDK statuses.

pay

Purpose. Initiates a single payment or a bulk payment from the customer's bank account.

When to use.

One-off transfers. The customer chooses the bank and authorises the payment in the SDK.

Backend prerequisites.

A PaymentIntent or BulkPaymentIntent created via the Payments API.
customer_id (if using a pre-linked customer) — not strictly required for the SDK but typically expected by the intent.

Config fields.

Field	Required	Notes
`app_token`	✅
`payment_intent_id`	✅ (one-of)	Provide this OR `bulk_payment_intent_id`.
`bulk_payment_intent_id`	✅ (one-of)	Provide this OR `payment_intent_id`.
`account_id`	—	Pre-select a specific payment source / account.
`bank_identifier`	—	Pre-select a bank.
`access_token`	—
`success_redirect_url`, `fail_redirect_url`	—	Used if the selected bank requires an Open Finance redirect. See Open Finance.
`risk_details`	—	Fraud signal payload.
`destination_alias`, `destination_avatar`, `end_user_id`	—
`sandbox`, `language`, `customization`, `callback`	—	Shared.

reconnect

Purpose. Re-authenticates a customer's existing connection when it breaks (e.g. bank-side password change).

When to use.

You receive a webhook indicating a connection needs re-authentication. The webhook payload contains the reconnect_id.

Backend prerequisites.

A reconnect_id from Lean's webhook.

Config fields.

Field	Required	Notes
`app_token`	✅
`reconnect_id`	✅
`access_token`	—
`destination_alias`, `destination_avatar`	—
`sandbox`, `language`, `customization`, `callback`	—	Shared.

updatePaymentSource

Purpose. Attaches a new beneficiary (payment destination) to a customer's existing payment source, so future payments can be routed to that destination.

When to use.

Your customer has already completed connect with payment permissions and now needs to pay a new beneficiary.
Your customer completed connect for data only — use entity_id to upgrade the existing entity with payment permissions.

Backend prerequisites.

payment_destination_id for the new beneficiary.
Either payment_source_id (if already payments-enabled) or entity_id (to upgrade a data-only customer).

Config fields.

Field	Required	Notes
`app_token`	✅
`customer_id`	✅
`payment_destination_id`	✅
`payment_source_id`	✅ (one-of)	Provide this OR `entity_id`.
`entity_id`	✅ (one-of)	Use when the customer has data permissions but not payments — upgrades the existing entity.
`access_token`	—
`end_user_id`	—
`success_redirect_url`, `fail_redirect_url`	—	For Open Finance banks.
`destination_alias`, `destination_avatar`	—
`sandbox`, `language`, `customization`, `callback`	—	Shared.

⚠️
Naming note
On the Android SDK this flow is still called createBeneficiary (the updatePaymentSource name is deprecated there). On every other platform updatePaymentSource is primary. Both names resolve to the same flow.

checkout

Purpose. One-off Open Finance payment authorisation for a guest (no pre-existing Lean customer). The customer chooses a bank, authenticates via Open Finance redirect, authorises the payment, and is returned to your app.

When to use.

Guest checkout — you don't want to require account creation before payment.
Open Finance markets (e.g. UAE OF-regulated banks).

Backend prerequisites.

A PaymentIntent created via the Payments API.
Your own success_redirect_url and fail_redirect_url set up as routes in your app.

Config fields.

Field	Required	Notes
`app_token`	✅
`payment_intent_id`	✅
`success_redirect_url`	✅
`fail_redirect_url`	✅
`customer_name`	—	Shown to the user during checkout.
`bank_identifier`	—	Pre-select a bank.
`access_token`	—
`risk_details`	—
`sandbox`, `language`, `customization`, `callback`	—	Shared.

Redirect handling. After the bank flow completes, the customer lands on your success_redirect_url or fail_redirect_url with Lean-appended query parameters. Call captureRedirect with those parameters to show the correct outcome screen. See Open Finance.

authorizeConsent

Purpose. Lets a customer grant a long-lived Open Finance consent that your application can reuse to initiate future payments without another full re-authorisation.

When to use.

Subscription-like flows where you'll debit the customer repeatedly.
Saving a payment source for one-tap future payments.

Backend prerequisites.

A consent_id created via Lean's Consent API.
Redirect URLs configured.

Config fields.

Field	Required	Notes
`app_token`	✅
`customer_id`	✅
`consent_id`	✅
`success_redirect_url`	✅
`fail_redirect_url`	✅
`access_token`	—
`risk_details`	—
`destination_alias`, `destination_avatar`	—
`sandbox`, `language`, `customization`, `callback`	—	Shared.

Redirect handling. Same redirect-then-captureRedirect handshake as checkout.

manageConsents

Purpose. Shows a customer-facing screen where the user can view and revoke their currently-active consents.

When to use.

Regulatory requirement — OF customers must be able to revoke consents.
Expose in your app settings as "Manage linked banks" or similar.

Backend prerequisites.

customer_id.

Config fields.

Field	Required	Notes
`app_token`	✅
`customer_id`	✅
`access_token`	—
`sandbox`, `language`, `customization`, `callback`	—	Shared.

captureRedirect

Purpose. Displays the final outcome screen to the customer after they return from an Open Finance redirect. Reads the status parameters Lean appends to your success_redirect_url / fail_redirect_url and renders the appropriate success / failure / pending screen.

When to use.

Immediately after handling the redirect route on your side. Call this before your own success / failure UI — the SDK screen is what the customer expects to see at the end of a bank flow.

Backend prerequisites. None on the server. The parameters come from the redirect URL's query string.

Config fields.

Field	Required	Notes
`app_token`	✅
`customer_id`	✅
`consent_attempt_id`	—	From redirect URL.
`granular_status_code`	—	From redirect URL.
`status_additional_info`	—	From redirect URL.
`access_token`	—
`language`, `customization`, `callback`	—	Shared.

See Open Finance → captureRedirect for the full query-parameter contract.

verifyAddress

Purpose. Performs a proof-of-address check by matching the customer's submitted name against the identity record returned by the connected bank.

When to use.

KYC / AML workflows that need a verified name+address without manual document upload.

Backend prerequisites.

customer_id.
The customer's full name as you want it verified.

Config fields.

Field	Required	Notes
`app_token`	✅
`customer_id`	✅
`customer_name`	✅
`access_token`	—
`destination_alias`, `destination_avatar`	—
`sandbox`, `language`, `customization`, `callback`	—	Shared.

The SDK automatically sets permissions to ["identity"] — you don't need to pass it.

Deprecated methods

The following methods still work but will be removed in a future major release.

createBeneficiary (deprecated, except on Android)

Alias for updatePaymentSource. On Android, createBeneficiary is still the primary name; everywhere else it's the deprecated alias.

createPaymentSource (deprecated)

Alias for connect with permissions: ["payments"] forced. Retained for older integrations where the customer already has data permissions and only needs payments. New integrations should call connect directly with the desired permissions.