Sample integration guide

Follow the checklist to make sure you have correctly integrated with our Data API.

You can use this guide to easily integrate with our Data API so that you can avoid unnecessary errors and go live faster.


Step 1: Set up the infrastructure and the database

Why it’s important

  • To store all the relevant and required customer end-user data.
  • To adopt best practice security measures.

Structuring the database

  • Storing tokens as recommended.


  • Encryption of the keys (client_id and client_secret). Encryption of tokens.
  • No direct API to TrueLayer from the frontend.

Step 2: Authentication flow

Why it’s important:

  • To provide the best possible End-User Experience flow
  • To maximise user conversion rate
  • To maximise user retention rate
  • To display all regulatory required information

Option 1: TrueLayer Auth Dialog

  • Single auth_uri , generated from console
  • Bank selection screen is populated dynamically based on auth_uri
    providers parameters.
  • Permission screen is populated dynamically based on auth_uri scopes parameter.
  • Customise UI from the console.

Option 2: Customised Auth Dialog

  • Bank selection screen: using the providers endpoint properly.
  • Each bank in the selection screen is associated to a separate auth_uri,
    each one with its own provider_id.
  • Permission screen in place with relevant permissions displayed.

Configuring the Redirect_URI

  • Optimising Bank-to-App redirect. Mobile iOS to use Universal Links.
  • Redirect to a customer-hosted web page which is then redirecting the user to the App (TrueLayer auth-page is transparent as much as possible)

Using the state parameter for user reconciliation

  • Passing the state parameter encoded.
  • User’s data (for example. saved transaction data) is reconciled using the state parameter through subsequent re-consents.

User re-consent

  • User being prompted and instructed about having to re-consent soon when getting close to 90 days.
  • Re-authentication configuration.

Step 3: Use the Data API

Why it’s important

  • TrueLayer integration mostly takes place in the backend.
  • Data is retrieved in a timely and efficient way.
  • Best practices followed for DataAPI token management, consuming Data API, user reconciliation, error handling.

Token management

  • access_token and refresh_token management done right.
  • Background jobs to keep tokens alive and check token consent creation date.

Required data returned from all relevant providers

  • User information, account information.
  • Balance and relevant historical transactions.
  • Transaction Data enrichment.

Data API mode: ASYNC vs SYNC

  • Background / data refresh calls should be done Asynchronously.
  • Real-time user-triggered calls can be done with Synchronous API.
  • Regulatory maximum number of unattended calls is respected.

Fetching historical transactions

  • Handling the historical transaction time window.
  • Historical transactions API calls are being paginated.
  • Storing transactions.

Error handling

  • TrueLayer error codes returned need to be acknowledged and handled gracefully.
  • Debugging and reporting session done.