Navbar
Logo
curl

Introduction

Overview

TrueLayer allows applications to connect securely with their End user’s bank, in order to either read their financial data or initiate payments:

  1. Data API - instant access to financial data
  2. Payments API - instant payment initiation

Both of our products provide an unified interface between multiple financial institutions and third party applications over a common RESTful API.

Getting Started

Getting started with the Data API

  1. Sign-up and obtain your client_id and client_secret. You will need to register at least one redirect_uri.
  2. Create an Authentication Link to authenticate your End users
  3. Obtain an access_token following the End user Authentication oAuth 2.0 flow
  4. Use the Data API to retrieve End user’s personal information, account numbers and transaction data.

Getting started with the Payments API

  1. Sign-up in the sandbox environment and obtain your client_id and client_secret. You will need to register at least one redirect_uri.
  2. Create a client credentials grant to get a token to call the API.
  3. Use the Payments API to create a new payment resource, and follow the redirect URI to navigate to a bank payment consent flow.

Access Methods

TrueLayer uses dedicated PSD2 APIs for all available banks. We also use public proprietary APIs when available e.g. Monzo/Starling. The authentication is managed by the bank.

API Authentication

To call any TrueLayer APIs which require authentication, it’s necessary to first request the creation of an access token. Requests to authenticated APIs which do not include a valid access token will be rejected.

To create an access token, you will need your client_id and client_secret. These values can be found in the Console here: https://console.truelayer.com/settings/Application

Data API

When creating an access token for the Data API, you will also need to provide a code which represents the authorisation provided by your user.

See Data API Authentication for more details.

Payments API

Request access token

To create an access token for the Payments API, you simply need to provide the client_id and client_secret and request the payments scope.

Request

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=payments \
    https://auth.truelayer.com/connect/token

Response

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use access token

Once you have the access_token from the response, this can be included in Payments API requests as a Bearer token in the Authorization header. Here’s an example with other fields removed for clarity:

Request

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{...}' \
https://pay-api.truelayer.com/single-immediate-payments

Data types

General

All of the responses returned by TrueLayer APIs are in JSON format. The description of the data types encoded in a JSON response is below.

Type Description
string A UTF-8 string
datetime An ISO8601 encoded date time
boolean true or false
number A float number

ISO20022 Text Fields

The Payments API constrains some fields to be limited to ISO 20022 text format. These fields are typically used for names and references in bank payment requests.

Valid characters for such a text field include: a-z A-Z 0-9 / – ? : ( ) . , ‘ + space

Any other characters included will result in a validation error.

API response structure

All responses are JSON encoded.

Success

Success response

{
    "results": [
        {
            "hello": "world"
        }
    ]
}
Field name Type Description
results array An array of objects

Error

Error response

{
    "error":  "internal_error",
    "error_description": "Well, this is embarrassing!",
    "error_details": {
        "detail_key": "detail value"
    }
}
Field name Type Description
error string An error code for classification. eg: internal_error
error_description string When possible, extra details about the specific error
error_details object Additional key/value error details if available

Error codes

The following error codes can be returned with the associated HTTP status for both the Data and Payments API.

Auth (OAuth2) API Errors

HTTP Status Description Error Retry How to handle
200 Success
400 The request is missing a required parameter invalid_request No Check that your API request is correct and that contains all the required parameters
400 The client is not authorized to request an authorization token unauthorized_client No Check your client id/secret/redirect_url
400 Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method) invalid_client No Check your client id/secret/redirect_url
400 The resource owner or authorization server denied the request access_denied
400 The authorization server does not support obtaining an authorization code using this method unsupported_response_type No Check that your API request is correct
400 The requested scope is invalid, unknown, or malformed invalid_scope No Check the scopes that you are requesting
400 The server encountered an unexpected condition that prevented it from fulfilling the request server_error Yes Retry later
400 The authorization server is currently unable to handle the request due to a temporary overloading or maintenance temporarily_unavailable Yes Retry later
400 The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client invalid_grant No Ask the user to reconnect their account. This most often occurs when a user’s 90 days of consent to access their account has expired. It can also be caused by some rare network errors which can cause a user’s bank tokens to be made invalid. Either way, the user must reconnect their account.
400 The authorization grant type is not supported by the authorization server unsupported_grant_type No Check that your API request is correct

Providers

TrueLayer uses the term providers to refer to Banks, ASPSPs, or other institutions we connect to.

Each provider has a provider_id which is immutable.

Examples: ob-lloyds, oauth-starling, xs2a-db.

Provider Release Channels

We allow our customers to get early access to providers we are working on, for both our Data and Payments products.

Provider release stages

Private Beta Public Beta Live
Definition We have a functional connector that has been proven to work with live traffic, and we may have known issues.We do not commit to our standard SLA’s when using these providers. We have a functional connector that has been proven to work with live traffic, and we may have known issues, but they are only minor. We do not commit to our standard SLA’s when using these providers. We are comfortable the connector is functional to TrueLayer’s standards. We commit to maintaining these providers based on our standard SLA’s.
Availability Open to specific clients who express an interest in specific providers. Open to all TrueLayer clients. Open to all TrueLayer clients.
Access Please contact your Customer Success Manager to join. Please contact our sales team to join. Everyone, including people testing our API, can use these providers.

Full list of providers

To see the full list of live providers please click here: https://auth.truelayer.com/api/providers

Providers and authorisation steps

If you are creating your own bank selection page, you may need to collect additional information from the end-user during the authorisation flow. This additional information is documented in the form of steps in the Providers API response for all providers that require them. You can find more information on how to send us the end-user’s response to these steps as Auth Inputs on our Direct Bank Authentication section. If you are using TrueLayer’s Auth Dialog, TrueLayer will handle this process for you.

The steps parameter structure

Field Type Description
title string Friendly name for this method within the provider
fields array Array of input fields
fields.type string Input field type. Can be a Single Choice Input or a Free Input
fields.is_sensitive boolean OPTIONAL: For Free Input Values, is set to true for sensitive information like passwords
fields.values array OPTIONAL: For Single Choice Input, an array of values
fields.values.value string OPTIONAL: For Single Choice Input, input field value
fields.values.display_name string OPTIONAL: For Single Choice Input, friendly name for this input field value
fields.validations array OPTIONAL: For Free Input Values, an array of RegEx validation rules that need to be satisfied to consider the input valid
fields.allowed_characters string OPTIONAL: For Free Input Values, character ranges allowed. can be alphanumeric or numeric
fields.id string Unique id for this field within the method
fields.display_name string Friendly name for this field within the method
fields.help_text string Input help text for the end user
fields.mandatory boolean Indicates whether the field is required

Accessing beta providers

Once approved for the programme, Beta connectors will be enabled for your client_id only. You can view the providers you have access to in two ways:

  1. Via your Console. You must be logged into the correct account to view them.
  2. Via the Providers API. You must pass your client_id in the providers URL following this pattern: https://auth.truelayer.com/api/providers?clientId=your-client_id

Sandbox

TrueLayer provides a completely separate sandbox environment where you can test without requiring live bank accounts. All account data and transactions are completely segregated from the production environment.

The sandbox environment provides the console to manage your account, the Data API and the Payments API.

To create a sandbox account, click here.

Please note that the sandbox does not include a full bank simulation with consistent bank accounts, it is only intended to facilitate API testing.

For details on how to integrate to the Payments API using the sandbox, please see the Payments Quick Start.

User logins and TrueLayer platform accounts

Your login to the TrueLayer platform is either via single-sign-on (e.g. Google or Github accounts), or with email address and password. When you create your login for the first time, you will navigate through our registration wizard, then your TrueLayer platform account will be created.

If you register via the sandbox console, a sandbox TrueLayer platform account will be created. This can be used with sandbox API endpoints.

If you register via the production console, a production TrueLayer platform account will be created. This can be used with production API endpoints.

Please note that the same login (whether SSO or email/password) can be used to log in to both your sandbox and production accounts; you do not need two separate logins.

Sandbox accounts and production accounts

Your sandbox account has its own client_id and client_secret; these may be used to create access tokens to call the Data or Payments API. To differentiate it from production accounts, your sandbox account client_id will always have the prefix sandbox-. It will not be possible to add this prefix to a production account client_id.

Sandbox accounts may only be used with sandbox API endpoints: - sandbox client credentials cannot be used to create a production access token - sandbox access tokens cannot be used to call production API endpoints

The production environment has no access to the sandbox environment. Resources created in the sandbox cannot be accessed via production APIs, e.g. if a payment is created in the sandbox, an attempt to GET the payment resource in the production environment will return a 404 response. Similarly, when the Data API is used to retrieve banking data within the sandbox environment, this data will not be accessible from within the production environment.

Sandbox API endpoints

API endpoints for the sandbox are the same as in production, but instead of ending with the domain truelayer.com, they all end with the domain truelayer-sandbox.com.

Sandbox Bank Accounts

For Payments, we have integrated into an actual bank sandbox environment to facilitate end-to-end testing of the API and the associated user journeys. This provides the ability to navigate through a bank’s payment consent journey while testing the Payments API.

For Data, we currently support testing of our API in the sandbox environment with Mock Bank.

Data API v1

Data API Overview

The TrueLayer Data API is a single interface to access identity, accounts, transactions and balance data for all integrated banks.

We currently offer the Data API in the UK, are in private Beta in Germany and are rapidly expanding across Europe.

To get support for the Data API:

Data API Quick Start

You can connect with our Data API and retrieve bank data in a few quick steps - here’s how it works:

  1. After signing up to our Console, generate an Authentication Link. This link provides a simple user interface for your users to connect their bank accounts.
  2. Through that interface, you or your users can log into a real bank account (or our Mock Bank account), and obtain an access_token. Then, you can use this access_token to access user data (accounts, transactions, balances, etc.) via our API.

It’s that simple! Want to see it in action? Try our demo application Piggy Bank to see a working example of a TrueLayer integration.

Or try it yourself! We have made Postman collections available for both our Live and Sandbox environments.

Sandbox Postman Collection

Step 1 - Sign Up

  1. Sign up to the TrueLayer Console to get your Sandbox client_id and client_secret.
  2. Install Postman and download our Sandbox Postman collection. It contains sample requests so that you can quickly retrieve data, and generate code snippets in various languages of your choice. It also has our Sandbox environment endpoints preconfigured.

Step 2 - Authorise a User

Create a Sandbox Auth Link to authenticate users via the Auth Link Builder in our Console. This Auth Link provides an easy user interface to demo connecting to our Mock Bank.

How to build your Sandbox Auth Link:

  1. Select the set of Permissions to include in the Authentication link. These permissions will limit the endpoints of Data API that your application will be able to access.
  2. You must also choose a Redirect URI where the user will be redirected after authenticating.
  3. Make sure the Mock provider is enabled so that you can use our Mock Bank user credentials for testing.
  4. Next, click the test button to open the generated Sandbox Auth Link and connect to Mock Bank.

    Auth Link Builder

  5. Select Mock Bank and use a set of our Mock Bank credentials (eg. “john”/”doe”) in order to obtain a code.

    Sandbox Authentication Code

Step 3 - Obtain an Access Token

Use the Postman Exchange Code request within the Authentication folder in order to exchange the generated code into an access_token. To do so:

  1. Add the missing required variables : Sandbox client_id and Sandbox client_secret (found in the Console) as well as the code (generated in Step 2).

Postman Collection Example

  1. Send the request and retrieve a response containing an access_token and refresh_token.

Step 4 - Access Data

With the acquired access_token, run any of the requests in the Data API folder in the Sandbox Postman collection to retrieve account numbers, transaction data or personal information. For example: the List all accounts request within the Data API folder will retrieve all account information within the given set of credentials. For a list of all the endpoints supported, see the full Data API reference.

Now you’re retrieving mock bank data!

Live Postman Collection

Step 1 - Sign Up

  1. Sign up to the TrueLayer Console to get your client_id and client_secret.
  2. Install Postman and download our Live Postman collection. It contains sample requests so that you can quickly retrieve data, and generate code snippets in various languages of your choice.

Step 2 - Authorise a User

Create an Auth Link to authenticate users via the Auth Link Builder in our Console. This Auth Link provides an easy user interface for your users to choose their bank accounts.

How to build your Auth Link:

  1. Select the set of Permissions to include in the Authentication link. These permissions will limit the endpoints of Data API that your application will be able to access.
  2. You must also choose a Redirect URI where the user will be redirected after authenticating.
  3. Enable the providers you want to to make available.
  4. Next, click “Test” to open the generated link and connect a bank.

    Auth Link Builder

  5. Select a Live Bank and you will be redirected to the Bank’s Open banking Consent screen to Authenticate in order to obtain a code.

    Authentication Code

Step 3 - Obtain an Access Token

Use the Postman Exchange Code request within the Authentication folder in order to exchange the generated code into an access_token. To do so:

  1. Add the missing required variables : client_id and client_secret (found in the Console) as well as the code (generated in Step 2). Postman Collection Example
  2. Send the request and retrieve a response containing an access_token and refresh_token.

Step 4 - Access Data

With the acquired access_token, run any of the requests in the Data API folder in the Postman collection to retrieve account numbers, transaction data or personal information. For example: the List all accounts request within the Data API folder will retrieve all account information within the given set of credentials. For a list of all the endpoints supported, see the full Data API reference.

Now you’re retrieving live bank data!

What’s next

Data Guides

This section will contain the Guide sub-sections for the Data API.

Data Definitions

Definition Description
Account A financial account with a Provider
Authorization Server The secure service hosted by TrueLayer that allows End users to authenticate with their Provider credentials. It also offers API endpoints to obtain and renew access_token
Client An application implementing this API
End user An application’s user and the owner of an account
Data API The API that provides access to End users’s financial data
Permissions A set of permissions the End user grant to the Client to access data on their behalf
Provider A supported bank or other financial institution
Credentials A set of identifiers and secrets the End user uses to access their accounts with a Provider

Data API Authentication

To authenticate, the single-use code obtained at the redirect_uri will need to be exchanged for a short-lived access_token.

The access_token can be used to access all Data API endpoints allowed by the given set the permissions.

To see how to exchange the code for the access token: Exchange code for access_token

To see how to renew an access token: Renew the access_token

The Data API supports one access method for authentication: Access Methods

The Data API authentication via Regulated APIs works like this:

OpenBanking Sequence Diagram

End User Authentication

The first step in the authentication process is to redirect the End user with a properly formatted link to TrueLayer Authorization Server. If the provider used for the authentication is already known, it can be supplied with an optional provider_id parameter, in order to skip the selection.

Request

https://auth.truelayer.com/\
  ?response_type=code\
  &response_mode=form_post\
  &client_id=${client_id}\
  &redirect_uri=${redirect_uri}\
  &scope=${scope}\
  &state=${state}

Authentication Link: The End user’s browser is redirected to TrueLayer’s Authorization Server using a link that includes the application’s client_id, redirect_uri (already authorized for the Client) and a scope parameter defining the Permissions requested to the End user. A state argument is optional but is strongly recommended (helps reconcile requests that by their nature are stateless).

You can build your Authentication Link in the console as shown below.

Auth Link Builder

End user log-in: The End user selects a Provider and authenticates securely on the TrueLayer authorization server using their Provider credentials.

Choose your bank

  1. Code Redirect: End user’s browser is redirected to the redirect_uri controlled by the Client with a code, the requested scope and the optional state

  2. Exchange code with access_token: The application exchanges the code received with a short-lived access_token (and optionally a refresh_token if the scope offline_access was requested) making a HTTP POST to the TrueLayer authorization server including the application client_id, client_secret and redirect_uri

  3. Access Data API: The application can use the obtained access_token to access data on behalf of the End user. An Authorization header must be provided to access any endpoint of the Data API

  4. Renew the access_token: After the short-lived access_token expires (1 hour by default or provider specified) a new access_token can be obtained using the refresh_token

Auth Dialog

TrueLayer Auth Dialog is the end user facing interface that permits you to connect to your user’s bank account.

