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 the following methods to access APIs from providers:

  1. Open Banking/PSD2: We use Open Banking APIs for all available banks. We also use public proprietary APIs when available e.g. Monzo/Starling. The authentication is managed by the bank.

  2. Credential Sharing: TrueLayer uses proprietary technology in order to access private bank APIs when the public API is not available. The credentials are encrypted at rest and we don’t keep the encryption keys. Even if our Credentials Store is breached, the privacy of credentials will not be compromised. You can read more here.

    Please note that we are deprecating the Credential Sharing access method.

Access method Data API Payments API
Open Banking/PSD2 Y Y
Credential Sharing Y N

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
200 Success
400 The request is missing a required parameter invalid_request
400 The client is not authorized to request an authorization token unauthorized_client
400 Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method) invalid_client
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
400 The requested scope is invalid, unknown, or malformed invalid_scope
400 The server encountered an unexpected condition that prevented it from fulfilling the request server_error
400 The authorization server is currently unable to handle the request due to a temporary overloading or maintenance temporarily_unavailable
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
400 The authorization grant type is not supported by the authorization server unsupported_grant_type

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.

Currently, the sandbox environment provides the console to manage your account, and the Payments API. We will add support for the Data API in a future release.

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

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, the production environment has no access to the sandbox 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

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

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 - watch this video walkthrough to see how you can start accessing data with our Postman collection in just 2 minutes. Test it yourself by following these steps:

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 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 Authentication Link to authenticate users via the Auth Link Builder in our Console. This Authentication 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. Make sure enable_mock is enabled so that you can use our Mock Bank user credentials for testing.
  4. Next, click “Test” to open the generated link and connect a 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.

    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 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 two access methods for authentication: Access Methods

OpenBanking

OpenBanking Sequence Diagram

Credential Sharing

Credential Sharing 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}\
  &nonce=${nonce}\
  &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. An arbitrary nonce is also required and an optional state argument can be included.

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 Enterprise plan, you can also customise parts of the Auth Dialog including colors, some copy elements, setting a cancelation_uri or a link to your FAQs.

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 Succeded 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

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 Credential sharing: 1 hour
Open Banking: provider-specific
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}\
  &nonce=${nonce}\
  &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.

Parameters

Parameter Description
client_id Your client unique identifier
redirect_uri Must exactly match one of the registered redirect_uri for your Client
nonce A nonce is a random string, uniquely generated by the Client to allow the server to verify that a request has never been made before and helps prevent replay attacks.
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"
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.
enable_mock OPTIONAL. if set to "true“ the authentication dialog will show a fictitious bank named "Mock" for testing. See Mock Users.
enable_open_banking_providers OPTIONAL. if set to "true” the authentication dialog will show all available Open Banking Providers.
enable_credentials_sharing_providers OPTIONAL. if set to "true“ the authentication dialog will show all available Credential Sharing Providers. Please note that we are deprecating Credential Sharing providers.
enable_oauth_providers OPTIONAL. if set to "true” the authentication dialog will show all available oAuth Providers.
disable_providers OPTIONAL. Space-separated list of provider ids to be hidden in the authentication dialog

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
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} \
    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.

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. In the case of Credential Sharing, it will also purge the encrypted credentials.

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"
        ]
    }

