Sample integration guide

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

Checklist

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.

Security

• 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 Data API 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.