Its purpose is to guide the end users through the process of sharing their banking data by providing a login experience that is simple and compliant with FCA policies, GDPR and PSD2.

The Auth Dialog will handle credential validation, different authentication methods and error handling for all the banks we support, so you don’t have to. It works across all modern browsers and devices.

UI Customisation

On the Scale plan and the Enterprise plan, you can also customise parts of the Auth Dialog including colours, some copy elements, setting a cancelation_uri or a link to your FAQs directly from our Console.

Flow Customisation

The Auth Dialog flow can also be customised depending on your needs:

Async Requests

We recommend using Data API asynchronously. Asynchronous access mitigates issues that are beyond the control of TrueLayer and removes the need for you to write your own error and retry logic as is it handled seamlessly.

You can make an asynchronous API call by passing a query parameter async=true for any potentially long operation (For ex. fetching multiple years of transactions) and be returned with a results_uri that will contain the results of your request once they are available. The Data API supports asynchronous requests on all endpoints.

After making an asynchronous API call, you can poll the results_uri and wait for completion. To avoid polling, you can pass a webhook_uri parameter to receive a real-time notification via HTTP POST (Webhook) when the request is completed.

Please note that even if webhook_uri is passed the results will not be part of the HTTP POST payload but must be fetched at results_uri.

Make Asynchronous API calls

Request

curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/accounts/${account_id}?async=true&webhook_uri=${uri}"

Response

{
    "results_uri": "https://api.truelayer.com/data/v1/results/b1bc9472-3c21-44ed-ade2-2e932c41ee64", 
    "status": "Queued", 
    "task_id": "b1bc9472-3c21-44ed-ade2-2e932c41ee64"
}

If a query parameter async=true is passed, the Data API immediately returns a response containing the results_uri, status and task_id, which can be used to track the status of the call. When the results are ready, they will be available to fetch at the results_uri.

The query will return one of the following status messages:

Status Description
Queued The query is waiting to run
Running The query is currently running
Succeeded The query has successfully returned results
Failed The query is has failed to retrieve the query results

Parameters

Field Type Description
async boolean If true the request is handled asynchronously
webhook_uri URI The URI where notification of completion will be sent via HTTP POST

Webhook Callback Payload

Webhook payload

{
    "request_timestamp" : "0001-01-01T00:00:00Z",
    "request_uri" : "https://api.truelayer.com/api/v1.0/accounts/1234/transactions?from=2017-01-01&to=2017-12-01",
    "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
    "task_id": "e1245d07-d846-42df-86d8-99b08b430a0",
    "status": "Succeeded | Failed",
    "results_uri": "https://api.truelayer.com/data/v1/results/e1245d07-d846-42df-86d8-99b08b430a0/",
    "error_description": "Error | null",
    "error": "Error | null"
}

When an asynchronous request is completed, this payload will be sent to the webhook_uri via HTTP POST.

Field Type Description
request_timestamp datetime The time of the original request
request_uri string The URI of the original request
credentials_id string Unique string identifying a set of End user’s credentials used to access a Provider
task_id string A unique ID associated with the task
status string Succedeed or Failed
results_uri string The URI where results can be fetched from when available.
error string An error code
error_description string Extra details about the error

Fetch the results

Request

curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/results/${task_id}

To fetch results from results_uri you will need to authenticate with a valid access_token corresponding to the credentials_id of the original request.

Transaction Categorisation

transaction_category identifies the type of a transaction for both account and card transactions. The supported set of categories is consistent across all providers.

These are the supported set of transaction categories:

Type Description
ATM Deposit or withdrawal of funds using an ATM (Automated Teller Machine)
BILL_PAYMENT Payment of a bill
CASH Cash deposited over the branch counter or using a Cash & Deposit Machines
CASHBACK An option retailers offer to withdraw cash while making a debit card purchase
CHEQUE A document ordering the payment of money from a bank account to another person or organization
CORRECTION Correction of a transaction error
CREDIT Funds added to your account
DIRECT_DEBIT An automatic withdrawal of funds initiated by a third party at regular intervals
DIVIDEND A payment to your account from shares you hold
FEE_CHARGE Fees or charges in relation to a transaction
INTEREST Credit or debit associated with interest earned or incurred
OTHER Miscellaneous credit or debit
PURCHASE A payment made with your debit or credit card
STANDING_ORDER A payment instructed by the account-holder to a third party at regular intervals
TRANSFER Transfer of money between accounts
DEBIT Funds taken out from your account, uncategorised by the bank
UNKNOWN No classification of transaction category known

Transaction Classification

Transaction classification returns detailed category information for account transactions.

Category Subcategory
Income Income
Paycheck
Investment
Returned Purchase
Bonus
Interest Income
Reimbursement
Rental Income
Uncategorized Cash & ATM
Check
Entertainment Arts
Music
Dating
Movies & DVDs
Newspaper & Magazines
Social Club
Sport
Games
Education Tuition
Student Loan
Books & Supplies
Shopping Pets
Groceries
General
Clothing
Home
Books
Electronics & Software
Hobbies
Sporting Goods
Personal Care Hair
Laundry
Beauty
Spa & Massage
Health & Fitness Dentist
Doctor
Eye care
Pharmacy
Gym
Pets
Sports
Food & Dining Catering
Coffee shops
Delivery
Fast Food
Restaurants
Bars
Gifts & Donations Gift
Charity
Investments Equities
Bonds
Bank products
Retirement
Annuities
Real-estate
Bills and Utilities Television
Home Phone
Internet
Mobile Phone
Utilities
Auto & Transport Auto Insurance
Auto Payment
Parking
Public transport
Service & Auto Parts
Taxi
Gas & Fuel
Travel Air Travel
Hotel
Rental Car & Taxi
Vacation
Fees & Charges Service Fee
Late Fee
Finance Charge
ATM Fee
Bank Fee
Commissions
Business Services Advertising
Financial Services
Office Supplies
Printing
Shipping
Legal
Personal Services Advisory and Consulting
Financial Services
Lawyer
Repairs & Maintenance
Taxes Federal Tax
State Tax
Local Tax
Sales Tax
Property Tax
Gambling Betting
Lottery
Casino
Home Rent
Mortgage
Secured loans
Pension and insurances Pension payments
Life insurance
Buildings and contents insurance
Health insurance

Batch endpoint

The batch endpoint abstracts implementation complexity for our Data API by simplifying the retrieval of transaction histories and balances for all accounts and cards belonging to a user.

Specifically, through a single API request, it is made possible to retrieve transaction histories and balances for all accounts and cards relating to that credential set on a single provider within a specified time window.

The batch endpoint proposition requires enabling the storage of account transactions on TrueLayer servers. By allowing this, you will be able to:

You can try out the batch endpoint immediately in production using our mock bank - check the API reference.

What problem does it solve?

The batch endpoint feature simplifies the implementation of the Data API at scale.

Before

Without the batch endpoint the current workflow to retrieve transactions for multiple accounts and cards belonging to the same set of credentials is:

  1. (Optional) Check token scopes using /me;
  2. Enumerate all accounts using /accounts;
  3. Enumerate all cards using /cards;
  4. For each account, fetch transactions for the time range of interest using /accounts/{account_id}/transactions;
  5. (Optional) For each account, fetch pending transactions using /accounts/{account_id}/transactions/pending;
  6. (Optional) For each account, fetch balance using /accounts/${account_id}/balance​;
  7. For each card, fetch transactions for the time range of interest /cards/{account_id}/transactions;
  8. (Optional) For each card, fetch pending transactions using /cards/{account_id}/transactions/pending;
  9. ​​(Optional) For each card, fetch balance using /cards/${account_id}/balance​;

Each of these calls might fail and retries have to be handled.

If you are using the asynchronous API, you may also need to:

After

Setup

# Get a valid access token and export it as an environment variable:
export ACCESS_TOKEN=your-access-token
# Set up a request bin on https://requestbin.com/ - you will use it to receive our webhook
# Put the request body in a JSON file, e.g. `batch_request.json`:
{
  "from": "2019-05-10",
  "to": "2019-05-20",
  "pending": true,
  "balance": true,
  "webhook_uri": "https://your-webhook-uri.com/"
} 

Execute the call

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --request POST \
  --data @batch_request.json \
  https://api.truelayer.com/data/v1/batch/transactions

With the batch endpoint the workflow is reduced to the following steps:

  1. Submit request to batch endpoint specifying access token and transaction time period;
  2. Await a single webhook notifying of job completion;
  3. Retrieve results from the results_uri specified in the webhook payload, using the access token.

Income API

Leveraging the Data API, it returns an estimate of an end-user’s income along with relevant insights, broken down by source and type.

Example request

curl --header "Content-Type: application/json" \
 --header "Authorization: Bearer ${ACCESS_TOKEN}" \
 https://insights.truelayer.com/v1/accounts/${account_id}/income?from=${from}&to=${to}

Example response

{
 "average_total_income_monthly": 3251.62,
 "transaction_history_span_days": 86,
 "sources": [
     {
         "income_type": "salary",
         "name": "some company ltd",
         "average_monthly_income": 3125.12,
         "average_amount": 3125.2,
         "maximum_amount": 3180.24,
         "minimum_amount": 3070,
         "supporting_transactions": [
             {
                  "transaction_id": "a15d8156569ba848d84c07c34d291bca",
                  "amount": 3180.24,
                  "currency": "GBP",
                  "transaction_category": "CREDIT",
                  "description": "some company ltd",
                  "timestamp": "2020-03-06T00:00:00Z",
                  "transaction_type": "Credit",
                  "transaction_classification": [],
                  "meta": {
                    "provider_transaction_category": "CRED"
                  }
              },
              {
                  "transaction_id": "03c333979b729315545816aaa365c33f",
                  "amount": 3070,
                  "currency": "GBP",
                  "transaction_category": "CREDIT",
                  "description": "some company ltd",
                  "timestamp": "2020-02-06T00:00:00Z",
                  "transaction_type": "Credit",
                  "transaction_classification": [],
                  "meta": {
                    "provider_transaction_category": "CRED"
                  }
              }
         ]
     },
     {
         "income_type": "other_source",
         "name": "savings account profit",
         "average_monthly_income": 126.5,
         "average_amount": 126.5,
         "maximum_amount": 150,
         "minimum_amount": 103,
         "supporting_transactions": [
            {
                "transaction_id": "3484333edb2078e77cf2ed58f1dec11e",
                "amount": 150,
                "currency": "GBP",
                "transaction_category": "CREDIT",
                "description": "savings account profit",
                "timestamp": "2020-03-01T00:00:00Z",
                "transaction_type": "Credit",
                "transaction_classification": [],
                "meta": {
                  "provider_transaction_category": "CRED"
                }
            },
            {
                "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
                "amount": 103,
                "currency": "GBP",
                "transaction_category": "CREDIT",
                "description": "savings account profit",
                "timestamp": "2020-02-24T00:00:00Z", 
                "transaction_type": "Credit",
                "transaction_classification": [],
                "meta": {
                  "provider_transaction_category": "CRED"
                }
            }
         ]
     }
 ]
}

Expenditure API

Leveraging the Data API, it returns insights and patterns on a user’s recurring expenditures. Such expenditures include

Example request

curl --header "Content-Type: application/json" \
 --header "Authorization: Bearer ${ACCESS_TOKEN}" \
 https://insights.truelayer.com/v1/accounts/${account_id}/expenditure/regular?from=${from}&to=${to}

Example response