This endpoint returns the list of supported providers:

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

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 Consent status update date OB
consent_created_at string Consent creation date OB
consent_expires_at string 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.

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 Date of birth of the End user
addresses[...].address string Full address of the End user
addresses[...].city string City
addresses[...].state string State
addresses[...].zip string Post code
addresses[...].country string ISO-3166-1 alpha-3 code of the country
emails[...] Array of strings Email addresses
phones[...] Array of strings Phone numbers

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 ISO 13616-1:2007 international bank number
account_number.number string Bank account number
account_number.sort_code string 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

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"
      }
    }
  ]
}

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[j]
account_number.iban string ISO 13616-1:2007 international bank number
account_number.number string Bank account number
account_number.sort_code string United Kingdom SORT code
account_number.swift_bic string ISO 9362:2009 Business Identifier Codes[k]
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

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 Available balance, including pre-arranged overdraft limit
currency string ISO 4217 alpha-3 currency code
current number Current balance
overdraft number Pre-arranged overdraft limit. Available for all “TRANSACTION” and “BUSINESS_TRANSACTION” account types. See Account Types
update_timestamp datetime 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
merchant_name string Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object OPTIONAL. 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
merchant_name string Name of the merchant
amount number Amount of the transaction
currency string ISO 4217 alpha-3 currency code
meta object OPTIONAL. 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.

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 This can either be Active or Inactive
previous_payment_timestamp datetime Date of the latest payment
previous_payment_amount string Amount of the latest payment
currency string ISO 4217 alpha-3 currency code
meta object OPTIONAL. 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.

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 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 OPTIONAL. A collection of additional Provider specific transaction metadata
next_payment_date datetime The date on which the next payment for the standing order schedule will be made.
next_payment_amount string Amount of the next payment for the standing order
first_payment_date datetime The date on which the first payment for the standing order schedule will be or was made.
first_payment_amount string Amount of the first payment for the standing order
final_payment_date datetime The date on which the next payment for a Standing Order schedule will be made.
final_payment_amount string Amount of the last payment for the standing order
reference string Reference of the standing order set by the user
previous_payment_timestamp datetime Date of the latest payment
previous_payment_amount string Amount of the latest payment

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"
    }
  ]
}

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 If available, the name on the card
valid_from string If available, the valid from date
valid_to string If available, the valid to date
update_timestamp datetime Last update time of the card information

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 Available balance
currency string ISO 4217 alpha-3 currency code
current number Current balance
credit_limit number 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
timestamp datetime Date the transaction was posted on the card
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
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
timestamp datetime Date the transaction was posted on the card
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
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

Data API errors

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

HTTP Status Description Error Code
200 Success
400 The supplied parameters are not valid. validation_error
400 Invalid date range provided. invalid_date_range
400 The provider has been deprecated. deprecated_provider
401 The credentials entered are incorrect. wrong_credentials
403 The account is temporarily locked by the provider. account_temporarily_locked
403 The account is permanently locked by the provider. account_permanently_locked
403 Access to the account has been revoked or expired. access_denied
403 The provided credentials encryption key is invalid. invalid_credentials_key
403 Multi-Factor Authentication required. mfa_required
403 User input is required by the provider. user_input_required
404 The requested account cannot be found. account_not_found
409 This request is already running. Please try again later. request_conflict
410 The selected provider recognises the user within a different context. wrong_bank
500 Internal server error. internal_server_error
501 Feature not supported by the provider. endpoint_not_supported
503 The provider service is unavailable. provider_error
503 The connector service is currently overloaded. connector_overload
503 Excessive concurrent requests for unique set of credentials. connector_session_overload
503 The provider service is unavailable. temporarily_unavailable
504 The provider service timed out. provider_timeout
504 The connector service timed out. connector_timeout

Data API Changelog

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

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 banks which offer Payment Initiation APIs, and provides a single public API which enables clients to request payment via all integrated banks.

Payment initiation is currently supported by these banks:

  1. Lloyds Group: Lloyds, Halifax, Bank of Scotland
  2. RBS Group: RBS, NatWest, Ulster
  3. Barclays
  4. HSBC
  5. Santander
  6. Nationwide
  7. Danske Bank (formerly Northern Bank)
  8. Bank of Ireland UK
  9. AIB GB

The only payment mode currently supported by banks is Single Immediate Payment. Payment system users (i.e. payers) must authenticate to their bank provider for each payment, select the payment account and authorise the payment.

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

The Payments API allows you to make a single immediate payment. This is a one-off payment that cannot be future dated, i.e. it is executed as soon as possible after authorisation.

The API relies on our PISP permission in order to use the Open Banking infrastructure and initiate the payment. This means that funds will not transit through TrueLayer. The creditor and debtor account are connected directly through the underlying circuit operated by the involved banks.

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.

Payment initiation overview: Integration

  1. Obtain a client credentials grant from the authentication server
  2. Create a new single immediate payment resource on our resource server
  3. Redirect the user to the URI specified in the API response
  4. User selects a bank provider and is redirected to the bank authorisation page
  5. User authorises the payment and is redirected back to the specified application URI
  6. (Optional) Poll the payment resource to get an updated status of the transaction

Obtain a client credentials grant

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"
}

First we need to obtain a grant representing the client, to create a payment on a back channel. This prevents the final user from tampering with the actual payment details. Unlike our Data API, this grant doesn’t represent a user, but a client creating the payment.

Here is an example of this flow. Enter the request example on the command line to request an access token. The response should contain a valid token value.

