--- updatedAt: 2026-07-21T08:33:57.000Z agentTools: projectIndex: https://docs.leantech.me/llms.txt --- # Config Reference The Link SDK accepts a single `config` object on every method. The **same field set** applies across Web, iOS, Android, React Native, and Flutter — only the naming convention changes (snake\_case on Web / React Native / Flutter URL builder; camelCase on iOS / Android native APIs). This page describes every field and which flows consume it. For required-vs-optional per flow, see [Flows reference](https://docs.leantech.me/docs/flows-reference). > 📘 Naming convention > > Examples on this page use the **snake\_case** names that Web, React Native, and the Flutter URL builder use. On iOS and Android the equivalent camelCase name applies (e.g. `customer_id` → `customerId`, `payment_destination_id` → `paymentDestinationId`). ## Identity and session ### `app_token` | | | | ----- | --------- | | Type | `string` | | Scope | All flows | Your Lean application token, copied from the [developer dashboard](https://dev.leantech.me). Identifies your application to Lean. Safe to include in your frontend bundle. ### `customer_id` | | | | ----- | ---------------------------------------------------------------------------------------------------------- | | Type | `string` | | Scope | `connect`, `updatePaymentSource`, `manageConsents`, `captureRedirect`, `verifyAddress`, `authorizeConsent` | The Lean customer ID returned by `POST /customers/v1` when you created the customer server-side. See [Creating a customer](https://docs.leantech.me/docs/creating-a-customer). ### `access_token` | | | | ----- | -------------------- | | Type | `string` (JWT) | | Scope | All flows (optional) | Customer-scoped JWT minted server-side via `POST /oauth2/token` (use `scope=customer.`). See [Authentication](https://docs.leantech.me/docs/authentication) for the full OAuth flow. SDK-specific rules the Link SDK enforces when this field is present: * Must be a valid JWT with an `exp` claim. * Must have **at least 10 minutes** of validity remaining at the time of the SDK call — the SDK rejects shorter-lived tokens with `Token must be valid for at least 10 minutes`. * **Do not prepend `Bearer `.** The SDK adds `Authorization: Bearer` itself at [axios.ts:98](../../link-sdk-web-v2/src/utils/api/axios.ts#L98). Passing `"Bearer "` produces the broken header `Authorization: Bearer Bearer ` and every request fails with 401. ### `customer_name` | | | | ----- | ------------------------------------------------- | | Type | `string` | | Scope | `checkout` (optional), `verifyAddress` (required) | Display name of the customer. Shown to the user during `checkout`; used for proof-of-address matching in `verifyAddress`. ### `customer_metadata` | | | | ----- | -------------------- | | Type | `string` | | Scope | `connect` (optional) | Free-form metadata attached to the session. Passed through on webhooks so you can correlate sessions with your own records. ### `end_user_id` | | | | ----- | ------------------------------------------------------ | | Type | `string` | | Scope | `connect`, `updatePaymentSource`, `pay` (all optional) | Your internal user identifier for the end user driving this session. Not validated by Lean — used for analytics and support correlation. ## Flow-scoped identifiers ### `payment_intent_id` | | | | ----- | ----------------------------------------------------------------------------------- | | Type | `string` | | Scope | `pay` (required unless `bulk_payment_intent_id` is provided), `checkout` (required) | ID of a `PaymentIntent` you created via the Payments API. Drives a single payment. ### `bulk_payment_intent_id` | | | | ----- | ------------------------------------------------------- | | Type | `string` | | Scope | `pay` (required unless `payment_intent_id` is provided) | ID of a `BulkPaymentIntent`. Drives a batch of payments executed in one bank session. ### `payment_destination_id` | | | | ----- | -------------------------------- | | Type | `string` | | Scope | `updatePaymentSource` (required) | ID of the payment destination (beneficiary account) the customer is authorising. ### `payment_source_id` | | | | ----- | --------------------------------------------------------------- | | Type | `string` | | Scope | `updatePaymentSource` (required unless `entity_id` is provided) | ID of an existing payment source on this customer. Identifies *which* linked account the new beneficiary should be attached to. ### `entity_id` | | | | ----- | ----------------------------------------------------------------------- | | Type | `string` | | Scope | `updatePaymentSource` (required unless `payment_source_id` is provided) | Entity ID for a customer who is already connected for data permissions but missing `payments`. Using `entity_id` upgrades the existing connection to include payments rather than creating a new payment source. Mutually exclusive with `payment_source_id`. ### `account_id` | | | | ----- | ---------------- | | Type | `string` | | Scope | `pay` (optional) | ID of a specific bank account on the customer's existing payment source. When provided, the SDK skips its payment-source selection screen. ### `bank_identifier` | | | | ----- | ------------------------------------------- | | Type | `string` | | Scope | `connect`, `pay`, `checkout` (all optional) | Pre-selects a specific bank by its Lean identifier. The SDK skips the bank-selection screen and goes straight into the authentication step for that bank. Useful if you render your own bank list — see [Create your own bank list](https://docs.leantech.me/docs/create-your-own-bank-list). ### `reconnect_id` | | | | ----- | ---------------------- | | Type | `string` | | Scope | `reconnect` (required) | ID of the entity whose connection needs to be restored. Supplied to you by Lean webhooks when a connection breaks. ### `consent_id` | | | | ----- | ----------------------------- | | Type | `string` | | Scope | `authorizeConsent` (required) | ID of the consent the customer is authorising. ### `consent_attempt_id` / `granular_status_code` / `status_additional_info` | | | | ----- | --------------------------------------------------------------- | | Type | `string` | | Scope | `captureRedirect` (all optional, all sourced from redirect URL) | Query parameters that Lean appends to your `success_redirect_url` / `fail_redirect_url` when returning from an Open Finance flow. Pass them through to `captureRedirect` so it can display the correct outcome screen. See [Open Finance](https://docs.leantech.me/docs/open-finance#captureredirect). ## Permissions and data access ### `permissions` | | | | ----- | ------------------------------------------------------------------ | | Type | `Permission[]` | | Scope | `connect` (required), `verifyAddress` (auto-set to `["identity"]`) | The list of data / payment permissions the user will be asked to grant. Values: * Data: `"identity"`, `"balance"`, `"accounts"`, `"transactions"` * Payments: `"payments"` * Region-specific (KSA): `"beneficiaries"`, `"identities"`, `"scheduled_payments"`, `"direct_debits"`, `"standing_orders"` Certain combinations require `"accounts"` to also be present — e.g. `"balance"` and `"transactions"` implicitly depend on account identity. See [permissions.ts](../../link-sdk-web-v2/src/constants/permissions.ts) for the full enum. ### `account_type` | | | | ----- | -------------------------- | | Type | `"PERSONAL" \| "BUSINESS"` | | Scope | `connect` (optional) | Filters the bank list shown to the user to banks that support the given account type. ### `access_from` | | | | ----- | ------------------------ | | Type | `string` (ISO 8601 date) | | Scope | `connect` (optional) | Start of the data access range the user is granting. Must be a valid date and not after `access_to`. ### `access_to` | | | | ----- | ------------------------ | | Type | `string` (ISO 8601 date) | | Scope | `connect` (optional) | End of the data access range. Must be a valid date, not in the past, and not before `access_from`. ## Payment redirect URLs ### `success_redirect_url` | | | | ----- | ------------------------------------------------------------------------------------------------------------------ | | Type | `string` (URL) | | Scope | `checkout`, `authorizeConsent` (required); `pay`, `updatePaymentSource` (optional, used for Open Finance redirect) | URL the customer is redirected to after a successful payment / consent flow. Include your own query parameters to identify the session on return; Lean will append its own status parameters that you can forward to [`captureRedirect`](https://docs.leantech.me/docs/flows-reference#captureredirect). ### `fail_redirect_url` | | | | ----- | ------------------------------- | | Type | `string` (URL) | | Scope | Same as `success_redirect_url`. | URL the customer is redirected to after a failed / cancelled payment / consent flow. See [Open Finance](https://docs.leantech.me/docs/open-finance) for the full redirect handshake. ## Display and branding ### `destination_alias` | | | | ----- | -------------------------------------------------------------------------------------------------------- | | Type | `string` | | Scope | `connect`, `pay`, `reconnect`, `updatePaymentSource`, `authorizeConsent`, `verifyAddress` (all optional) | Display name shown in the SDK UI as the "destination" the customer is paying or granting access to. Override when the destination's legal name differs from your product's customer-facing brand. ### `destination_avatar` | | | | ----- | ---------------------------------- | | Type | `string` (URL to png/jpg image) | | Scope | Same flows as `destination_alias`. | Image URL for the destination logo shown in the SDK UI. The SDK validates the URL format and rejects non-image extensions. ### `show_consent_explanation` | | | | ----- | -------------------- | | Type | `boolean` | | Scope | `connect` (optional) | When `true`, shows an extra explanation screen before the consent step describing what data the user is about to share and why. ### `language` | | | | ----- | -------------------- | | Type | `"en" \| "ar"` | | Scope | All flows (optional) | Overrides the SDK UI language. Arabic (`"ar"`) switches the UI to a full right-to-left layout. Defaults to English. ### `customization` | | | | ----- | ---------------------- | | Type | `Customization` object | | Scope | All flows (optional) | Theme and appearance overrides — colours, border radius, dialog mode, dark mode. See [Customisation](https://docs.leantech.me/docs/customisation) for the full object shape. ## Environment and mode ### `sandbox` | | | | ----- | -------------------- | | Type | `boolean` | | Scope | All flows (optional) | Set to `true` during development to run against the sandbox environment. The SDK will connect to mock banks that accept any credentials and never move real money. ## Risk signals ### `risk_details` | | | | ----- | ---------------------------------------------------- | | Type | `RiskDetails` object | | Scope | `pay`, `checkout`, `authorizeConsent` (all optional) | Structured fraud and risk signals attached to the payment authorisation. Includes device binding, biometrics, geolocation, authentication methods, transaction metadata. The full schema is defined in [riskDetails.ts](../../link-sdk-web-v2/src/types/riskDetails.ts). Required for some regulated Open Finance deployments — check with your Lean account manager if risk signals are mandatory for your integration. ## Lifecycle ### `callback` | | | | ----- | --------------------------------------------- | | Type | `(data: CallbackData) => void` | | Scope | All flows (optional but strongly recommended) | Invoked on SDK close with the outcome of the session. `CallbackData` fields: | Field | Description | | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `status` | `SUCCESS` \| `ERROR` \| `CANCELLED` \| `REDIRECT` \| `LINK_CLOSED_PROGRAMMATICALLY` | | `message` | Human-readable description of the outcome. | | `bank` | `{ bank_identifier, is_supported }` — bank the user selected, if any. | | `exit_point` | The last screen the user saw. | | `secondary_status` | Additional detail on failures (e.g. `INVALID_CREDENTIALS`). See [LinkSDK statuses](https://docs.leantech.me/docs/linksdk-statuses). | | `last_api_response` | Last status returned by the Lean API during the flow. | | `lean_correlation_id` | Correlation ID for the session — include in support requests. | | `user_exit_intent` / `exit_intent_point` / `exit_survey_reason` | Optional, populated when the user cancels via the exit survey. | | `open_banking_redirect_url` | Populated on `REDIRECT` status (Open Finance flows). | The callback fires on the **client**. Authoritative state — account creation, payment completion — is delivered via webhooks. Configure your webhook URL in the [developer dashboard](https://dev.leantech.me) and always respond `200` to confirm receipt. See the [Webhooks reference](https://docs.leantech.me/reference) for payload schemas.