{
  "transaction_history_span_days": 86,
  "expenditures": [
    {
      "name": "THAMES WATER",
      "frequency": "monthly",
      "classification_category": [
        "Bills and Utilities",
        "Utilities"
      ],
      "merchant_name": "THAMES WATER",
      "previous_payment_timestamp": "2020-04-01T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-05-01T00:00:00Z",
      "predicted_next_payment_amount": -40.15,
      "average_amount": -40.15,
      "minimum_amount": -40.77,
      "maximum_amount": -39.84,
      "supporting_transactions": [
       {
          "transaction_id": "b8db1fdf3638a5307bd4af2e2b43d45e",
          "description": "Thames Water",
          "amount": -40.77,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-04-01T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Utilities"],
          "merchant_name": "THAMES WATER",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "aff0e8ee9d5ae4c10e446c331d09d7c6",
          "description": "Thames Water",
          "amount": -39.84,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-02T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Utilities"],
          "merchant_name": "THAMES WATER",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "a0e78409ce5a155d9688f57c9e0f5aa1",
          "description": "Thames Water",
          "amount": -39.84,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-04T00:00:00Z", 
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Utilities"],
          "merchant_name": "THAMES WATER",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        }
      ]
    },
    {
      "name": "Octopus Energy Lim",
      "frequency": "monthly",
      "classification_category": [],
      "merchant_name": "Octopus Energy",
      "previous_payment_timestamp": "2020-04-01T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-05-01T00:00:00Z",
      "predicted_next_payment_amount": -53.36,
      "average_amount": -53.36,
      "minimum_amount": -53.36,
      "maximum_amount": -53.36,
      "supporting_transactions": [
        {
          "transaction_id": "1022425bf7cd247a9a704dc345e88ad2",
          "description": "Octopus Energy Lim",
          "amount": -53.36,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-04-01T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": [],
          "merchant_name": "Octopus Energy",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "36ce2bc0726f3ad17da0d7752beedbb5",
          "description": "Octopus Energy Lim",
          "amount": -53.36,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-02T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": [],
          "merchant_name": "Octopus Energy",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "4544ef2534a29c15bd85ef0f1633a053",
          "description": "Octopus Energy Lim",
          "amount": -53.36,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-03T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": [],
          "merchant_name": "Octopus Energy",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        }
      ]
    },
    {
      "name": "VIRGIN MEDIA",
      "frequency": "monthly",
      "classification_category": [
        "Bills and Utilities",
        "Internet"
      ],
      "merchant_name": "VIRGIN MEDIA",
      "previous_payment_timestamp": "2020-03-27T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-04-27T00:00:00Z",
      "predicted_next_payment_amount": -38.11,
      "average_amount": -38.11,
      "minimum_amount": -38.35,
      "maximum_amount": -38,
      "supporting_transactions": [
        {
          "transaction_id": "85e070858eddebc6488f6a4fee0bbcbc",
          "description": "Virgin Media",
          "amount": -38.35,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-27T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Internet"],
          "merchant_name": "VIRGIN MEDIA",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "26756a7ad5b7b72d6191afe416ddef48",
          "description": "Virgin Media",
          "amount": -38,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-27T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Internet"],
          "merchant_name": "VIRGIN MEDIA",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "d5bbb797ce7ac0e6bf5d4d83d07ed37f",
          "description": "Virgin Media",
          "amount": -38,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-01-27T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Internet"],
          "merchant_name": "VIRGIN MEDIA",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        }
      ]
    },
    {
      "name": "NETFLIX",
      "frequency": "monthly",
      "classification_category": [
        "Entertainment",
        "Movies & DVDs"
      ],
      "merchant_name": "NETFLIX",
      "previous_payment_timestamp": "2020-03-20T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-04-20T00:00:00Z",
      "predicted_next_payment_amount": -8.99,
      "average_amount": -8.99,
      "minimum_amount": -8.99,
      "maximum_amount": -8.99,
      "supporting_transactions": [
       {
          "transaction_id": "070ff6c1fc9ac17309466cd52e61bbcc",
          "description": "Netflix",
          "amount": -8.99,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-20T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Entertainment", "Movies & DVDs"],
          "merchant_name": "NETFLIX",
          "meta": {
            "bank_transaction_id": "9882ks-00js",
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "1efacba6b94e16ce3de0ec5986908ee2",
          "description": "NETFLIX",
          "amount": -8.99,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-20T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Entertainment", "Movies & DVDs"],
          "merchant_name": "netflix",
          "meta": {
            "bank_transaction_id": "9883ys-00js",
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "e8796dbd81e1a6fe5b893cb83e50a7b4",
          "description": "Netflix",
          "amount": -8.99,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-01-20T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Entertainment", "Movies & DVDs"],
          "merchant_name": "NETFLIX",
          "meta": {
            "bank_transaction_id": "9892fs-00js",
            "provider_transaction_category": "DEB"
          }
        }
      ]
    }
      ]
    }

Data API reference

The Data API provides endpoints to retrieve personal information, account numbers and transaction data. All endpoints require authorization using access_token.

Only one concurrent request per access token is allowed in the synchronous API, if a concurrent request is made a 409 request_conflict error is returned.

Identifiers

Identifier name Description Confidentiality Lifetime
access_token A short-lived JWT token used to access data on behalf of the End user Secret provider-specific (usually 1 hour)
client_id A unique string identifying a Client Public Forever
client_secret A secret key used to authenticate a Client Secret Forever (until rotated)
code A one-time code that can be exchanged for an access_token Secret Single use
credentials_id Unique string identifying a set of End user’s credentials used to access a Provider Public Forever
provider_id A unique string identifying a Provider Public Forever
redirect_uri A URI controlled by the Client where one-time code is posted during authentication Public Forever
refresh_token A long-lived code used to obtain a new access_token Secret Single use

Permissions

An Authentication Link must include a set of permissions in the scope parameter that your Client is requesting on behalf of the End user. These permissions (or scopes) limit what endpoints the Client will be authorized to access in the Data API.

Scope Description API endpoint
info Allows access to End user’s identity information held by the Provider /data/v1/info
accounts Allows access to End user’s account numbers and details /data/v1/accounts, /data/v1/accounts/${account_id}
accounts + balance Allows access to End user’s account balances /data/v1/accounts/${account_id}/balance
accounts + transactions Allows access to End user’s account transactions /data/v1/accounts/${account_id}/transactions
accounts + transactions + balance Allows access to End user’s account transactions along with running balance /data/v1/accounts/${account_id}/transactions
cards Allows access to End user’s card numbers and details /data/v1/cards, /data/v1/cards/${account_id}
cards + balance Allows access to End user’s card balances /data/v1/cards/${account_id}/balance
cards + transactions Allows access to End user’s card transactions /data/v1/cards/${account_id}/transactions
cards + transactions + balance Allows access to End user’s card transactions along with running balance /data/v1/cards/${account_id}/transactions
offline_access Allows access to End user’s data after the short-lived access_token expires. When this permission is granted a refresh_token will be returned refresh_token
direct_debits Allows access to End user’s direct debits. Open Banking providers only /data/v1/accounts/${account_id}/direct_debits
standing_orders Allows access to End user’s standing orders. Open Banking providers only /data/v1/accounts/${account_id}/standing_orders

Request

https://auth.truelayer.com/\
  ?response_type=code\
  &response_mode=form_post\
  &client_id=${client_id}\
  &redirect_uri=${redirect_uri}\
  &scope=${scope}\
  &state=${state}

The first step in the authentication process is to redirect the End user with a properly formatted link to TrueLayer Authorization Server. If the provider used for the authentication is already known, it can be supplied with an optional provider_id parameter in order to skip the selection.

Note that even if you include a provider_id parameter, the intended provider must still be included in the parameter providers. For example, if you use provider_id=uk-ob-lloyds, under providers you must include either uk-ob-all or uk-ob-lloyds.

To easily generate your Auth Link you can use the Auth Link Builder in our Console.

Parameters

Parameter Description
client_id Your client unique identifier
redirect_uri Must exactly match one of the registered redirect_uri for your Client
state An opaque value used by the Client to maintain state between the request and callback.
scope Space-separated list of requested permissions. Please see Permissions
response_type MUST be: "code"
providers OPTIONAL. Space-separated list of providers to include. If not provided, will default to the TrueLayer default list, which is providers=uk-oauth-all uk-ob-all.
provider_id OPTIONAL. If supplied provider selection will be skipped.
response_mode OPTIONAL. if set to "form_post" the code will be submitted via form POST instead of a query string encoded redirect.
disable_providers OPTIONAL. Space-separated list of provider ids to be hidden in the authentication dialog
language_id OPTIONAL. Choose the language for AuthDialog. If not specified, AuthDialog defaults to English. Supported values: en (English), es (Spanish), it (Italian), fr (French), de (German).

To enable Mock Bank, our fictitious bank for testing, include provider uk-cs-mock. See Mock Users.

Once submitted, this will start a regular OAuth2 authorization_code flow. Optionally, you may choose to use a PKCE flow which is a more secure option for mobile and javascript based implementations.

Optional PKCE flow

PKCE requires a code_verifier. This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

The code_verifier is held on to by the client and passed on a back channel during final code exchange. To initiate PKCE flow, during the auth-link phase, the following parameters must be supplied

Parameter Description
code_challenge Base64Url encoded string of the SHA256 hash of the code_verifier.
code_challenge_method “S256”

Request

# This value will be sent on code exchange
code_verifier=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 64 ; echo '')

# the `code_challenge` hash *must* be derived from
# the binary representation of the `code_verifier`.
# It *must* be Base64Url encoded
code_challenge=$(printf %s "${code_verifier}" | openssl dgst -sha256 -binary | base64 | sed 's/+/-/g; s/\//_/g; s/=//g';)

https://auth.truelayer.com/\
  ?response_type=code\
  &response_mode=form_post\
  &client_id=${client_id}\
  &redirect_uri=${redirect_uri}\
  &scope=${scope}\
  &state=${state}\
  &code_challenge=${code_challenge}\
  &code_challenge_method=S256

Provider Format

For including under the providers or disable_providers parameters in the AuthLink, Provider IDs have the format CountryCode-AccessMethod-BankIdentifier. For example: uk-ob-lloyds, uk-oauth-starling. Some BankIdentifier can contain information specific to the bank; e.g. uk-ob-lloyds-business for Business users of Lloyds Bank.

The list of providers can include a list of individual, country-specific providers (e.g. uk-ob-hsbc-business, uk-oauth-starling), or you can use an aggregated label to include all banks from a country (uk-ob-all, ie-ob-all), or all countries for a given bank (all-ob-revolut).

To include new banks that TrueLayer releases as soon as they are available, use “all” for “Bank Identifier” in your provider flag for a given country and access method. For instance, “uk-ob-all” will include all Open Banking banks in the UK, including new ones when they are released.

To enable Mock Bank, our fictitious bank for testing, include provider uk-cs-mock.

Backwards Compatibility

We are backwards compatible with our legacy provider_id schema. This means that in the UK, we would accept provider_id’s without the uk- prefix. In the example provided above, we would also therefore accept ob-lloyds-business.

Direct Bank Authentication

Request

curl -X POST -H "Content-Type: application/json" \
   -d response_type=code \
   -d client_id=${client_id} \
   -d redirect_uri=${redirect_uri} \
   -d scope=${scopes} \
   -d state=${state} \
   -d consent_id=${consent_id} \
   -d provider_id=${provider_id} \
   -d auth_inputs={
    "<auth_input_id>": "<auth_input_value>",
    ...
   }
  https://auth.truelayer.com/v1/authuri

Response

    {
      "result": "https://example.com"
    }

Direct Bank Authentication is an alternative authorisation flow which can be used by regulated clients (those with permission to capture user consent themselves). In this flow, you can retrieve from TrueLayer a link directly to the bank - send your user to this link where they can approve access to their bank account.

Parameters

Field Type Description
response_type string "code"
client_id string TrueLayer client_id
redirect_uri string A valid redirect_uri for your TrueLayer client_id (set in your Console)
state string OPTIONAL. An opaque value used by the Client to maintain state between the request and callback
scope string Space delimited list of desired TrueLayer scopes
consent_id string Identifier to indicate the client has captured the user’s consent themselves. Any alphanumeric string allowed. Should be unique to track that the user has given consent.
provider_id string Intended provider. See our Providers API to look up a provider_id.
auth_inputs array OPTIONAL. For banks that require extra inputs before the user is directed to the bank, those values are specified here. If necessary these Auth Inputs are specified through our Providers API.
code_challenge string OPTIONAL. PKCE code challenge
code_challenge_method string MANDATORY "S256" only if code_challenge is supplied
response_mode string OPTIONAL. "form_post"

Response

We will return a link for the user to follow to authenticate with their bank.

Parameter Description
result A link to the bank for the user to follow

The user will then follow the link to their bank’s app or website to approve sharing of data, after which they will be sent through the Code redirect.

Reauthentication flow

Request

curl -X POST -H "Content-Type: application/json" \
   -d redirect_uri=${redirect_uri} \
   -d response_type=code \
   -d refresh_token=${refresh_token} \
https://auth.truelayer.com/v1/reauthuri

Response

    {
      "result": "https://example.com"
    }

Most European banks require that end-users who are sharing account details grant permission for data sharing every 90 days.

For these banks, access to your user’s bank accounts will no longer be available 90 days after they initially connect their account. When this happens, the TrueLayer /connect/token endpoint will return a 400 invalid_grant error when you try to refresh your tokens, and if you try to fetch data using an access_token TrueLayer will return a 403 access_denied error.

The reauthentication flow provides a simple path for the user to follow to reconnect their account, providing a shorter user journey compared to setting up their account for the first time.

To initiate the Reauthentication flow, call our reauth url with a refresh_token for the user you would like to re-authenticate. We will return a link to the bank for the user to follow. You can have the user go through this flow either before or after their original connection expires (for example, you may prefer to have users reconnect their accounts a week before the connection expires, which would reset the expiration to 90 days from the time of reauthentication).

Users can use the reauthentication flow for up to 90 days after their associated refresh_token expires. (The expiration time varies based on the underlying bank but in general you will have at least 90 days after their connection has expired in which to use the reauthentication flow). After that time has elapsed, reauthentication is no longer possible and the user should go through the first-time authentication flow instead.

Parameters

Field Type Description
redirect_uri string A valid redirect_uri for your TrueLayer client_id (set in your Console)
response_type string "code"
refresh_token string refresh token for the PSU you wish to re-authenticate
state string OPTIONAL. An opaque value used by the Client to maintain state between the request and callback
code_challenge string OPTIONAL. PKCE code challenge
code_challenge_method string MANDATORY "S256" only if code_challenge is supplied
response_mode string OPTIONAL. "form_post"

Response

We will return a link for the user to follow to reauthenticate with their bank.

Parameter Description
result A link to the bank for the user to follow

The user will then follow the link to their bank’s app or website, approve continued sharing of data, and will be returned to you at the specified redirect_uri with a code to swap for access and refresh tokens, just as in the first-time user authentication flow.

Note that it is possible for the user to select a different set of accounts to share when approving continued data sharing with their bank (for example, from sharing a current account and a savings account at first to just sharing the current account after reauthenticating). Some, but not all, banks require the user to choose exactly the same set of accounts that they had shared previously, but because not all banks enforce this requirement it is possible the list will change.

To safeguard against the reauthentication flow being used by the wrong user, if the user chooses to share a completely different set of accounts (with no overlap with their previous selection), you will receive a 403 access_denied when trying to access their bank data. If you expect the user to choose a new set of accounts, have them connect their accounts as if they are a new user, not by using the reauthentication flow.

Mock users

These credentials can be used with the mock bank for testing normal behaviour and errors.

Username Password Behaviour
"john" "doe" Working normally with fake data.*
"error.account_permanently_locked" "error" Any endpoint will fail with account_permanently_locked
"error.account_temporarily_locked" "error" Any endpoint will fail with account_temporarily_locked
"error.internal_error" "error" Any endpoint will fail with internal_error
"error.provider_error" "error" Any endpoint will fail with provider_error
"error.user_input_required" "error" Any endpoint will fail with user_input_required
"error.wrong_credentials" "error" Any endpoint will fail with wrong_credentials

*Multiple user accounts can be tested with the following username/password combinations: john1/doe1, john2/doe2, up to john100/doe100.

Code redirect

Request

code=${code}&scope=${scope}&state=${state}

End user’s browser is redirected to perform an HTTP GET (or HTTP POST in case response_mode has been set to "form_post") to the redirect_uri controlled by the Client with the following parameters:

Parameters
Parameter Description
code A one-time code that can be exchanged with an access_token. The code has a lifetime of 5 minutes.
state An opaque value used by the Client to maintain state between the request and callback.
scope Space-separated list of granted permissions. Please see Permissions
error If the user doesn’t grant the request scopes the redirect will contain an error parameter with value access_denied

Exchange code with access token

Request

curl -X POST \
    -d grant_type=authorization_code \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d redirect_uri=${redirect_uri} \
    -d code=${code} \
    -d code_verifier=${code_verifier} ## Only if using PKCE flow
    https://auth.truelayer.com/connect/token

Response

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": "JWT-EXPIRY-TIME",
  "token_type": "Bearer",
  "refresh_token": "REFRESH-TOKEN-HERE"
}

After a code is obtained by the Client via redirect it can be exchanged for a short-lived access_token

Parameters

Parameter Description
client_id Your unique client identifier
client_secret Your client secret
code one-time code obtained via the redirect
grant_type Must be: "authorization_code"
redirect_uri Must match the registered redirect_uri that was used to authorize access to the account.
code_verifier Required only if using PKCE flow. Must be the code_verifier used to generate the code_challenge

Response

The Authorization server will respond with JSON

Parameter Description
access_token A short-lived JWT token used to access data on behalf of the End user
expire_in access_token validity in seconds. Default is 1 hour or specified by provider.
refresh_token A long-lived code used to obtain a new access_token when expired. It will be returned only if the scope offline_access was requested
token_type Must be: Bearer

Renew the access_token

Request

curl -X POST \
    -d grant_type=refresh_token \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d refresh_token=${refresh_token} \
    https://auth.truelayer.com/connect/token

Response

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": "JWT-EXPIRY-TIME",
  "token_type": "Bearer",
  "refresh_token": "REFRESH-TOKEN-HERE"
}

After the short-lived access_token expires (1 hour by default) a new access_token can be requested using a refresh_token

Parameters

Parameter Description
grant_type Must be: "refresh_token"
client_id Your unique client identifier
client_secret Your client secret
refresh_token The refresh_token

Response

Parameter Description
access_token A short-lived JWT token used to access data on behalf of the End user
expire_in access_token validity in seconds. Default is 1 hour
refresh_token A new refresh_token that must be used instead of the previous one
token_type Must be: Bearer

Delete encrypted credentials

Request

curl -X DELETE -H "Authorization: Bearer ${access_token}" \
  https://auth.truelayer.com/api/delete

This endpoint will revoke the access associated with the access token used for the request.

Submit access token for debug

Request

curl -X POST -H "Content-Type: application/json" \
  -d '{"access_token": "ACCESS-TOKEN-HERE"}' https://auth.truelayer.com/api/debug

Response

{
"credentials_id": "SSwF1CgQMLOs0qratFpybzF7uJ3hxwppiw1C4s+rT4I=",
"debug_id": "mock|U1N3RjFDZ1FNTE9zMHFyYXRGcHliekY3dUozaHh3cHBpdzFDNHMrYXk0ST0",
"provider_id": "mock"
}
DELETE /api/debug
Content-Type: application/json

{"access_token": "ACCESS-TOKEN-HERE"}
curl -X DELETE -H "Content-Type: application/json" \
  -d '{"access_token": "ACCESS-TOKEN-HERE"}' https://auth.truelayer.com/api/debug
{
    "credentials_id": "SSwF1CgQMLOs0qratFpybzF7uJ3hxwppiw1C4s+rT4I=",
    "debug_id": "mock|U1N3RjFDZ1FNTE9zMHFyYXRGcHliekY3dUozaHh3cHBpdzFDNHMrYXk0ST0",
    "provider_id": "mock"
}

This endpoint will return a debug_id that will allow TrueLayer to debug a particular issue. You can delete the credentials from the endpoint in two ways:

Remove the credentials completely using the delete endpoint found here or remove just the debug credentials using the /debug endpoint.

Response

Parameter Description
credentials_id Unique TrueLayer credential ID
debug_id Computed TrueLayer key
provider_id Unique TrueLayer provider ID