Create a single immediate payment

There are three ways to create a single immediate payment, described in the three sub-sections below.

Payer selects bank account

Request

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     -H "Content-Type: application/json" \
     --data '{
  "amount": 350,
  "currency": "GBP",
  "remitter_reference": "ECOM-12345-ABCD",
  "beneficiary_name": "Ecommerce Shop",
  "beneficiary_sort_code": "102030",
  "beneficiary_account_number": "88881234",
  "beneficiary_reference": "ecommerce-12345", 
  "redirect_uri": "http://www.ecommerce.com/redirect"
}' \
https://pay-api.truelayer.com/single-immediate-payments

Response

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

This sub-section describes the request made when the payee specifies the amount and beneficiary bank account, but the payer may select which bank and bank account they pay from using TrueLayer’s UI.

See the payment resource representation reference for more details on the meaning of the fields and how to use them.

The response includes:

Payee selects bank account

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://pay-api.truelayer.com/?payment_id=44708581-1967-4120-8f6a-1e532f1bf52a",
      "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 sub-section describes the request made when the payee specifies the amount and both the remitter and beneficiary bank accounts. For instance, this might be in a situation where the payer has already provided details of their bank account to the payee.

The data fields are the same as for when the payer selects the bank account to pay from, except that the following additional information must be provided:

Payee selects bank

This model is the same as the option Payee selects bank account above, except that here you specify the provider ID only i.e. you pre-select the bank that can be used to pay, but not the specific account. As with the Payee selects bank account option, this means that your user will be directed straight from your user interface to the bank authentication flow. For this version, the request is the same as for Payer selects bank, but you only add one additional parameter to the API request:

remitter_provider_id

To get a list of valid remitter_provider_id values, call this API endpoint (no authentication required).

https://pay-api.truelayer.com/available-providers

The JSON response will include an array of provider objects; the id element of each object will be the remitter_provider_id you need to submit in your payment POST request. e.g. for Lloyds in the UK, the remitter_provider_id value is ob-lloyds.

Redirect the user to the payment authorisation

The application will redirect the user to the redirect_uri returned from the payment creation response.

301 GET https://pay.truelayer.com/?payment_id=a55f2e12-55ef-410c-9341-628033a62dc3

Remitter details not specified

Bank selection dialog

If the payee has not specified the remitter bank account details, the user needs to choose which bank they will pay from.

The end user will be presented with a bank selection dialogue, allowing them to select the bank which they will want to use for this payment.

Note that this URI may be accessed with the same result as long as the end user has not selected a bank. Once a bank button has been clicked, the payment resource will be updated and it will not be possible to load the page again to select a different provider bank for the payment.

Remitter details specified

If the payee has specified the remitter bank account details, the end user does not need to choose their bank, they simply need to authorise the payment. They will be redirected straight to the bank portal.

User is redirected to the selected bank portal

Bank consent login

Once the end user selects the bank, we will redirect them to the payment authorisation page. They can then confirm the amount, the destination and possibly choose an account from where to withdraw the funds (in case they have multiple accounts with the given bank).

User authorises the payment

When the end user authorises the payment, they will be redirected back to the URI specified by the Application during the creation of the payment. We will also append the payment ID to the query parameters; this will enable you to match up the redirect request to your record of the earlier payment API response. In the example below, the redirect_uri specified by the client is https://client.app.com/payment_redirect and the payment ID has been appended to it.

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

Polling for payment status

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. Successful payments should have a status value of executed.

Request

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

The following additional field will be present in the payment resource representation:

Field Type Description
remitter_provider_id string a TrueLayer identifier for the bank which processed the payment (the payer’s bank)

Response

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"
    }
  ]
}

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

Technical Notes

Representations

This section explains the fields in the representations passed in requests and responses.

