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.

📘

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 & session

app_token

Your Lean application token, copied from the developer dashboard. Identifies your application to Lean. Safe to include in your frontend bundle.

customer_id

The Lean customer ID returned by POST /customers/v1 when you created the customer server-side. See Creating a customer.

access_token

Customer-scoped JWT minted server-side via POST /oauth2/token (use scope=customer.<customer_id>). See 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. Passing "Bearer <token>" produces the broken header Authorization: Bearer Bearer <token> and every request fails with 401.

customer_name

Display name of the customer. Shown to the user during checkout; used for proof-of-address matching in verifyAddress.

customer_metadata

Free-form metadata attached to the session. Passed through on webhooks so you can correlate sessions with your own records.

end_user_id

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

ID of a PaymentIntent you created via the Payments API. Drives a single payment.

bulk_payment_intent_id

ID of a BulkPaymentIntent. Drives a batch of payments executed in one bank session.

payment_destination_id

ID of the payment destination (beneficiary account) the customer is authorising.

payment_source_id

ID of an existing payment source on this customer. Identifies which linked account the new beneficiary should be attached to.

entity_id

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

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

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.

reconnect_id

ID of the entity whose connection needs to be restored. Supplied to you by Lean webhooks when a connection breaks.

consent_id

ID of the consent the customer is authorising.

consent_attempt_id / granular_status_code / status_additional_info

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.

Permissions & data access

permissions

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 for the full enum.

account_type

Filters the bank list shown to the user to banks that support the given account type.

access_from

Start of the data access range the user is granting. Must be a valid date and not after access_to.

access_to

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

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.

fail_redirect_url

URL the customer is redirected to after a failed / cancelled payment / consent flow.

See Open Finance for the full redirect handshake.

Display & branding

destination_alias

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

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

When true, shows an extra explanation screen before the consent step describing what data the user is about to share and why.

language

Overrides the SDK UI language. Arabic ("ar") switches the UI to a full right-to-left layout. Defaults to English.

customization

Theme and appearance overrides — colours, border radius, dialog mode, dark mode. See Customisation for the full object shape.

Environment & mode

sandbox

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

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.

Required for some regulated Open Finance deployments — check with your Lean account manager if risk signals are mandatory for your integration.

Lifecycle

callback

Invoked on SDK close with the outcome of the session. CallbackData fields:

The callback fires on the client. Authoritative state — account creation, payment completion — is delivered via webhooks. Configure your webhook URL in the developer dashboard and always respond 200 to confirm receipt. See the Webhooks reference for payload schemas.

Implementation & analytics (reserved)

The following fields are populated automatically by the mobile wrappers and should not be set manually on Web:

• implementation — metadata about the SDK host (OS, platform, SDK version).
• context — internal context strings.
• mfa_enrollment — internal MFA state.
• is_create_payment_source_method_used — internal flag set by the deprecated createPaymentSource method.

Source of truth

• Type definitions: config.ts
• Runtime validators: src/utils/configValidator/

If this page drifts from the source, the source wins — open an issue against link-sdk-web-v2 so we can realign.