List of supported providers

Request

curl https://auth.truelayer.com/api/providers

Response

{
        "display_name": "RBS Scotland",
        "logo_url": "https://auth.truelayer.com/img/banks/banks-icons/rbs-digital-icon.svg",
        "provider_id": "rbs-digital",
        "scopes": [
            "info",
            "accounts",
            "transactions",
            "balance",
            "cards",
            "offline_access"
        ],
        "country": "uk"

    }

This endpoint returns the list of supported providers:

The endpoint returns all providers in production, from every country. When TrueLayer adds new providers they will automatically be returned by this endpoint.

clientId is an optional query parameter. If you include your TrueLayer Client ID, the endpoint will return all providers that your account has access to, including providers that are currently in beta:

Response

Parameter Description
provider_id Unique TrueLayer provider ID
display_name Human friendly provider name
logo_url URL to the provider’s logo as used by TrueLayer
scopes List of Permissions supported by the provider
country Country where the provider is available

Retrieve access_token metadata

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/me

Response

{
    "results": [
        {
            "client_id": "test",
            "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
            "consent_status": "Authorised",
            "consent_status_updated_at": "2020-05-24T15:44:40.077Z",
            "consent_created_at": "2020-05-24T14:44:40.077Z",
            "consent_expires_at": "2020-08-24T14:44:40.077Z",
            "provider": {
                "display_name": "Lloyds Bank",
                "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
                "provider_id": "lloyds"
            },
            "scopes": [
                "info",
                "accounts",
                "balance",
                "transactions",
                "cards",
                "offline_access"
            ],
            "privacy_policy": "Feb2019"
        }
    ]
}

Returns access_token metadata.

Response

Field Type Description Auth Method
client_id string Your unique client identifier All
credentials_id string Unique identifier of the set of credentials All
consent_status string Consent status. Possible responses: Rejected, Authorised, Revoked or AwaitingAuthorisation OB
consent_status_updated_at string OPTIONAL (returned if available). Consent status update date OB
consent_created_at string OPTIONAL (returned if available). Consent creation date OB
consent_expires_at string OPTIONAL (returned if available). Consent expiration date OB
provider.display_name string Display name for the Provider All
provider.logo_uri string URI for the Provider logo All
provider.provider_id string Unique identifier for the Provider All
scopes array Permission intersection for the End user and Provider All
privacy_policy string The version of TrueLayer’s Privacy Policy that the owner of the set of credentials has given consent to All

Retrieve identity information

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/info

Response

{
    "results": [
        {
            "addresses": [
                {
                    "address": "1 Market Street",
                    "city": "San Francisco",
                    "country": "US",
                    "zip": "94103"
                }
            ],
            "date_of_birth": "1984-07-03T00:00:00",
            "emails": [
                "john@doe.com"
            ],
            "full_name": "John Doe",
            "phones": [
                "+14151234567"
            ],
            "update_timestamp": "0001-01-01T00:00:00Z"
        }
    ]
}

Returns End user’s identity information held by the Provider. This can include name, address, emails and phone numbers.

When implementing this endpoint, the end user’s data should be requested within five minutes of the consent grant, and stored if necessary for your use case. Provider implementations of this endpoint differ due to varying interpretations of Article 10 of PSD2’s Regulatory Technical Standards on Strong Customer Authentication. If the data becomes unavailable, we will return an “sca_exceeded” error message.

Response

Field Type Description
update_timestamp datetime last time the data has been updated from the provider
full_name string Full name of the End user
date_of_birth datetime OPTIONAL. Date of birth of the End user
addresses[...].address string OPTIONAL. Full address of the End user
addresses[...].city string OPTIONAL. City
addresses[...].state string OPTIONAL. State
addresses[...].zip string OPTIONAL. Post code
addresses[...].country string OPTIONAL. ISO-3166-1 alpha-3 code of the country
emails[...] Array of strings Email addresses (if none available returns empty array)
phones[...] Array of strings Phone numbers (if none available returns empty array)

List all accounts

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts

Response

{
  "results": [
    {
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "account_id": "f1234560abf9f57287637624def390871",
      "account_type": "TRANSACTION",
      "display_name": "Club Lloyds",
      "currency": "GBP",
      "account_number": {
        "iban": "GB35LOYD12345678901234",
        "number": "12345678",
        "sort_code": "12-34-56",
        "swift_bic": "LOYDGB2L"
      },
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    },
    {
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "account_id": "f1234560abf9f57287637624def390872",
      "account_type": "SAVINGS",
      "display_name": "Club Lloyds",
      "currency": "GBP",
      "account_number": {
        "iban": "GB35LOYD12345678901235",
        "number": "12345679",
        "sort_code": "12-34-57",
        "swift_bic": "LOYDGB2L"
      },
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    }
  ]
}

Returns all End user’s accounts and associated data

Response

Field Type Description
account_id string Unique identifier of the account
account_type string Type of the account
account_number.iban string OPTIONAL. ISO 13616-1:2007 international bank number
account_number.number string OPTIONAL (only returned for UK accounts). Bank account number
account_number.sort_code string OPTIONAL (only returned for UK accounts). United Kingdom SORT code
account_number.swift_bic string ISO 9362:2009 Business Identifier Codes
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human-readable name of the account
update_timestamp datetime Last update time of the account information
provider.display_name string Display name for the Provider
provider.logo_uri string URI for the Provider logo
provider.provider_id string Unique identifier for the Provider
description string Description of the account

Account types

These account types are currently supported and can be returned as account_type

Type Description
TRANSACTION A transaction account is a checking account or current account
SAVINGS A savings account is an interest-bearing deposit account
BUSINESS_TRANSACTION A transaction account for a business
BUSINESS_SAVINGS A savings account for a business

Retrieve an account

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}

Response

{
  "results": [
    {
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "account_id": "f1234560abf9f57287637624def390871",
      "account_type": "TRANSACTION",
      "display_name": "Club Lloyds",
      "currency": "GBP",
      "account_number": {
        "iban": "GB35LOYD12345678901234",
        "number": "12345678",
        "sort_code": "12-34-56"
      },
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    }
  ]
}

Returns data associated with the specified account_id

Response

Field Type Description
account_id string Unique identifier of the account
account_type string Type of the account
account_number.iban string OPTIONAL (not returned by internal savings accounts on credential sharing). ISO 13616-1:2007 international bank number
account_number.number string OPTIONAL (only returned for UK accounts). Bank account number
account_number.sort_code string OPTIONAL (only returned for UK accounts). United Kingdom SORT code
account_number.swift_bic string ISO 9362:2009 Business Identifier Codes
account_number.blz string OPTIONAL (only returned for Germany-based accounts). Bankleitzahl
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human-readable name of the account
update_timestamp datetime Last update time of the account information
provider.display_name string Display name for the Provider
provider.logo_uri string URI for the Provider logo
provider.provider_id string Unique identifier for the Provider
description string Description of the account

Account types

These account types are currently supported and can be returned as account_type

Type Description
TRANSACTION A transaction account is a checking account or current account
SAVINGS A savings account is an interest-bearing deposit account
BUSINESS_TRANSACTION A transaction account for a business
BUSINESS_SAVINGS A savings account for a business

Retrieve account balance

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}/balance

Response

{
  "results": [
    {
      "currency": "GBP",
      "available": 1161.2,
      "current": 1161.2,
      "overdraft": 1000,
      "update_timestamp": "2017-02-07T17:33:30.001222Z"
    }
  ]
}

Returns balance information for the specified account_id

Response

Field Type Description
available number OPTIONAL. Available balance, including pre-arranged overdraft limit
currency string ISO 4217 alpha-3 currency code
current number Current balance
overdraft number OPTIONAL. Pre-arranged overdraft limit. Available for all “TRANSACTION” and “BUSINESS_TRANSACTION” account types. See Account Types
update_timestamp datetime OPTIONAL (if applicable). Last update time

Retrieve account transactions

Request

curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/accounts/${account_id}/transactions?from=${from}&to=${to}"

Response

{
  "results": [
    {
      "transaction_id": "03c333979b729315545816aaa365c33f",
      "timestamp": "2018-03-06T00:00:00",
      "description": "GOOGLE PLAY STORE",
      "amount": -2.99,
      "currency": "GBP",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "transaction_classification": [
        "Entertainment",
        "Games"
      ],
      "merchant_name": "Google play",
      "running_balance": {
        "amount": 1238.60, 
        "currency": "GBP"
      },
      "meta": {
        "bank_transaction_id": "9882ks-00js",
        "provider_transaction_category": "DEB"
      }
    },
    {
      "transaction_id": "3484333edb2078e77cf2ed58f1dec11e",
      "timestamp": "2018-02-18T00:00:00",
      "description": "PAYPAL EBAY",
      "amount": -25.25,
      "currency": "GBP",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "transaction_classification": [
        "Shopping",
        "General"
      ],
      "merchant_name": "Ebay",
      "meta": {
        "bank_transaction_id": "33b5555724",
        "provider_transaction_category": "DEB"
      }
    }
  ]
}

Returns transaction data for the specified account_id.

Parameters

Field Type Description
from datetime OPTIONAL. Returns transactions posted on or after this date. Default value is date as of the API request minus 3 months
to datetime OPTIONAL. Returns transactions up to and including this date. Default value is date as of the API request

Response

Field Type Description
transaction_id string Unique identifier of the transaction in a request. It may change between requests.
timestamp datetime Date the transaction was posted on the account
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
transaction_classification array Classification of the transaction (array can be empty if classification has not been successfully assigned)
merchant_name string OPTIONAL (if merchant has been identified). Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata
running_balance.amount number OPTIONAL. If available, contains the running balance
running_balance.currency string OPTIONAL. If available, contains the running balance currency - ISO 4217 alpha-3 currency code

Retrieve account pending transactions

Request

curl -H "Authorization: Bearer ${access_token}" \
 "https://api.truelayer.com/data/v1/accounts/${account_id}/transactions/pending"

Response

{
 "results": [
   {
     "transaction_id": "03c333979b729315545816aaa365c33f",
     "timestamp": "2018-11-18T00:00:00",
     "description": "GOOGLE PLAY STORE",
     "amount": -2.99,
     "currency": "GBP",
     "transaction_type": "DEBIT",
     "transaction_category": "PURCHASE",
     "transaction_classification": [
       "Entertainment",
       "Games"
     ],
     "merchant_name": "Google play",
     "running_balance": {
       "amount": 1238.60, 
       "currency": "GBP"
     },
     "meta": {
       "bank_transaction_id": "9882ks-00js",
       "provider_transaction_category": "DEB"
     }
   },
   {
     "transaction_id": "3484333edb2078e77cf2ed58f1dec11e",
     "timestamp": "2018-11-18T00:00:00",
     "description": "PAYPAL EBAY",
     "amount": -25.25,
     "currency": "GBP",
     "transaction_type": "DEBIT",
     "transaction_category": "PURCHASE",
     "transaction_classification": [
       "Shopping",
       "General"
     ],
     "merchant_name": "Ebay",
     "meta": {
       "bank_transaction_id": "33b5555724",
       "provider_transaction_category": "DEB"
     }
   }
 ]
}

Returns pending transaction data for the specified account_id.

Response

Field Type Description
transaction_id string Unique identifier of the transaction in a request. It may change between requests.
timestamp datetime Date the transaction was posted on the account
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
transaction_classification array Classification of the transaction (array can be empty if classification has not been successfully assigned)
merchant_name string OPTIONAL (if merchant has been identified). Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata
running_balance.amount number OPTIONAL. If available, contains the running balance
running_balance.currency string OPTIONAL. If available, contains the running balance currency - ISO 4217 alpha-3 currency code

Retrieve direct debits

Request

curl -H "Authorization: Bearer ${access_token}" \
 "https://api.truelayer.com/data/v1/accounts/${account_id}/direct_debits"

Response

{
    "results": [{
        "direct_debit_id": "004ea8ce16b6ff57090b7bf8c7b483a1",
        "timestamp": "2019-07-19T17:28:37.798+01:00",
        "name": "EE",
        "status": "Active",
        "previous_payment_timestamp": "2018-09-17T00:00:00+01:00",
        "previous_payment_amount": 25.0,
        "currency": "GBP",
        "meta": {
            "provider_mandate_identification": "6",
            "provider_account_id": "1000000000000000001"
        }
    }, {
        "direct_debit_id": "8e5dfbc5b4d66c8aff248e9ca6440c55",
        "timestamp": "2019-07-19T17:28:37.805+01:00",
        "name": "PAYPAL",
        "status": "Active",
        "previous_payment_timestamp": "2019-07-18T00:00:00+01:00",
        "previous_payment_amount": 4.99,
        "currency": "GBP",
        "meta": {
            "provider_mandate_identification": "9",
            "provider_account_id": "1000000000000000001"
        }
    }, {
        "direct_debit_id": "72699309c9be1226e46e5257fb24133f",
        "timestamp": "2019-07-19T17:28:37.805+01:00",
        "name": "BT INTERNET",
        "status": "Active",
        "previous_payment_timestamp": "2018-09-18T00:00:00+01:00",
        "previous_payment_amount": 16.99,
        "currency": "GBP",
        "meta": {
            "provider_mandate_identification": "7",
            "provider_account_id": "1000000000000000001"
        }
    }],
    "status": "Succeeded"
}

Returns direct debit data for the specified account_id.

When implementing this endpoint, the end user’s data should be requested within five minutes of the consent grant, and stored if necessary for your use case. Provider implementations of this endpoint differ due to varying interpretations of Article 10 of PSD2’s Regulatory Technical Standards on Strong Customer Authentication. If the data becomes unavailable, we will return an “sca_exceeded” error message.

Response

Field Type Description
direct_debit_id string Unique identifier of the direct debit in a request. It may change between requests.
timestamp datetime Date and time the request was made
name string Name of the service or user returned by the Provider
status string OPTIONAL. This can either be Active or Inactive
previous_payment_timestamp datetime OPTIONAL. Date of the latest payment
previous_payment_amount string OPTIONAL. Amount of the latest payment
currency string OPTIONAL. ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata

Retrieve standing orders

Request

curl -H "Authorization: Bearer ${access_token}" \
 "https://api.truelayer.com/data/v1/accounts/${account_id}/standing_orders"

Response

{
    "results": [
        {
            "frequency": "IntrvlMnthDay:01:26",
            "status": "Active",
            "timestamp": "2019-07-24T11:29:47.414+00:00",
            "currency": "GBP",
            "meta": {
                "provider_account_id": "12345ca1-18fd-4e6b-891e-0597cac6bb8c"
            },
            "next_payment_date": "2019-07-26T00:00:00+00:00",
            "next_payment_amount": 500.0,
            "first_payment_date": "2019-06-26T00:00:00+00:00",
            "first_payment_amount": 0.0,
            "final_payment_date": "9999-12-31T00:00:00+00:00",
            "final_payment_amount": 0.0,
            "reference": "Savings"
        },
        {
            "frequency": "IntrvlMnthDay:01:30",
            "status": "Active",
            "timestamp": "2019-07-24T11:29:47.416+00:00",
            "currency": "GBP",
            "meta": {
                "provider_account_id": "12345ca1-18fd-4e6b-891e-0597cac6bb8c"
            },
            "next_payment_date": "2019-07-30T00:00:00+00:00",
            "next_payment_amount": 500.0,
            "first_payment_date": "2019-01-01T00:00:00+00:00",
            "first_payment_amount": 0.0,
            "final_payment_date": "9999-12-31T00:00:00+00:00",
            "final_payment_amount": 0.0,
            "payee": "JOHN DOE",
            "reference": "MONZO"
        }
    ],
    "status": "Succeeded"
}

Returns standing order data for the specified account_id.

When implementing this endpoint, the end user’s data should be requested within five minutes of the consent grant, and stored if necessary for your use case. Provider implementations of this endpoint differ due to varying interpretations of Article 10 of PSD2’s Regulatory Technical Standards on Strong Customer Authentication. If the data becomes unavailable, we will return an “sca_exceeded” error message.