Field Type Description/Format
simp_id UUID Unique identifier for this payment resource; used to locate a resource with a GET request
auth_uri URI URI to redirect user to in order to authorise a new payment initiation request
amount integer Amount of payment in minor currency units e.g. for GBP, in pennies; e.g. for EUR in cents
currency string ISO 4217 currency code. p
beneficiary_name string Name of payee account holder. For merchants i.e. sales payments this will be the name of the merchant. This will be displayed on the payer’s bank account statement.
beneficiary_sort_code string Sort code of payee account: six digits only, no whitespace or punctuation
beneficiary_account_number string Number of payee account: eight digits only, no whitespace or punctuation
beneficiary_reference string Reference information which is displayed on the payee’s bank account statement. Can be used to uniquely identify a transaction, and assist with reconciliation. Up to 18 characters long. Also known as “RemittanceInformation/Reference”.
Note that with some banks, this is also displayed on the payer’s bank account statement, but not for all.
remitter_name string Name of payer account holder. If provided, this will be displayed on the payee’s bank account statement.
remitter_sort_code string Sort code of payer account: six digits only, no whitespace or punctuation
remitter_account_number string Number of payer account: eight digits only, no whitespace or punctuation
remitter_reference string Reference of API client to describe and uniquely identify this transaction. Up to 31 characters long. This is also known as the “merchant reference”, or “EndToEndIdentification”.

This field is displayed to the end user in the bank selection dialog.

Note that currently this is only displayed by the RBS Group banks in their authorisation flows and payer bank statements (as “Transaction Reference”) and is generally not visible in other bank statements. It can be used when contacting a bank directly for support about a specific payment.
remitter_provider_id string Identifier of an open banking provider (ASPSP).

If this value is specified when creating a payment response, the payer will be redirected straight to this provider, without the chance to select their provider.

If this value is not specified when creating a payment response, it will be added to the resource after the user has selected their bank provider using the TrueLayer dialog.

Valid values may be queried from this endpoint: https://pay-api.truelayer.com/available-providers e.g. ob-lloyds
redirect_uri URI API client’s URI where the end user should be redirected after authorising the payment
status string Payment status. See section below for explanation of possible values.
Transaction References

Note that there are a number of API fields available for specifying transaction meta-data. Usage depends upon the specific scenario that you wish to implement.

If you are implementing payment for goods or services, we recommend:

We recommend checking the appearance of your payments on the payer’s bank account statement while testing to make sure it looks appropriate for your payers.

Payment Status

States

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.

Settlement

When a payment has the status “executed”, this means that the payer’s bank has confirmed that the payment has been sent successfully via the national payment system (in the UK, this is Faster Payments).

Note that this is not the same thing as confirmation of settlement. In order to verify that the funds are definitively settled, i.e. they are available for use in the payee’s bank account, the beneficiary account needs to be checked directly.

Generally, all successfully executed payments are settled within seconds during working hours. Here is information from the Faster Payments website:

Provided the sending and receiving bank/building society are Direct Participants of Faster Payments, payments are usually available almost immediately, although they can sometimes take up to two hours.

These timescales can still apply if either the sending or receiving bank is not a Direct Participant of Faster Payments.

Some payments will take longer, especially outside normal working hours.

You should talk to your bank/building society if the speed of the payment is particularly important.

As a minimum, all financial institutions in the UK must abide by the Payment Services Directive (PSD) - this states that any payments made by mobile, internet or phone banking (including standing orders) must arrive by the end of the following business day at the latest.

You should contact your bank or building society directly for more information on the exact process they follow when you request a payment to be made from your account.

See Faster Payments FAQs for more details.

State Transition Diagram

This diagram shows the possible states which a Payment resource may exist in, and the valid transitions between states. See above for an explanation of the states.

State transition diagram

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

User Interface Guidelines

This section provides guidance on the implementation of the client UI.

Payment Flow

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.

Regulatory Messaging

If you require your end user to select their bank, they will always be redirected to the TrueLayer bank selection dialog, where required terms will be displayed.

If you select your end user’s bank or bank account (Payer selects bank account or Payee selects bank options in payment initiation integration overview above), they will be redirected straight to their bank. In this case, you will need to display some terms relating to consent on behalf of TrueLayer. We can provide this information to you; this will also be covered in your TrueLayer agreement.

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

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 Reference

The Payments API provides endpoints to create and query payment resources. Like the Data API, all endpoints require authorisation using access_token.

To call the Payments API, your account must have specific permission assigned. To enable this permission, please contact support@truelayer.com.

Create a payment

Request

curl -X POST \
     -H "Authorization: Bearer ${access_token}" \
     --data '{
  "amount": 350,
  "currency": "GBP",
  "remitter_reference": "ECOM-12345-ABCD",
  "beneficiary_name": "Ecommerce Shop",
  "beneficiary_sort_code": "102030",
  "beneficiary_account_number": "88881234",
  "beneficiary_reference": "ecommerce-12345", 
  "redirect_uri": "http://www.ecommerce.com/redirect"
}' \
https://pay-api.truelayer.com/single-immediate-payments

