TrueLayer

Access and limits

Authentication

Data API user-consent access token, plus client credentials for Payments API reads

Plans and access

A TrueLayer Console application. Data API reads need an end-user consent token; Payments API reads need the client ID and secret with the payments scope. Each Data API endpoint needs its consent scope (accounts, balance, transactions, cards, info, standing_orders, direct_debits). Mandate reads need the recurring_payments:sweeping or recurring_payments:commercial scope.

Test environment

Use api.truelayer-sandbox.com with sandbox credentials and the Mock bank; payments tokens then come from auth.truelayer-sandbox.com.

Rate limits

Banks limit unattended Data API access (often four calls per account per day under PSD2); TrueLayer returns HTTP 429, which Nexra honours with bounded retries.

Pagination

Data API endpoints return all results in one response. Mandates and merchant account transactions follow pagination.next_cursor.

Provider events

TrueLayer sends payment, refund, payout and mandate webhooks to the URI registered in Console. Flows run on demand, on a schedule, or when a scheduled check finds new or changed records.

Before you build a flow

• Intentional exclusions: creating, cancelling or authorising payments, refunds, payouts, mandates and payment links; revoking mandates; confirming funds; sweeping settings; and the legacy Payments and PayDirect APIs.
• Data API access tokens expire after one hour. With a stored refresh token (offline_access scope) and the client ID and secret, Nexra renews the token at /connect/token and writes the new access token, expiry and any returned refresh token back to the secure vault; without one, supply a fresh token. An access token stored without an expiry is renewed once on first use so its expiry becomes known.
• Token renewal is compare-and-write: a worker that finds the refresh token already rotated uses the stored pair instead. TrueLayer warns that many refreshes in the same instant can lose the bank's latest token, and the secure vault has no conditional write, so very high concurrency on one connection can still race; reconnect the user if TrueLayer then rejects the refresh token.
• Account numbers, sort codes, IBANs, remitter and beneficiary account details and full card numbers are never mapped.
• Consent acquisition, reconfirmation and reauthentication happen in your app through TrueLayer's auth flow.
• Fees: TrueLayer deducts its fees daily from the merchant account as one payout to TrueLayer (List fee collections) and sends a monthly invoice; the API reports no per-payment fee, and invoices are not available through the API.
• Disputes: open banking payments have no card-style chargebacks and TrueLayer has no dispute list. Indemnity claims on direct debit mandate payments appear as disputedAt and disputedReason on Get payment, and as payment_disputed webhooks.
• Payouts: TrueLayer has no payout list or settlement batches; payouts are read from merchant account transactions, which are themselves the settlement lines. A merchant account ID is required (List merchant accounts).
• Asynchronous Data API requests (async=true with results_uri) are not used; requests run synchronously.

Developer reference