Response

Field Type Description
frequency string Frequency of the standing order. Possible values: EvryDay - every day, EvryWorkgDay - every working day, IntrvlDay:XX - every XX calendar day, IntrvlMnthDay:XX:YY - every XXth month on the YYth day of the month, IntrvlWkDay:XX:YY - every XXth week, on the YYth day of the week, QtrDay - quarterly - , WkInMnthDay:XX:YY -every month, on the XXth week of the month and on the YYth day of the week.
status string OPTIONAL. This can either be Active or Inactive
timestamp datetime Date and time the request was made
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata
next_payment_date datetime OPTIONAL. The date on which the next payment for the standing order schedule will be made.
next_payment_amount string OPTIONAL. Amount of the next payment for the standing order
first_payment_date datetime OPTIONAL. The date on which the first payment for the standing order schedule will be or was made.
first_payment_amount string OPTIONAL. Amount of the first payment for the standing order
final_payment_date datetime OPTIONAL. The date on which the next payment for a Standing Order schedule will be made.
final_payment_amount string OPTIONAL. Amount of the last payment for the standing order
reference string OPTIONAL. Reference of the standing order set by the user
payee datetime OPTIONAL. Payee of the standing order set by the user

List all cards

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards

Response

{
  "results": [
    {
      "account_id": "f7b093437032c216d4350b7d442b9c5ccc0e9f19",
      "card_network": "VISA",
      "card_type": "CREDIT",
      "currency": "GBP",
      "display_name": "Club Credit Card",
      "partial_card_number": "0044",
      "name_on_card": "A. N. Other",
      "valid_from": "2017-01",
      "valid_to": "2018-01",
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    },
    {
      "account_id": "ad86fb1c213245b6b6594895068973efca5f9367",
      "card_network": "MASTERCARD",
      "card_type": "CHARGE",
      "currency": "GBP",
      "display_name": "Club Charge Card",
      "partial_card_number": "0055",
      "name_on_card": "A. N. Other",
      "valid_from": "2017-01",
      "valid_to": "2018-01",
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    }
  ]
}

Returns all End user’s cards and associated data

Response

Field Type Description
account_id string Unique identifier of the account
card_network string Processing network (eg. VISA)
card_type string Type of card (eg. Credit)
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human-readable name of the account
partial_card_number string Last 4 digits of the card
name_on_card string OPTIONAL. If available, the name on the card
valid_from string OPTIONAL. If available, the valid from date
valid_to string OPTIONAL. If available, the valid to date
update_timestamp datetime Last update time of the card information
provider.display_name string Display name for the Provider
provider.logo_uri string URI for the Provider logo
provider.provider_id string Unique identifier for the Provider

Retrieve a card

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards/${account_id}

Response

{
  "results": [
    {
      "account_id": "f7b093437032c216d4350b7d442b9c5ccc0e9f19",
      "card_network": "VISA",
      "card_type": "CREDIT",
      "currency": "GBP",
      "display_name": "Club Credit Card",
      "partial_card_number": "0044",
      "name_on_card": "A. N. Other",
      "valid_from": "2017-01",
      "valid_to": "2018-01",
      "update_timestamp": "2017-02-07T17:29:24.740802Z",
      "provider": {
        "display_name": "Lloyds Bank",
        "logo_uri": "https://auth.truelayer.com/img/banks/banks-icons/lloyds-icon.svg",
        "provider_id": "lloyds"
      }
    }
  ]
}

Returns a End user’s card and associated data

Response

Field Type Description
account_id string Unique identifier of the account
card_network string Processing network (eg. VISA)
card_type string Type of card (eg. Credit)
currency string ISO 4217 alpha-3 currency code of the account
display_name string Human-readable name of the account
partial_card_number string Last 4 digits of the card
name_on_card string OPTIONAL. If available, the name on the card
valid_from string OPTIONAL. If available, the valid from date
valid_to string OPTIONAL. If available, the valid to date
update_timestamp datetime Last update time of the card information
provider.display_name string Display name for the Provider
provider.logo_uri string URI for the Provider logo
provider.provider_id string Unique identifier for the Provider

Retrieve card balance

Request

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards/${account_id}/balance

Response

{
  "results": [
    {
      "available": 3279.0,
      "currency": "GBP",
      "current": 20.0,
      "credit_limit": 3300,
      "last_statement_balance": 420.0,
      "last_statement_date": "2017-01-28",
      "payment_due": 5.0,
      "payment_due_date": "2017-02-24",
      "update_timestamp": "2017-02-247T17:29:24.740802Z"
    }
  ]
}

Returns card balance information for the specified account_id

Response

Field Type Description
available number OPTIONAL. Available balance
currency string ISO 4217 alpha-3 currency code
current number Current balance
credit_limit number OPTIONAL. Card credit limit
last_statement_balance number OPTIONAL. Card balance at time of last statement, if available
last_statement_date string OPTIONAL. Date of last statement, if available
payment_due number OPTIONAL. Minimum amount required by due date
payment_due_date number OPTIONAL. Date by which payment due should be remitted
update_timestamp datetime Last update time

Retrieve card transactions

Request

curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/cards/${account_id}/transactions?from=${from}&to=${to}"

Response

{
  "results": [
    {
      "transaction_id": "a15d8156569ba848d84c07c34d291bca",
      "timestamp": "2018-01-16T00:00:00+00:00",
      "amount": 24.25,
      "currency": "GBP",
      "description": "SAINSBURYS SMRKT STORE 128",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "running_balance": {
        "amount": 1238.60, 
        "currency": "GBP"
      },
      "meta": {
        "cardNumber": "1234********5678",
        "location": "INTERNET"
      }
    },
    {
      "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
      "timestamp": "2018-03-19T00:00:00",
      "amount": 46.82,
      "currency": "GBP",
      "description": "TALKTALK TELECOM",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "meta":{
        "provider_transaction_category": "DEB",
        "cardNumber": "1234********5678",
        "location": "INTERNET"
      }
    }
  ]
}

Returns card transaction data for the specified account_id.

Parameters

Field Type Description
from datetime OPTIONAL. Returns transactions posted on or after from date. Default value is date as of the API request minus 3 months
to datetime OPTIONAL. Returns transactions up to and including this date. Default value is date as of the API request

Response

Field Type Description
transaction_id string Unique identifier of the transaction in a request. It may change between requests.
timestamp datetime Date the transaction was posted on the account
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
transaction_classification array Classification of the transaction (array can be empty if classification has not been successfully assigned)
merchant_name string OPTIONAL (if merchant has been identified). Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata
running_balance.amount number OPTIONAL. If available, contains the running balance
running_balance.currency string OPTIONAL. If available, contains the running balance currency - ISO 4217 alpha-3 currency code

Retrieve card pending transactions

Request

curl -H "Authorization: Bearer ${access_token}" \
 "https://api.truelayer.com/data/v1/cards/${account_id}/transactions/pending"

Response

{
 "results": [
   {
      "transaction_id": "a15d8156569ba848d84c07c34d291bca",
      "timestamp": "2018-01-16T00:00:00+00:00",
      "amount": 24.25,
      "currency": "GBP",
      "description": "SAINSBURYS SMRKT STORE 128",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "running_balance": {
        "amount": 1238.60, 
        "currency": "GBP"
      },
      "meta": {
        "cardNumber": "1234********5678",
        "location": "INTERNET"
      }
    },
    {
      "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
      "timestamp": "2018-03-19T00:00:00",
      "amount": 46.82,
      "currency": "GBP",
      "description": "TALKTALK TELECOM",
      "transaction_type": "DEBIT",
      "transaction_category": "PURCHASE",
      "meta":{
        "provider_transaction_category": "DEB",
        "cardNumber": "1234********5678",
        "location": "INTERNET"
      }
    }
  ]
}

Returns card pending transaction data for the specified account_id.

Response

Field Type Description
transaction_id string Unique identifier of the transaction in a request. It may change between requests.
timestamp datetime Date the transaction was posted on the account
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
transaction_classification array Classification of the transaction (array can be empty if classification has not been successfully assigned)
merchant_name string OPTIONAL (if merchant has been identified). Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata
running_balance.amount number OPTIONAL. If available, contains the running balance
running_balance.currency string OPTIONAL. If available, contains the running balance currency - ISO 4217 alpha-3 currency code

Retrieve cards and accounts transactions with a single call

Enqueueing a batch task

You can retrieve all cards and accounts transactions with a single API call using our batch endpoint.

Batch calls are asynchronous by default: in the response you will find a results_uri where you can fetch the transactions once the batch task is complete.

If you specify a webhook_uri you will receive a webhook notification when the status of your task changes (it becomes either Succeeded or Failed) - the webhook notification payload can be found here.

You can retrieve cards and accounts transactions once the task is complete using our /batch/results endpoint can be found here.

Request

# Save the payload in a file, e.g. `request.json`
{
  "from": "2019-05-10",
  "to": "2019-05-20",
  "pending": true,
  "balance": true,
  "webhook_uri": "https://your-webhook-uri.com/"
} 
curl -X POST -d @request.json \
  -H "Authorization: Bearer ${access_token}" \ 
  -H "Content-Type:application/json" \
  https://api.truelayer.com/data/v1/batch/transactions

Response

{
    "results_uri": "https://api.truelayer.com/data/v1/batch/results/0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43",
    "status": "Queued",
    "task_id": "0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43"
}
Request - Endpoint

POST /data/v1/batch/transactions

Request - Headers
Header Value
Content-Type application/json
Authorization Bearer <ACCESS_TOKEN>
Request - Body
Field Required Example Description
from Yes 2019-01-07 or
2019-01-07T10:00:00
An ISO8601 encoded date or datetime that specifies the lower limit of the time window you want to fetch transactions for.
to Yes 2019-05-07 or
2019-05-07T17:00:00
An ISO8601 encoded date or datetime that specifies the upper limit of the time window you want to fetch transactions for.
webhook_uri No https://app.api.example.com/ The endpoint that will receive our notification webhook.
The webhook will be fired as a POST request - query parameters are allowed.
pending No true If set, also the pending transactions will be included in the response (if not specified it defaults to false ).
If the provider doesn’t support pending transactions, they won’t be included in the response.
balance No true If set, the balance will also be returned for each account and/or card.
account_ids_whitelist No ["32828340fa4c", "3100e17de12145"] A JSON array of account/card ids to be whitelisted - only accounts with the corresponding id’s will be returned in the batch response. When set in the request body at least one id must be provided. If a whitelisted account is not found, the batch call will fail.
Response
Field Type Description
results_uri string The URI where results can be fetched from when available.
status string The request outcome. If successful, Queued.
task_id string A unique ID associated with the task

Webhook notification for a batch call

Webhook payload

{
    "request_timestamp" : "2019-05-10T00:00:00Z",
    "request_uri" : "https://api.truelayer.com/api/v1/batch/transactions",
    "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
    "task_id": "e1245d07-d846-42df-86d8-99b08b430a0",
    "status": "Succeeded",
    "results_uri": "https://api.truelayer.com/data/v1/batch/results/e1245d07-d846-42df-86d8-99b08b430a0/"
}

When a batch task is completed, this payload will be sent to the webhook_uri specified in the batch request via HTTP POST.

Field Type Description
request_timestamp datetime The ISO8601 encoded datetime specified in the original request
request_uri string The URI of the original request
credentials_id string Unique string identifying a set of End user’s credentials used to access a Provider
task_id string A unique ID associated with the task
status string Succedeed or Failed
results_uri string The URI where results can be fetched from when available.

Retrieve batch results - Success case

If the batch job was successful, you can use the results_uri specified in the webhook payload to fetch your transactions.

Request

curl -H "Authorization: Bearer ${access_token}" \ 
  https://api.truelayer.com/data/v1/batch/results/0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43

Response

{
  "status": "Succeeded",
  "task_id": "0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43",
  "request": {
    "from": "2019-05-10T00:00:00",
    "to": "2019-05-20T00:00:00"
  },
  "results": {
    "accounts": [
      {
        "account_id": "a467e5319ddc9ad99846465bd6f0127e",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "1647dc2acf12438d8c348a379b85814a"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "7cfc04c0f5c4c39a3e168b76ec607799"
          }
        ],
        "pending_transactions": [
          {
            "transaction_id": "a15d8156569ba848d84c07c34d291bca",
            "timestamp": "2019-05-20T00:00:00",
            "amount": 24.25,
            "currency": "GBP",
            "description": "SAINSBURYS SMRKT STORE 128",
            "transaction_type": "DEBIT",
            "transaction_category": "PURCHASE",
            "running_balance": {
              "amount": 1238.6,
              "currency": "GBP"
            },
            "meta": {
              "cardNumber": "1234********5678",
              "location": "INTERNET"
            }
          },
          {
            "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
            "timestamp": "2019-05-20T00:00:00",
            "amount": 46.82,
            "currency": "GBP",
            "description": "TALKTALK TELECOM",
            "transaction_type": "DEBIT",
            "transaction_category": "PURCHASE",
            "meta": {
              "provider_transaction_category": "DEB",
              "cardNumber": "1234********5678",
              "location": "INTERNET"
            }
          }
        ],
        "balance": {
​​            "currency": "GBP",
​​            "available": 200.12,
​​            "current": 200.12,
​​            "overdraft": 0,
​​            "update_timestamp": "2019-05-20T00:00:00"
​​        }
      },
      {
        "account_id": "9586f94c8b253dc83807171339ea5da9",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "f80d0229693f61fcb6c1fb79f2c61af4"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "DEBIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "bdf8979b2d9c80ad1db2053c2e18a483"
          }
        ],
        "pending_transactions": [],
        "balance": {
​​            "currency": "GBP",
​​            "available": 50.08,
​​            "current": 50.08,
​​            "overdraft": 0,
​​            "update_timestamp": "2019-05-20T00:00:00"
​​        }
      }
    ],
    "cards": [
      {
        "account_id": "8901414c1e40d6beb24dfe45f39f3912",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "646a9145784840eb911fef6278fbc4e5"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "27d48b9c7d943c285e870bceba5b033b"
          }
        ],
        "balance": {
​​            "available": 3279.0,
​​            "currency": "GBP",
​​            "current": 20.0,
​​            "credit_limit": 3300,
​​            "last_statement_balance": 420.0,
​​            "last_statement_date": "2019-04-30",
​​            "payment_due": 5.0,
​​            "payment_due_date": "2019-05-20",
​​            "update_timestamp": "2019-05-107T17:29:24.740802Z"
        }
      },
      {
        "account_id": "afb594831dacd544563b20be7c362a51",
        "transactions": [
          {
            "timestamp": "2019-05-10T00:00:00",
            "description": "EDF ENERGY",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Bills and Utilities",
              "Utilities"
            ],
            "merchant_name": "EDF ENERGY",
            "amount": -24.5,
            "currency": "GBP",
            "transaction_id": "cc96f312d45f2c96d9464e69873d6a04"
          },
          {
            "timestamp": "2019-05-20T00:00:00",
            "description": "REGENDA REDWING",
            "transaction_type": "CREDIT",
            "transaction_category": "UNKNOWN",
            "transaction_classification": [
              "Investments",
              "Real-estate"
            ],
            "merchant_name": "REDWING LIVING",
            "amount": -150,
            "currency": "GBP",
            "transaction_id": "da5c341e2b790bb3bcfd0235829df37c"
          }
        ],
        "balance": {
​​            "available": 510.0,
​​            "currency": "GBP",
​​            "current": 200.0,
​​            "credit_limit": 710,
​​            "last_statement_balance": 420.0,
​​            "last_statement_date": "2019-04-30",
​​            "payment_due": 10.0,
​​            "payment_due_date": "2019-05-20",
​​            "update_timestamp": "2019-05-107T17:29:24.740802Z"
        }
      }
    ]
  }
}
Request - Endpoint