Response

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

Create a new payment initiation request.

Request

Field Type Description
amount integer MANDATORY. The amount in minor currency units of the payment. e.g. 101 would mean £1.01 for a GBP payment. e.g. 1 would mean £0.01 for a GBP payment.
currency string MANDATORY. The ISO 4217 three letter alpha currency code. Only “GBP” is supported currently, other currency values will return an error.
remitter_reference iso20022 text MANDATORY. Reference of API client to describe and uniquely identify this transaction. Up to 31 characters long. This is also known as the “merchant reference”, or “EndToEndIdentification”. This field is displayed to the user in the bank selection dialog. Note that currently this is only displayed by the RBS Group banks in their authorisation flows and payer bank statements (as “Transaction Reference”) and is generally not visible in other bank statements. It can be used when contacting a bank directly for support about a specific payment.
beneficiary_name iso20022 text MANDATORY. Name of payee account holder. For merchants i.e. sales payments this will be the name of the merchant. This will be displayed on the payer’s bank account statement.
beneficiary_sort_code string MANDATORY. Sort code of payee account: six digits only, no whitespace or punctuation
beneficiary_account_number string MANDATORY. Number of payee account: eight digits only, no whitespace or punctuation
beneficiary_reference iso20022 text MANDATORY. Reference information which is displayed on the payee’s bank account statement.
Can be used to uniquely identify a transaction, and assist with reconciliation. Up to 18 characters long. Also known as “RemittanceInformation/Reference”.
Note that with some banks, this is also displayed on the payer’s bank account statement, but not for all.
redirect_uri URI MANDATORY. API client’s URI where the user should be redirected after authorising the payment. Note that TrueLayer will append the payment_id to the URI when redirecting the user. This URI must be added to the application’s whitelist of redirect URIs in the Console here: https://console.truelayer.com/settings/application
remitter_name iso20022 text OPTIONAL. Name of payer account holder. If provided, this will be displayed on the payee’s bank account statement.
remitter_sort_code string OPTIONAL. Sort code of payer account: six digits only, no whitespace or punctuation
remitter_account_number string OPTIONAL. Number of payer account: eight digits only, no whitespace or punctuation
remitter_provider_id string OPTIONAL. Identifier of an open banking provider (ASPSP).
If this value is specified when creating a payment response, the payer will be redirected straight to this provider, without the chance to select their provider.
If this value is not specified when creating a payment response, it will be added to the resource after the user has selected their bank provider using the TrueLayer dialog.
Valid values may be queried from this endpoint: https://pay-api.truelayer.com/available-providers
e.g. ob-lloyds

Response

Response fields are the same as in the request representation. The fields below will be added in the response representation.

Field Type Description
simp_id UUID Unique identifier for this payment resource; used to locate a resource with a GET request
auth_uri URI URI to redirect user to in order to authorise a new payment initiation request
status string Status of this payment resource. Possible values include: new, authorised, cancelled, rejected, failed, submitted, executed

Query a single payment

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": "submitted"
    }
  ]
}

Get a single immediate payment representation using its unique simp_id.

Query multiple payments

Request

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

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": "submitted"
    },
    {
      "simp_id": "fdea4e33-216d-4671-80d2-10af94d1a73c",
      "created_at": "2018-10-01T16:01:00.0000000+00:00",
      "amount": 450,
      "currency": "GBP",
      "beneficiary_reference": "ecommerce-12346",
      "beneficiary_name": "Ecommerce Shop",
      "beneficiary_sort_code": "102030",
      "beneficiary_account_number": "88881234",
      "remitter_reference": "ECOM-12345-ABCE",
      "redirect_uri": "http://www.ecommerce.com/redirect",
      "remitter_provider_id": "ob-lloyds",
      "status": "authorised"
    }
  ]
}

Get a list of all single immediate payment representations for an account.

Payments API errors

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

HTTP Status Description Error Code
400 The supplied parameters are not valid. parameter_error
400 A payment with supplied id can not be found. invalid_payment_id_error
500 A transient error with bank or an unspecified error occurred. Please contact support if this persists. internal_server_error
401 The supplied Authorization token is invalid

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 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
            }
          ],
          "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
            }
          ],
          "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
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: