NAV Navbar
Logo
curl

Introduction

Welcome to the TrueLayer API Reference!

TrueLayer allows applications to connect securely with their customer’s bank, in order to either read their financial data or initiate payments. TrueLayer provides a unified interface between multiple financial institutions and third party applications over a common RESTful API.

Getting started

  1. Sign-up and obtain your client_id and client_secret. You will need to register at least one redirect_uri.
  2. For the Data API:
    1. Create an Authentication Link to authenticate your Customers
    2. Obtain an access_token following the Customer Authentication oAuth 2.0 flow
    3. Use the Data API to retrieve Customer’s personal information, account numbers and transaction data.
  3. For the Payments API:
    1. Create a client credentials grant to get a token to call the API.
    2. 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:

Open Banking/PSD2: We use the 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.

Credential-sharing: TrueLayer uses a 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.

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

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.

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

Data API v1

Authentication

Customer authentication and Client authorization (to access financial data on their customer’s behalf) is achieved using the industry standard OAuth 2.0 three-legged server code flow RFC 6749

According to the OAuth roles TrueLayer is the Authorization Server, the Customer is the Resource owner and the Application is the Client.

Authentication

Note that this section focuses on authentication for access to account data. Please see the Payments Guide section below for information on how to create tokens to access the Payments API.

Definitions

Definition Description
Account A financial account with a Provider
Authorization Server The secure service hosted by TrueLayer that allows Customers to authenticate with their Provider credentials. It also offers API endpoints to obtain and renew access_token
Client An application implementing this API
Customer An application’s user and the owner of an account
Data API The API that provides access to Customers’s financial data
Permissions A set of permissions the Customer 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 Customer uses to access their accounts with a Provider

Identifiers

Identifier name Description Confidentiality Lifetime
access_token A short-lived JWT token used to access data on behalf of the Customer 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 Customer’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 Customer. 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 Customer’s identity information held by the Provider /data/v1/info
accounts Allows access to Customer’s account numbers and details /data/v1/accounts, /data/v1/accounts/${account_id}
accounts + balance Allows access to Customer’s account balances /data/v1/accounts/${account_id}/balance
accounts + transactions Allows access to Customer’s account transactions /data/v1/accounts/${account_id}/transactions
cards Allows access to Customer’s card numbers and details /data/v1/cards, /data/v1/cards/${account_id}
cards + balance Allows access to Customer’s card balances /data/v1/cards/${account_id}/balance
cards + transactions Allows access to Customer’s card transactions /data/v1/cards/${account_id}/transactions
offline_access Allows access to Customer’s data after the short-lived access_token expires. When this permission is granted a refresh_token will be returned refresh_token

Customer Authentication

  1. Authentication Link: The customer’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 Customer. 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

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

Choose your bank

  1. Code Redirect: Customer’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 Customer. 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

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 Customer 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. If omitted, this is set to true by default.
enable_credentials_sharing_providers_de OPTIONAL. if set to "true” the authentication dialog will show all available Credential-sharing Providers for Germany.
enable_oauth_providers OPTIONAL. if set to "true“ the authentication dialog will show all available oAuth Providers.

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

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

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

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
{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": "JTW-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 Customer
expire_in access_token validity in seconds. Default is 1 hour or specified by provider.
refresh_token A long lived code use 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

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
{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": "JTW-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 Customer
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

DELETE /api/delete
Authorization: Bearer ${access_token}
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

POST /api/debug
Content-Type: application/json

{"access_token": "ACCESS-TOKEN-HERE"}
curl -X POST -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"
}
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

GET /api/providers
curl https://auth.truelayer.com/api/providers
{
        "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 providers logo as used by TrueLayer
scopes List of Permissions supported by the provider

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.

Retrieve access_token metadata

GET /data/v1/me
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/me
{
    "results": [
        {
            "client_id": "test",
            "credentials_id": "6L7RxyPKX0THy1tw93PB4V+8DB+KjnX9Pxa451yXPu0=",
            "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
client_id string Your unique client identifier
credentials_id string Unique identifier of the set of credentials
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
scopes array Permission intersection for the Customer and Provider
privacy_policy string The version of TrueLayer’s Privacy Policy that the owner of the set of credentials has given consent to

Retrieve identity information

GET /data/v1/info
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/info
{
    "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 Customer’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 Customer
date_of_birth datetime Date of birth of the Customer
addresses[...].address string Full address of the Customer
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

GET /data/v1/accounts
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts
{
  "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 Customer’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

GET: /data/v1/accounts/${account_id}
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}
{
  "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 datime 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

GET: /data/v1/accounts/${account_id}/balance
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts/${account_id}/balance
{
  "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

GET: /data/v1/accounts/${account_id}/transactions
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/accounts/${account_id}/transactions?from=${from}&to=${to}"
{
  "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",
      "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
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

Retrieve account pending transactions

GET: /data/v1/accounts/${account_id}/transactions/pending
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
 "https://api.truelayer.com/data/v1/accounts/${account_id}/transactions/pending"
{
 "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",
     "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
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

List all cards

GET /data/v1/cards
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards
{
  "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 Customer’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

GET /data/v1/cards/${account_id}
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards/${account_id}
{
  "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 Customer’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

GET: /data/v1/cards/${account_id}/balance
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/cards/${account_id}/balance
{
  "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 statment, 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

GET: /data/v1/cards/${account_id}/transactions
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  "https://api.truelayer.com/data/v1/cards/${account_id}/transactions?from=${from}&to=${to}"
{
  "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",
      "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

Retrieve card pending transactions

GET: /data/v1/cards/${account_id}/transactions/pending
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
 "https://api.truelayer.com/data/v1/cards/${account_id}/transactions/pending"
{
 "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",
      "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

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

Asynchronous Requests and Webhooks

Data API supports asynchronous requests on all endpoints. 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.

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.

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

GET: /data/v1/accounts/${account_id}/transactions
Header: "Authorization: Bearer ${access_token}"
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 asynchronoulsy
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",
    "task_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 Customer’s credentials used to access a Provider
task_id string A unique ID associated with the task
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

GET: /data/v1/results/${task_id}
Header: "Authorization: Bearer ${access_token}"
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 Categories

Supported set of transaction categories used to identify the type of a transaction. Values are mapped from each providers proprietary category model into a core set that is consistent across all providers.

Returned as transaction_category for both account and card transactions.

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

Payments API v1

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

POST: /single-immediate-payments
Authorization: Bearer ${access_token}
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
{
  "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

GET: /single-immediate-payments/{id}
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  "https://pay-api.truelayer.com/single-immediate-payments/a55f2e12-55ef-410c-9341-628033a62dc3"
{
  "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

GET: /single-immediate-payments/
Authorization: Bearer ${access_token}
curl -H "Authorization: Bearer ${access_token}" \
  "https://pay-api.truelayer.com/single-immediate-payments/"
{
  "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 Guide

The first release of 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.

 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 ASPSP 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}"
     -- 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://customer.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://customer.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 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 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 user does not need to choose their bank, they simply need to authorise the payment. They will be redirected straight to the ASPSP portal.

User is redirected to the selected ASPSP portal

Bank consent login

Once the 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 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.

https://customer.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.

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 ASPSP which processed the payment (the payer’s bank)

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

State transition diagram

Initiate Payment

Initiate Payment

End-User Authorises Payment

End-User Authorises Payment

Polling Payment Status

Polling Payment Status

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 customer 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 customer’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.

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

Status API v1

The Status API exposes the availability and error rates of the TrueLayer Data API in a JSON format.

Retrieve Data API status

Request

GET: /api/v1/data/status
curl "https://status-api.truelayer.com/api/v1/data/status?\
from=2019-01-07 11:00:00&to=2019-01-08 13:00:00&providers=amex,ob-barclays,oauth-monzo\
&endpoints=cards,accounts"

Response

{
  "results": [
    {
      "timestamp": "2019-01-07 10:00:00.000",
      "providers": [
        {
          "provider_id": "oauth-monzo",
          "endpoints": [
            {
              "endpoint": "accounts",
              "availability": 97.24,
              "provider_error": 0,
              "truelayer_error": 2.76
            },
            {
              "endpoint": "accounts/balance",
              "availability": 100,
              "provider_error": 0,
              "truelayer_error": 0
            }
          ]
        },
        {
          "provider_id": "oauth-starling",
          "endpoints": [
            {
              "endpoint": "accounts",
              "availability": 100,
              "provider_error": 0,
              "truelayer_error": 0
            },
            {
              "endpoint": "accounts/balance",
              "availability": 100,
              "provider_error": 0,
              "truelayer_error": 0
            }
          ]
        }
      ]
    },
    {
      "timestamp": "2019-01-07 11:00:00.000",
      "providers": [
        {
          "provider_id": "oauth-monzo",
          "endpoints": [
            {
              "endpoint": "accounts",
              "availability": 100,
              "provider_error": 0,
              "truelayer_error": 0
            },
            {
              "endpoint": "accounts/balance",
              "availability": 92.86,
              "provider_error": 7.14,
              "truelayer_error": 0
            }
          ]
        },
        {
          "provider_id": "oauth-starling",
          "endpoints": [
            {
              "endpoint": "accounts",
              "availability": 96.43,
              "provider_error": 0,
              "truelayer_error": 3.57
            }
          ]
        }
      ]
    }
  ]
}      

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