GET /data/v1/batch/results/<your-task-id>

Request - Headers
Header Value
Authorization Bearer <ACCESS_TOKEN>
Response

The schema of the response retrieved from results_uri has the following top-level structure:

Field Type Description
results BatchResult A BatchResult object. See below for its schema.
request BatchRequest An object containing the parameters used for the request. See below for its schema.
task_id string A unique ID associated with the task.
status string The request outcome. If successful, Succeeded.

BatchRequest has the following structure:

Field Type Description
from datetime The ISO8601 encoded date time passed as from query parameter in the original batch endpoint request.
to datetime The ISO8601 encoded date time passed as to query parameter in the original batch endpoint request.

BatchResult has the following structure:

Field Type Description
cards Asset list A list of Asset objects, one for each card associated to the credential set the token belongs to. See below for their schema.
accounts Asset list A list of Asset objects, one for each account associated to the credential set the token belongs to. See below for their schema.

Asset has the following structure:

Field Type Description
account_id string A unique ID associated with the card or the account (the same that would be returned if using /cards or /accounts)
transactions object list The list of transactions associated with the account or card for the specified time window.
pending_transactions object list The list of the pending transactions associated with the account or card (if there are no pending transactions this field will contain an empty list).
balance object object The account balance of the account or card.

Each element in the transactions array has the same schema of a transaction returned from /accounts/{account_id}/transactions or /cards/{account_id}/transactions.

Each element in the pending_transactions array has the same schema of a transaction returned from /accounts/{account_id}/transactions/pending or /cards/{account_id}/transactions/pending.

​​The returned balance​ has the same schema as a balance returned from /accounts/{account_id}/balance or /cards/{account_id}/balance​.

Retrieve batch results - Failure case

If the batch task was unsuccessful, you can use the results_uri specified in the webhook payload to retrieve useful information on what went wrong.

The response contains the details of each failed sub_task.

Request

curl -H "Authorization: Bearer ${access_token}" \ 
  https://api.truelayer.com/data/v1/batch/results/0cf3fca2-e64e-4a35-8280-7c5bd7b5dc43

Response

{
    "status": "Failed",
    "error_details_list": [
        {
            "sub_task_id": "a691d65a-312a-4f90-af2a-369a34cd78ac",
            "status_code": 403,
            "error": "user_input_required",
            "error_description": "Your bank requires your input. Please login on your bank website and try again.",
            "sub_task_type": "Cards"
        },
        {
            "sub_task_id": "85aa4ebd-a385-4d92-83dc-03e3499093d9",
            "status_code": 403,
            "error": "user_input_required",
            "error_description": "Your bank requires your input. Please login on your bank website and try again.",
            "sub_task_type": "Accounts"
        }
    ]
}
Request - Endpoint

GET /data/v1/batch/results/<your-task-id>

Request - Headers
Header Value
Authorization Bearer <ACCESS_TOKEN>
Response
Field Type Description
status string Status of the batch request (Failed)
error_details_list ErrorDetails list A list of ErrorDetails containing details on the failure reason for each failed sub_task

ErrorDetails has the following structure:

Field Type Description
sub_task_id string Id of the failed sub task
status_code int Failure status code of the sub task
error string Failure error code of the sub task (click here for a list of all possible error codes)
error_description string Failure error description of the sub task
sub_task_type string Type of the failed sub task - one of Cards, Accounts, AccountTransactions, CardTransactions, AccountPendingTransactions, CardPendingTransactions)

Retrieve income

Request

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://insights.truelayer.com/v1/accounts/${account_id}/income?from=${from}&to=${to}

Response

{
 "average_total_income_monthly": 3251.62,
 "transaction_history_span_days": 86,
 "sources": [
     {
         "income_type": "salary",
         "name": "some company ltd",
         "average_monthly_income": 3125.12,
         "average_amount": 3125.2,
         "maximum_amount": 3180.24,
         "minimum_amount": 3070,
         "supporting_transactions": [
             {
                  "transaction_id": "a15d8156569ba848d84c07c34d291bca",
                  "amount": 3180.24,
                  "currency": "GBP",
                  "transaction_category": "CREDIT",
                  "description": "some company ltd",
                  "timestamp": "2020-03-06T00:00:00Z",
                  "transaction_type": "Credit",
                  "transaction_classification": [],
                  "meta": {
                    "provider_transaction_category": "CRED"
                  }
              },
              {
                  "transaction_id": "03c333979b729315545816aaa365c33f",
                  "amount": 3070,
                  "currency": "GBP",
                  "transaction_category": "CREDIT",
                  "description": "some company ltd",
                  "timestamp": "2020-02-06T00:00:00Z",
                  "transaction_type": "Credit",
                  "transaction_classification": [],
                  "meta": {
                    "provider_transaction_category": "CRED"
                  }
              }
         ]
     },
     {
         "income_type": "other_source",
         "name": "savings account profit",
         "average_monthly_income": 126.5,
         "average_amount": 126.5,
         "maximum_amount": 150,
         "minimum_amount": 103,
         "supporting_transactions": [
            {
                "transaction_id": "3484333edb2078e77cf2ed58f1dec11e",
                "amount": 150,
                "currency": "GBP",
                "transaction_category": "CREDIT",
                "description": "savings account profit",
                "timestamp": "2020-03-01T00:00:00Z",
                "transaction_type": "Credit",
                "transaction_classification": [],
                "meta": {
                  "provider_transaction_category": "CRED"
                }
            },
            {
                "transaction_id": "af4d5470cc7ad6a83a02335ab8053481",
                "amount": 103,
                "currency": "GBP",
                "transaction_category": "CREDIT",
                "description": "savings account profit",
                "timestamp": "2020-02-024T00:00:00Z", 
                "transaction_type": "Credit",
                "transaction_classification": [],
                "meta": {
                  "provider_transaction_category": "CRED"
                }
            }
         ]
     }
 ]
}

Returns income insights for the specified account_id.

Parameters

Field Type Description
from datetime OPTIONAL. Find income from transactions posted on or after from date. Default value is date as of the API request minus 3 months
to datetime OPTIONAL. Find income from transactions up to and including this date. Default value is date as of the API request

Response

Field Type Description
average_total_income_monthly number Estimate of account’s total monthly income
transaction_history_span_days number Number of days between first and last transaction retrieved within specified time range
sources array of sources Array of identified income sources

Income source schema

Field Type Description
income_type string Type of income. Values include “salary”, “wages” and “other_source”
name string Entity name of identified income source
average_monthly_income number Average income contribution by source
average_amount number Average value of an individual transaction amount in the identified income source
maximum_amount number Maximum value of an individual transaction amount in the identified income source
minimum_amount number Minimum value of an individual transaction amount in the identified income source
supporting_transactions array of supporting_transactions Array of all individual supporting transactions for identified income source

Supporting transaction schema

Field Type Description
transaction_id string Unique identifier of the transaction in a request. It may change between requests.
timestamp datetime Date the transaction was posted on the account
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
transaction_classification array Classification of the transaction (array can be empty if classification has not been successfully assigned)
merchant_name string OPTIONAL (if merchant has been identified). Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata

Retrieve regular expenditure

Request

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  https://insights.truelayer.com/v1/accounts/${account_id}/expenditure/regular?from=${from}&to=${to}

Response

{
  "transaction_history_span_days": 86,
  "expenditures": [
    {
      "name": "THAMES WATER",
      "frequency": "monthly",
      "classification_category": [
        "Bills and Utilities",
        "Utilities"
      ],
      "merchant_name": "THAMES WATER",
      "previous_payment_timestamp": "2020-04-01T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-05-01T00:00:00Z",
      "predicted_next_payment_amount": -40.15,
      "average_amount": -40.15,
      "minimum_amount": -40.77,
      "maximum_amount": -39.84,
      "supporting_transactions": [
       {
          "transaction_id": "b8db1fdf3638a5307bd4af2e2b43d45e",
          "description": "Thames Water",
          "amount": -40.77,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-04-01T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Utilities"],
          "merchant_name": "THAMES WATER",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "aff0e8ee9d5ae4c10e446c331d09d7c6",
          "description": "Thames Water",
          "amount": -39.84,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-02T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Utilities"],
          "merchant_name": "THAMES WATER",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "a0e78409ce5a155d9688f57c9e0f5aa1",
          "description": "Thames Water",
          "amount": -39.84,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-04T00:00:00Z", 
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Utilities"],
          "merchant_name": "THAMES WATER",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        }
      ]
    },
    {
      "name": "Octopus Energy Lim",
      "frequency": "monthly",
      "classification_category": [],
      "merchant_name": "Octopus Energy",
      "previous_payment_timestamp": "2020-04-01T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-05-01T00:00:00Z",
      "predicted_next_payment_amount": -53.36,
      "average_amount": -53.36,
      "minimum_amount": -53.36,
      "maximum_amount": -53.36,
      "supporting_transactions": [
        {
          "transaction_id": "1022425bf7cd247a9a704dc345e88ad2",
          "description": "Octopus Energy Lim",
          "amount": -53.36,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-04-01T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": [],
          "merchant_name": "Octopus Energy",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "36ce2bc0726f3ad17da0d7752beedbb5",
          "description": "Octopus Energy Lim",
          "amount": -53.36,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-02T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": [],
          "merchant_name": "Octopus Energy",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "4544ef2534a29c15bd85ef0f1633a053",
          "description": "Octopus Energy Lim",
          "amount": -53.36,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-03T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": [],
          "merchant_name": "Octopus Energy",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        }
      ]
    },
    {
      "name": "VIRGIN MEDIA",
      "frequency": "monthly",
      "classification_category": [
        "Bills and Utilities",
        "Internet"
      ],
      "merchant_name": "VIRGIN MEDIA",
      "previous_payment_timestamp": "2020-03-27T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-04-27T00:00:00Z",
      "predicted_next_payment_amount": -38.11,
      "average_amount": -38.11,
      "minimum_amount": -38.35,
      "maximum_amount": -38,
      "supporting_transactions": [
        {
          "transaction_id": "85e070858eddebc6488f6a4fee0bbcbc",
          "description": "Virgin Media",
          "amount": -38.35,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-27T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Internet"],
          "merchant_name": "VIRGIN MEDIA",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "26756a7ad5b7b72d6191afe416ddef48",
          "description": "Virgin Media",
          "amount": -38,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-27T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Internet"],
          "merchant_name": "VIRGIN MEDIA",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "d5bbb797ce7ac0e6bf5d4d83d07ed37f",
          "description": "Virgin Media",
          "amount": -38,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-01-27T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Bills and Utilities", "Internet"],
          "merchant_name": "VIRGIN MEDIA",
          "meta": {
            "provider_transaction_category": "DEB"
          }
        }
      ]
    },
    {
      "name": "NETFLIX",
      "frequency": "monthly",
      "classification_category": [
        "Entertainment",
        "Movies & DVDs"
      ],
      "merchant_name": "NETFLIX",
      "previous_payment_timestamp": "2020-03-20T00:00:00Z",
      "predicted_next_payment_timestamp": "2020-04-20T00:00:00Z",
      "predicted_next_payment_amount": -8.99,
      "average_amount": -8.99,
      "minimum_amount": -8.99,
      "maximum_amount": -8.99,
      "supporting_transactions": [
       {
          "transaction_id": "070ff6c1fc9ac17309466cd52e61bbcc",
          "description": "Netflix",
          "amount": -8.99,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-03-20T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Entertainment", "Movies & DVDs"],
          "merchant_name": "NETFLIX",
          "meta": {
            "bank_transaction_id": "9882ks-00js",
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "1efacba6b94e16ce3de0ec5986908ee2",
          "description": "NETFLIX",
          "amount": -8.99,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-02-20T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Entertainment", "Movies & DVDs"],
          "merchant_name": "netflix",
          "meta": {
            "bank_transaction_id": "9883ys-00js",
            "provider_transaction_category": "DEB"
          }
        },
        {
          "transaction_id": "e8796dbd81e1a6fe5b893cb83e50a7b4",
          "description": "Netflix",
          "amount": -8.99,
          "currency": "GBP",
          "transaction_category": "DEBIT",
          "timestamp": "2020-01-20T00:00:00Z",
          "transaction_type": "Debit",
          "transaction_classification": ["Entertainment", "Movies & DVDs"],
          "merchant_name": "NETFLIX",
          "meta": {
            "bank_transaction_id": "9892fs-00js",
            "provider_transaction_category": "DEB"
          }
        }
      ]
    }
      ]
    }

Returns expenditure insights for the specified account_id.

Parameters

Field Type Description
from datetime OPTIONAL. Find expenditure from transactions posted on or after from date. Default value is date as of the API request minus 3 months
to datetime OPTIONAL. Find expenditure from transactions up to and including this date. Default value is date as of the API request

Response

Field Type Description
transaction_history_span_days number Number of days between first and last transaction retrieved within specified time range
expenditures array of expenditure groups Array of identified recurring expenditure groups

Expenditure group schema

Field Type Description
name string Name of the expenditure group, based on transaction descriptions
frequency string Calculated frequency (periodicity) of transactions in group. Currently supports “monthly”, “weekly”, “annually”
classification_category array Classification category and sub-category in group
merchant_name string OPTIONAL (if merchant has been identified). Identified merchant name
previous_payment_timestamp datetime Timestamp of most recent payment in group
predicted_next_payment_timestamp datetime Predicted timestamp of next payment in group
predicted_next_payment_amount number Predicted amount of next payment in group
average_amount number Average value of an individual transaction amount in group
minimum_amount number Minimum value of an individual transaction amount in group
maximum_amount number Maximum value of an individual transaction amount in group
supporting_transactions array of supporting_transactions Array of all individual supporting transactions for identified expenditure group

Supporting transaction schema

Field Type Description
transaction_id string Unique identifier of the transaction in a request. It may change between requests.
timestamp datetime Date the transaction was posted on the account
description string Original description of the transaction as reported by the Provider
transaction_type string Type of the transaction
transaction_category string Category of the transaction
transaction_classification array Classification of the transaction (array can be empty if classification has not been successfully assigned)
merchant_name string OPTIONAL (if merchant has been identified). Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object A collection of additional Provider specific transaction metadata

End-user IP Address

EU banks limit the number of requests that can be made to their API if the request is not initiated by the end-user. These are documented as 429 errors here. In order to avoid this rate limit, you can include the end-user’s IP address in your requests to the Data API as follows.

Field Type Description
X-PSU-IP string The PSU’s IP address to be passed on to the bank in order to avoid rate limiting.

Data API errors

The following error codes can be returned with the associated HTTP status.

HTTP Status Description Error Code Retry How to handle
200 Success
400 The supplied parameters are not valid. validation_error Yes There’s a problem with the request. Read the error message which explains what’s wrong with the request specifically.
400 Invalid date range provided. invalid_date_range No Change the from and to parameters. Check here for bank-specific requirements: https://truelayer.zendesk.com/hc/en-us/articles/360003168153-How-far-back-can-I-pull-transactions-
400 The provider has been deprecated. deprecated_provider No The provider has been deprecated. It is no longer supported.
401 The credentials or token are no longer valid unauthorized No Refresh your access token. The access token may be invalid or expired. You can check for more details in the error description.
403 Access to a specific resource has been denied. access_denied No Ask the user to reconnect their account. This error is returned when the access to their account is no longer valid, either because it expired or because the user revoked it themselves.
403 The provided credentials encryption key is invalid. invalid_credentials_key
403 SCA exemption has expired. This resource is protected and should be accessed shortly after PSU Authentication. In order to access this resource, please have the PSU re-authenticate. sca_exceeded No The access to that specific endpoint has expired. For example, for some European banks you may only access the /info endpoint, or transanctions older than 90 days, during the 5 minutes after the user first grants access. Access to other data (balances, recent transactions) should still be working.
404 The requested account cannot be found. account_not_found No Check the accountId parameter used within your request. Confirm this matches an accountId returned from /accounts endpoint.
429 Provider rate limit exceeded. provider_too_many_requests Yes Include the X-PSU-IP header or retry later. Requests exceed the bank’s rate limit.
429 Maximum number of requests per user allowed by provider exceeded. provider_request_limit_exceeded Yes Include the X-PSU-IP header or retry later. The bank has a regulatory limit on how often the account can be accessed (for example, many European banks have a limit of 4 requests for a given user per endpoint per day, unless the user has initiated the request).
500 Internal server error. internal_server_error Yes Retry later.
501 Feature not supported by the provider. endpoint_not_supported No Check supported endpoints for each provider via our Help Desk FAQ.
503 The provider service is unavailable. provider_error Yes Retry later - the bank is currently undergoing maintenance.
503 The connector service is currently overloaded. connector_overload Yes Retry later - TrueLayer is currently overloaded.
503 The provider service is unavailable. temporarily_unavailable Yes Retry later - the bank is experiencing unexpected downtime.
504 The provider service timed out. provider_timeout Yes Retry later - the bank is experiencing issues.
504 The connector service timed out. connector_timeout Yes Retry later - TrueLayer is experiencing a transient issue.

Data API Changelog

Updates made to the Data API will be posted here with the release date.

May 21, 2020

August 1, 2019

June 20, 2019

June 19, 2019

June 18, 2019

May 24, 2019

May 21, 2019

March 29, 2019

March 5, 2019

Payments API v1

Payments API Overview

The TrueLayer Platform is integrated to UK and EU banks which offer Payment Initiation APIs, and provides a single public API which enables clients to request payment via all integrated banks.

Note that for access to the production API, you must have:

To get support for the Payments API:

Payments API: Contents

In this section of the documentation you will find:

Payments API Quick Start

Use our Payments API to make a single immediate payment in just a few quick steps - here’s how it works:

  1. After signing up to our Console, make a note of the client_id and the client_secret. These credentials allow you to obtain an access_token.
  2. Using that token, set up a single immediate payment, specifying recipient and amount.
  3. We’ll provide you with an authorisation link, which provides a simple interface for you to select the bank to make the payment from and complete the payment.

It’s that simple! To see it in action, use our Sandbox Postman collection to start making payments in just a few minutes, following the steps below.

If you want to use Postman with your production account, please download this Postman collection instead (this has production URIs instead of sandbox URIs).

Set Up

  1. Sign up to the TrueLayer Console to get your client_id and client_secret.
  2. Install Postman and download our Postman collection. It contains sample requests so that you can start making payments, and generate code snippets in various languages of your choice.

Step 1 - Obtain an Access Token

  1. Open the first step in the Postman collection and click the Body tab.
  2. Replace CLIENT_ID and CLIENT_SECRET with your own values obtained in Step 1.
  3. Click the Send button to forward the request to our server.
  4. In response you’ll receive an access_token, which you can copy into your clipboard.

Step 2 - Create a Single Immediate Payment

  1. Now open the second step in the postman collection and click the Authorization tab.
  2. Replace the token value ACCESS-TOKEN-HERE with the value obtained in the previous step.
  3. Now click on Body and replace the values with the actual payment details. Make sure redirect_uri is one of the URIs that has been whitelisted in the TrueLayer Console.
  4. Click the blue Send button to forward the request to our server.
  5. Open the auth_uri in a browser to complete the payment.

Step 3 - Get Payment Status

  1. Now open the third step in the Postman collection and click the Authorization tab.
  2. Replace the token value ACCESS-TOKEN-HERE with the value obtained in Step 1.
  3. Replace PAYMENT-ID-HERE in the URI with the value of simp_id obtained in Step 2.
  4. Click the Send button to forward the request to our server. We will return the status for this payment.

Congratulations, you made your first payment!

What’s next

Payments API Guide

Note that all API endpoint URIs in this section are for the production environment. If you wish to follow this guide using the sandbox environment, please ensure that you change the endpoint domain from truelayer.com to truelayer-sandbox.com. You can also find all the sandbox endpoints in our Sandbox Postman collection.

Integration Checklist

Below are two checklists, one is for using the TrueLayer UI to initiate payments and the other is for whitelabeling our service inside your own application. For the best user experience and the highest conversion rate, we recommend you integrate into your own UI.

For the simplest guide to getting integrated as fast as possible, see a blog post we have published here.

Using your own UI

  1. Use our providers endpoint to build a ‘Provider Selection screen’ for the user to choose their bank. (all assets are supplied)
  2. Obtain a client credentials grant from the authentication server
  3. Create a new payment (either a Single Immediate Payment or a Standing Order), specifying the bank the user wants to use
  4. Redirect the user to the URI specified in the API response
  5. Handle the redirect back from the bank on the redirect_uri you set in the console.
  6. Poll our Get Info endpoint until you see a final status.

Using our UI

  1. Obtain a client credentials grant from the authentication server
  2. Create a new payment (either a Single Immediate Payment or a Standing Order)
  3. Redirect the user to the URI specified in the API response
  4. Handle the redirect back from the bank on the redirect_uri you set in the console.
  5. Poll our Get Info endpoint until you see a final status.

Getting Setup

Using the Sandbox

To use the sandbox, all you have to do is replace truelayer.com with truelayer-sandbox.com in your requests. Remember to use the right credentials for the sandbox.

In the sandbox, you will have access to banks that have a sandbox environment. With these banks you can send a fake payment that will behave like a real one.

Finding your Client ID and Secret

To authenticate to our API you will need to use your Client ID and Secret for the environment you are using (Live or Sandbox). Both can be found in the console.

The client ID can be found in the settings page. If you don’t have your client secret, you can generate a new one here.

To upgrade your account to the live environment, you will need to give our sales team your Client ID. In the sandbox area of the console follow these steps:

  1. Navigate to the payments tab
  2. Click 'Go to live env’
  3. Navigate to the settings tab
  4. Copy the client ID field

Adding a redirect_uri

Once the user has authenticated with their bank, we will redirect them back to your application. Add this URI to the console so that we can validate it when you create a payment.

Add the redirect to the settings page, you can add as many as you like.

Common concepts to familiarise yourself with

Concept Description
Provider selection This refers to a selection screen used by your users to select their bank. You can build your own with the providers endpoint available for each payment type.
Redirect URI The redirect uri that you send us will be used to the send the user home after authorising their payment with the bank. This URI can’t have any paramaters associated with it. We will add a query parameter with the payment ID.
Beneficiary This referes to the bank account recieving the funds. This is most commonly you.
Remitter This refers to the bank account making the payment. This is most commonly your user.

How to present this payment method to your users

The only requirement for your user interface is that you should not embed the payment flow as a frame within a larger frameset. Most banks will not accept their flow running this way and will block the user from continuing. However, running as a webview should not be a problem if you wish to initiate the payment from within a mobile application.

When presenting the end user with the option to use this payment method, we recommend you label the option as “Pay with Bank” rather than mentioning TrueLayer or Open Banking. This increases user trust and confidence in using the service.

Authentication

Request

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=payments \
    https://auth.truelayer.com/connect/token

Response

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Use our authentication server to obtain a client credentials grant. You will need to use this on your requests to the Payments API.

Unlike our Data API, this grant doesn’t represent a user, but a client creating the payment.

Single Immediate Payment

This section describes how to setup, execute, and monitor progress of a Single Immediate Payment.

A single immediate payment is a one time payment, executed immediately, that requires the user to authenticate with their bank.

Below are instructions for how to:

  1. Build a provider selection screen for your users to select their bank
  2. Create a payment
  3. Redirect a user to authenticate
  4. Handle the user returning to your application
  5. Poll for payment status

Providers Endpoint

Request

https://pay-api.truelayer.com/providers?capability=SingleImmediatePayment

Response

{
  "results":[
    {
      "id":"ob-sandbox-natwest",
      "logo":"example.com",
      "icon":"example.com",
      "displayable_name":"Natwest Sandbox",
      "main_bg_color":"#eee",
      "supports_app_to_app":false,
      "divisions":["retail"]
    }
  ]
}

The providers endpoint serves two purposes:

  1. Tells you which banks are active, if a bank isn’t listed then we have deactivated it temporarily until it’s service is returned.
  2. Gives you the assets to build out a selection screen e.g. Logos and Icons.

When querying the endpoint, specify capability in the query string as SingleImmediatePayment.

Each bank available will have the following fields:

Field Type Description
id string This is the provider ID that you will send us in the create payment request.
logo string This is the address of the logo asset in SVG form.
icon string This is the address of the icon asset in SVG form.
displayable_name string This is a readable name for the provider.
main_bg_color string This is a hexacode color that matches the background of the logo.
supports_app_to_app bool This indicates whether the user will be redirected to the mobile banking app if using their mobile phone. In cases where this is false, the user authenticate in their browser.
divisions string array This array includes all divisions that are available on this provider, e.g. retail and business would indicate you can use this single provider to access both retail and business accounts.

We recommend you query this endpoint every single time you make a payment as we will remove banks that are not currently available.

Creating the payment

Request

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{
  "amount": 120000,
  "currency": "GBP",
  "remitter_provider_id": "ob-bank",
  "remitter_name": "Mike Smith",
  "remitter_sort_code": "987654",
  "remitter_account_number": "98765432",
  "remitter_reference": "FS-1000001",
  "beneficiary_name": "Financial Services Ltd",
  "beneficiary_sort_code": "234567",
  "beneficiary_account_number": "23456789"
  "beneficiary_reference": "FinServ-1a2b3c4d",
  "redirect_uri": "https://client.app.com/payment_redirect"
}' \
https://pay-api.truelayer.com/single-immediate-payments

Response

{
  "results": [
    {
      "simp_id": "44708581-1967-4120-8f6a-1e532f1bf52a",
      "auth_uri": "https://example.com",
      "created_at": "2018-10-01T17:00:00.0000000+00:00",
      "amount": 120000,
      "currency": "GBP",
      "remitter_provider_id": "ob-bank",
      "remitter_name": "Mike Smith",
      "remitter_sort_code": "987654",
      "remitter_account_number": "98765432",
      "remitter_reference": "FS-1000001",
      "beneficiary_name": "Financial Services Ltd",
      "beneficiary_sort_code": "234567",
      "beneficiary_account_number": "23456789",
      "beneficiary_reference": "FinServ-1a2b3c4d",
      "redirect_uri": "https://client.app.com/payment_redirect",
      "status": "new"
    }
  ]
}

This method includes the following fields:

Field Type Mandatory/Optional Description
amount int Mandatory The amount of money you are requesting in pennies.
currency string Mandatory The currency code of the payment.
beneficiary_reference string Mandatory The reference that will appear on your bank statement. Note: this can only be 18 characters or less.
beneficiary_sort_code string Mandatory The sort code of the receiving account (your account).
beneficiary_account_number string Mandatory The account number of the receiving account (your account).
remitter_reference string Mandatory The reference that will appear on the sender’s bank statement. Note: this can only be 18 characters or less.
beneficiary_name string Mandatory The name on the receiving account.
redirect_uri string Mandatory The URL we will redirect the user to after authorising the payment.
remitter_provider_id string Optional The ID from the providers endpoint of the bank your user has chosen, if this isn’t specified the user will be sent to TrueLayer to choose their bank.
remitter_account_number string Optional The account number of the payer, specify this if you want to lock the account from which the payment is being made. This may be an AML requirement.
remitter_sort_code string Optional The sort code of the payer, specify this if you want to lock the account from which the payment is being made. This may be an AML requirement.
direct_bank_link bool Optional If set to true, you will be returned a URI directly from the bank. !WARNING! If using this, you will skip all TrueLayer optimisation and conversion may be lower on desktop. You must specify remitter_provider_id for this request to succeed.
webhook_uri string Optional An address to send payment webhooks to with the status of your payment. This has to be https.

The request will return a simp_id that you should store as, after authorisation, the user will be redirected to your redirect_uri with this appended as payment_id.

Use the auth_uri to redirect your user to authorise the payment.

Redirecting your user to the bank

After creating the payment, you need to redirect the user to the auth_uri.

If you did not specify the remitter_provider_id your user will be redirected to the TrueLayer Provider Selection screen and from there on to their bank. Bank selection dialog

Handling a returning user

Once the payment is authorised, the user will return to your redirect_uri. The URL will include a payment_id query parameter containing the simp_id from the payment creation response.

https://client.app.com/payment_redirect?payment_id=a55f2e12-55ef-410c-9341-628033a62dc3

Managing payment status with webhooks

Status Changed Event

X-TL-Signature:  "a JWS token"

X-TL-Webhook-Timestamp: 2020-05-18T10:17:52Z

{
  "event_type": "single_immediate_payment_status_changed",
  "event_body": {
    "payment_id": "77a75df0-af60-4785-8e91-809ac77ca8e3",
    "status": "executed"
  }
}

When the status of a payment changes, we send a single_immediate_payment_status_changed event to the uri that you specified when creating the payment.

In the header you will see the following fields:

Field Type Description
X-TL-Signature JWS Token a signature in the form of a JWS token that you can use to validate that the request came from us. Instructions for using this are coming soon.
X-TL-Webhook-Timestamp timestamp time that the webhook was sent to you. This will be in the following format 2020-05-18T10:17:47Z

In the body you will see the following fields:

Field Type Description
event_type string describing which event is detailed. In this case the event will be single_immediate_payment_status_changed
event_body object containing both the payment_id as a string and the status as a string

To see all the available payment statuses, read the section below on polling for status where we list what states your payment can exist in.

To see webhooks in action, send a fake penny on https://penny.truelayer-sandbox.com/ and see the webhooks registering live.

Polling for payment status

Request

curl -H "Authorization: Bearer ${access_token}" \
https://pay-api.truelayer.com/single-immediate-payments/a55f2e12-55ef-410c-9341-628033a62dc3

Response

{
  "results": [
    {
      "simp_id": "c45d38a6-2384-49aa-98ab-60134a50a5d7",
      "created_at": "2018-10-01T16:00:00.0000000+00:00",
      "amount": 350,
      "currency": "GBP",
      "beneficiary_reference": "ecommerce-12345",
      "beneficiary_name": "Ecommerce Shop",
      "beneficiary_sort_code": "102030",
      "beneficiary_account_number": "88881234",
      "remitter_reference": "ECOM-12345-ABCD",
      "redirect_uri": "http://www.ecommerce.com/redirect",
      "remitter_provider_id": "ob-lloyds",
      "status": "executed"
    }
  ]
}

The application can poll the payment resource to see if the status has been modified. This allows the application to know if the payment was successful or not.

Note that if the remitter was specified, remitter details will also be included in the response.

The payment resource may exist in different states according to the progress of the transaction:

The submitted and executed states are very close; in fact a bank may respond to the payment submission indicating the payment has already been executed. However, it is also possible for a payment to be queued within the bank for a short period of time; in that case, the payment status will initially be submitted, and then may be updated to executed after polling for a status check.

Note that after a payment has been executed, it may take some time for it to be settled, although for transactions executed via Faster Payments, this normally happens very quickly.

State transition diagram

Request

``` shell
curl -H "Authorization: Bearer ${access_token}" \
https://pay-api.truelayer.com/single-immediate-payments/a55f2e12-55ef-410c-9341-628033a62dc3/statuses

>Response

``` json
{
    "results": [
        {
            "status": "New",
            "date": "2020-04-08T21:53:35.364038"
        },
        {
            "status": "Authorised",
            "date": "2020-04-08T21:54:17.690429"
        },
        {
            "status": "Submitted",
            "date": "2020-04-08T21:54:18.546706"
        },
        {
            "status": "Executed",
            "date": "2020-04-08T21:54:28.063325"
        },
        {
            "status": "Executed",
            "date": "2020-04-08T21:54:28.2761"
        }
    ],
    "status": "queued"
}

To see all known states of your payment and trace your payment with the timestamps, add /statuses to the end of the request.

Standing Order

This section describes how to setup, execute, and monitor progress of a Standing Order.

Below are instructions for how to:

  1. Build a provider selection screen for your users to select their bank
  2. Create a standing order
  3. Redirect a user to authenticate
  4. Handle the user returning to your application
  5. Poll for payment status

Providers Endpoint

Request

curl https://pay-api.truelayer.com/providers?capability=StandingOrder

Response

{
  "results":[
    {
      "id":"ob-sandbox-natwest",
      "logo":"example.com",
      "icon":"example.com",
      "displayable_name":"Natwest Sandbox",
      "main_bg_color":"#eee",
      "supports_app_to_app":false,
      "divisions":["retail"]
    }
  ]
}

The providers endpoint serves two purposes:

  1. Tells you which banks are active, if a bank isn’t listed then we have deactivated it temporarily until it’s service is returned.
  2. Gives you the assets to build out a selection screen e.g. Logos and Icons.

When querying the endpoint, specify capability in the query string as StandingOrder.

Each bank available will have the following fields:

Field Type Description
id string This is the provider ID that you will send us in the create payment request.
logo string This is the address of the logo asset in SVG form.
icon string This is the address of the icon asset in SVG form.
displayable_name string This is a readable name for the provider.
main_bg_color string This is a hexacode color that matches the background of the logo.
supports_app_to_app bool This indicates whether the user will be redirected to the mobile banking app if using their mobile phone. In cases where this is false, the user authenticate in their browser.
divisions string array This array includes all divisions that are available on this provider, e.g. retail and business would indicate you can use this single provider to access both retail and business accounts.

We recommend you query this endpoint every single time you make a payment as we will remove banks that are not currently available.

Setting the frequency

Standing Orders can recur on a monthly or weekly basis. The following two variables are used to set this:

Field Type Range Description
day_of_month int 1 to 31 The day of the month on which the standing order recurs.
day_of_week int 1 to 5 The day of the week on which the standing order recurs.

These variables cannot be used together. In the case that the standing order recurs on a day not present in the current month, the bank will default to executing the standing order on the last working day of the month. Standing orders only execute on working days.

Creating the Standing Order

Request

Curl -X POST \
    -H “Authorization: Bearer ${access_token}\
    -H “Content-Type: application/json” \
    --data ‘{
“recurring_amount”: 1,
“first_payment_date”: “2020-02-09”,
“currency”: “GBP”
“day_of_month”: 24, [can be day_of_week instead]
“beneficiary_sort_code”: “123456”,
“beneficiary_account_number”: “12345678”,
“beneficiary_name”: “Example”,
“beneficiary_reference”: “Example”,
“redirect_uri”: “example.com/callback”,
“remitter_reference”: “Example”,
“Remitter_name”: “Example”,
“Remitter_sort_code”: “123456”,
“Remitter_account_number”: “12345678”,
“Remitter_provider_id”: “ob-barclays”
}\
https://pay-api.truelayer.com/standing-orders

Response

{
    "results": [
        {
            "resource_id": "example",
            "auth_uri": "https://example.com",
            "created_at": "2020-01-29",
            "amount": 1,
            "currency": "GBP",
            "beneficiary_reference": "Example",
            "beneficiary_name": "Example",
            "beneficiary_sort_code": "123456",
            "beneficiary_account_number": "123456",
            "remitter_name": "Example",
            "remitter_sort_code": "123456",
            "remitter_account_number": "12345678",
            "remitter_reference": "Example",
            "redirect_uri": "https://example.com/callback",
            "remitter_provider_id": "ob-barclays",
            "status": "new"
        }
    ]
}

This method includes the following fields:

Field Type Mandatory/Optional Description
recurring_amount int Mandatory The amount in pennies to be debited from the account on each recurring date.
first_payment_date string (YYYY-MM-DD) Optional The date to start the standing order. If not specified, this will default to today.
currency string Mandatory Currency to debit the account in. The only valid string is currently 'GBP’.
beneficiary_reference string Mandatory The reference that will appear on your bank statement. Note: this can only be 18 characters or less.
beneficiary_sort_code string Mandatory The sort code of the receiving account (your account).
beneficicary_account_number string Mandatory The account number of the receiving account (your account).
remitter_reference string Mandatory The reference that will appear on the sender’s bank statement. Note: this can only be 18 characters or less.
day_of_month int Mandatory (when day_of_weeek not specified) The day of the month on which the standing order recurs.
day_of_week int Mandatory (when day_of_month not specified) The day of the week on which the standing order recurs.
redirect_uri string Mandatory The URL we will redirect the user to after authorising the payment.
remitter_provider_id string Optional The ID from the providers endpoint of the bank your user has chosen, if this isn’t specified the user will be sent to TrueLayer to choose their bank.
remitter_name string Optional The name of the payer.
remitter_sort_code string Optional The sort code of the payer. Send this if you want to lock which account they can use.
remitter_account_number string Optional The account number of the payer. Send this if you want to lock with account they can use.
direct_bank_link bool Optional If set to true, you will be returned a URI directly from the bank. !WARNING! If using this, you will skip all TrueLayer optimisation and conversion may be lower on desktop. You must specify remitter_provider_id for this request to succeed.

Redirecting your user to the bank

After creating the standing order, you need to redirect the user to the auth_uri.

If you did not specify the remitter_provider_id your user will be redirected to the TrueLayer Provider Selection screen and from there on to their bank. Bank selection dialog

Handling a returning user

Once the payment is authorised, the user will return to your redirect_uri. The URL will include a standing_order_id query parameter containing the resource_id from the payment creation response.

https://client.app.com/payment_redirect?standing_order_id=a55f2e12-55ef-410c-9341-628033a62dc3

Polling for payment status

Request

curl -H "Authorization: Bearer ${access_token}" \
https://pay-api.truelayer.com/standing-orders/a55f2e12-55ef-410c-9341-628033a62dc3

Response

{
  "results": [
    {
      "resource_id": "c45d38a6-2384-49aa-98ab-60134a50a5d7",
      "created_at": "2018-10-01T16:00:00.0000000+00:00",
      "amount": 350,
      "currency": "GBP",
      "beneficiary_reference": "example",
      "beneficiary_name": "example",
      "beneficiary_sort_code": "123456",
      "beneficiary_account_number": "12345678",
      "remitter_reference": "example",
      "redirect_uri": "example.com",
      "remitter_provider_id": "ob-lloyds",
      "status": "initiated",
      "day_of_month": 1,
      "day_of_week": 0
    }
  ]
}

The application can poll the payment resource to see if the status has been modified. This allows the application to know if the payment was successful or not. Note that in a future release, webhook notifications will be available.

Note that if the remitter was specified, remitter details will also be included in the response.

Standing orders can have three possible statuses: - New - The Standing Order intitiation request has been created, but not actioned yet. - Authorised - The user has authenticated in their bank app or website. - InitiationFailed - The Standing Order initiation failed. This is a terminal state. - InitiationCompleted - The Standing Order was successfully setup. This is a terminal state.

Request

``` shell
curl -H "Authorization: Bearer ${access_token}" \
https://pay-api.truelayer.com/standing-orders/a55f2e12-55ef-410c-9341-628033a62dc3/statuses

>Response

``` json
{
    "results": [
        {
            "status": "New",
            "date": "2020-04-08T21:53:35.364038"
        },
        {
            "status": "Authorised",
            "date": "2020-04-08T21:54:17.690429"
        },
        {
            "status": "InitiationCompleted",
            "date": "2020-04-08T21:54:28.063325"
        }
    ],
    "status": "queued"
}

To see all known states of your payment and trace your payment with the timestamps, add /statuses to the end of the request.

Technical Notes

Initiate Payment

This diagram illustrates the message flow when a payment is created. * Client gets access token * Client requests creation of payment resource * Client receives representation of payment resource, including a URI to redirect the user to

Initiate Payment

End-User Authorises Payment

This diagram illustrates the message flow when a user authorises a payment. * User is redirected to bank selection dialog * User selects bank * User is redirected to bank payment consent flow * User authorises payment * User is redirected back to application

End-User Authorises Payment

Polling Payment Status

This diagram shows messages used to determine the payment status after a payment has been authorised. * Client requests payment resource * Client receives payment resource representation and checks status attribute

Polling Payment Status

Payment Cancelled

This diagram shows the user navigation and messaging when a user cancels the payment during the bank consent flow. * User is redirected to bank selection dialog * User selects bank * User is redirected to bank payment consent flow * User cancels payment * User is redirected back to application * Client requests payment resource * Client receives payment resource representation and checks status attribute

Cancelled Payment

Payment Rejected

This diagram shows the user navigation and messaging when the bank rejects a payment after user authorisation. * User is redirected to bank selection dialog * User selects bank * User is redirected to bank payment consent flow * User authorises payment * Bank rejects payment * Client requests payment resource * Bank responds with rejected payment status * Client receives payment resource representation and checks status attribute

Rejected Payment

Testing Guidelines

The following guidelines aim to provide practical guidance while testing the integration.

Payments Sandbox

Before testing with live accounts, we recommend that you test your integration with the sandbox. The Payments Quick Start provides instructions on how to access the sandbox APIs.

When you transition to live testing in the production environment:

  1. Make sure you change all URIs to end with truelayer.com instead of truelayer-sandbox.com
  2. Change from using your sandbox client_id_ and client_secret to your production client_id and client_secret. You can find your production client_id here: https://console.truelayer.com/settings/Application (you should have saved your production client_secret when you last reset it, or when you created your production account)
  3. Have a live bank account to hand which you own to make payments from, as well as one to make payments into. The payer (or remitter) bank account must be from one of the supported providers listed here

Bank Account Limits

Each bank has its own limits on how much money can be transferred using online banking, which also apply to their open banking payment APIs.

Bank Details
Lloyds https://www.lloydsbank.com/online-banking/benefits-online-banking/view-pay-your-bills.asp#tab-row-5
Halifax https://www.halifax.co.uk/bankaccounts/help-guidance/online-banking-help/fasterpayments/
(click tab “Payment limits and timeframes”)
Bank of Scotland https://www.bankofscotland.co.uk/helpcentre/internet-banking/faster-payments/
(click tab FAQs)
Royal Bank of Scotland https://www.supportcentre-rbs.co.uk/Searchable/997053272/What-are-the-payment-limits.htm
NatWest https://supportcentre.natwest.com/Searchable/913208362/What-are-the-payment-limits.htm
Ulster https://supportcentre.ulsterbank.co.uk/Searchable/997054072/What-are-the-payment-limits.htm
Barclays https://www.barclays.co.uk/current-accounts/online-payment-limits/
HSBC From https://www.hsbc.co.uk/1/2/linklaunch/contactandsupport : “You can make payments of up to £25,000, per day via Online Banking if the funds are available, for larger amounts, you would need to visit an HSBC Branch with Identification and there may be a charge”
Santander https://www.santandercb.co.uk/contact-support/connect-helpcentre/making-payments/standard-domestic-payments-faster-payments
Nationwide https://www.nationwide.co.uk/support/support-articles/important-information/faster-payments#xtab:payment-limits
Danske Bank https://danskebank.co.uk/SiteCollectionDocuments/personal/payment-table-personal.pdf (see table on page 4 referencing Open Banking payment limits)
Post Office Bank (Bank of Ireland) https://www.postoffice.co.uk/current-account-faqs (see item “How much money can I send?”
AIB (Allied Irish Bank) https://aibgb.co.uk/ways-to-bank/online-banking/transaction-limit-information
First Trust Bank https://firsttrustbank.co.uk/ways-to-bank/transaction-limit-information
Starling https://www.starlingbank.com/paymentservices/
Monzo http://fasterpayments.org.uk/monzo
Revolut https://www.revolut.com/help/exploring-revolut/sending-money/sending-money-to-a-bank-account/what-are-the-transfer-limits/
TSB https://www.tsb.co.uk/business/payment-services/faster-payments/
Tesco https://yourcommunity.tescobank.com/t5/Help-Support/Faster-payments-and-daily-withdrawal-limits/td-p/11580

Velocity Limits

All banks have controls in place to protect their end users from fraudulent withdrawals. One type of control is a velocity limit, which allows only a certain number of payments, or a maximum aggregate payment amount, per time period, e.g. one hour, one day, etc.

Banks will not publish these limits, as the information could be taken advantage of by fraudsters. Therefore, when testing:

Payments API Changelog

Updates made to the Payments API will be posted here with the release date.

You can also view a list of known issues.

May 25, 2020

Webhooks added to single immediate payment

February 16, 2020

Standing orders documentation added

December 2, 2019

Addition of direct bank link parameter to create payment request

May 8, 2019

Sandbox environment released

January 29, 2019

Initial beta release:

Status API v1

Status API Overview

The Status API exposes the availability and error rates of the TrueLayer Data API in a JSON format. You can check this in case you are seeing failures to authenticate, which may be caused by lack of availability for the bank system.

You can see the Status API in action in the TrueLayer Status page.

Status Page

For updates on availability of our services you can subscribe to our TrueLayer Status Twitter feed.

Retrieve Data API status

Request

curl "https://status-api.truelayer.com/api/v1/data/status?\
from=2019-06-20T12:00:00&to=2019-06-20T13:00:00&providers=barclays,oauth-monzo\
&endpoints=accounts"

Response

{
  "status": "ok",
  "results": [
    {
      "timestamp": "2019-06-20T12:00:00.0000000",
      "providers": [
        {
          "provider_id": "barclays",
          "endpoints": [
            {
              "endpoint": "accounts",
              "availability": 93.68421052631578,
              "provider_error": 3.1578947368421053,
              "truelayer_error": 3.1578947368421053,
              "latency_percentiles": {
                "50": 15,
                "75": 74,
                "90": 78.2,
                "95": 140,
                "99": 1401.5,
              }
            }
          ],
          "availability": 93.68421052631578,
          "provider_error": 3.1578947368421053,
          "truelayer_error": 3.1578947368421053
        },
        {
          "provider_id": "oauth-monzo",
          "endpoints": [
            {
              "endpoint": "accounts",
              "availability": 100,
              "provider_error": 0,
              "truelayer_error": 0,
              "latency_percentiles": {
                "50": 17,
                "75": 74.3,
                "90": 73.2,
                "95": 240,
                "99": 1401.5,
              }
            }
          ],
          "availability": 100,
          "provider_error": 0,
          "truelayer_error": 0
        }
      ],
      "availability": 94.39252336448598,
      "provider_error": 2.803738317757009,
      "truelayer_error": 2.803738317757009
    }
  ]
}    

Retrieves Data API status, grouped by hour, provider and endpoint.

Parameters

Below is a list of optional query string parameters to use when calling the status-api.

Name Example Description
from from=2019-01-07T10:00:00 A timestamp that specifies the date and time data should be fetched from. This defaults to 24 hours. Results are rounded down to the nearest hour.
to to=2019-01-07T14:00:00 A timestamp that specifies the date and time data should be fetched until. This defaults the current time. Results are rounded down to the nearest hour.
providers providers=hsbc,oauth-monzo,ob-barclays A comma-separated list of providers, only data related to the supplied providers will be returned
endpoints endpoints=accounts,info A comma-separated list of endpoints, only data related to the supplied endpoints will be returned

Response

Name Description
results A JSON array containing data bucket objects
provider_id A string containing the provider id
timestamp The start of a one-hour time bucket
endpoints A comma-separated list of endpoints, only data related to the supplied endpoints will be returned
latency_percentiles A dictionary with percentiles as keys and latencies as values (in milliseconds). For example, a latency of 128 milliseconds on the 50th percentiles means that half of the requests directed to that endpoint completed in 128 milliseconds or less.
availability The percentage of successful requests for a provider’s endpoint represented as a float value between 0-100
provider_error The percentage of unsuccessful requests (that we know are on the provider side) for a provider’s endpoint represented as a float value between 0-100
truelayer_error The percentage of unsuccessful requests (due to TrueLayer) for a provider’s endpoint represented as a float value between 0-100

Check the providers and endpoints supported here.

Status API Changelog

Updates made to the Status API will be posted here with the release date.

January 5, 2019

Initial release: