Introduction

TrueLayer is an open banking solution that allows your customers to make secure, direct, payments from their bank accounts to you.

TrueLayer is a reliable alternative to traditional payment methods, ensuring instant payments, refunds, and payouts.

TrueLayer via BR-DGE

BR-DGE currently supports the following features with TrueLayer:

• Payments & Deposits
• SignUp+
• Refunds
• Cancel
• Payouts
  • Verified Payouts
• Notifications

Onboarding for TrueLayer

When integrating TrueLayer via the BR-DGE platform, you are enabling BR-DGE to forward your request to TrueLayer on your behalf. To do this BR-DGE requires you to provide us with some details from your TrueLayer account. A full onboarding guide, including the steps required to enable Truelayer via BR-DGE, can be found in our Support Centre

Once you're ready to enable TrueLayer on your BR-DGE retail channels, please get in touch with our support team.

Integration Methods

API

Payments

• Step 1 - Initiate Checkout

  Your customer proceeds to your checkout page

• Step 2 - Select Payment Method

  Your customer selects TrueLayer as a payment method on your checkout page

• Step 3 - Backend Communication

  Your checkout page communicates with your server side system

• Step 4 - Payment Request to BR-DGE

  Your server side sends a TrueLayer payment request to BR-DGE

📘

Landing page URLs must be provided in this step

• Step 5 - Receive TrueLayer Response

  You will receive a BR-DGE payment response containing a redirect URL

• Step 6 - Redirect Customer to TrueLayer

  You redirect your customer with the redirect URL returned in step 5

• Step 7 - Customer Bank Account Selection

  Your customer selects their bank, the account they wish to make the payment with

📘

TrueLayer will offer a list of accounts if your customer has several accounts

• Step 8 - Customer Approves Payment

  Your customer approves the payment

• Step 9 - Redirect to Landing Page

  Your customer will be redirected to the appropriate landing page specified in Step 4 depending on the outcome of the deposit

📘

The payment should only be considered successful once you have received a notification confirming the payment has been captured, or if you are not relying on notification, once the state of the payment has moved to CAPTURED.

• Step 10 - Payment Confirmation Notification

  You will receive a BR-DGE notification confirming the outcome of the payment/deposit

📘

Alternatively you can query the state of the payment to confirm the outcome of the payment/deposit via the BR-DGE /v1/payments/{paymentId}/status endpoint.

• Step 11 - Payment Instrument Account Selection Notification

  You will receive a BR-DGE notification confirming the account used for the payment

How to make a TrueLayer Payment

To create a TrueLayer payment, send a request to POST /v1/payments with the minimum mandatory fields and the paymentInstrument type of trueLayer.

The following JSON request is an example of how to create a TrueLayer payment via BR-DGE.

{
    "amount": "1000",
    "channel": "ios",
    "currencyCode": "GBP",
    "customerEmail": "[email protected]",
    "customerFirstName": "customerFirstName",
    "customerIpAddress": "123.100.100.200",
    "customerLastName": "customerLastName",
    "customerOrderCode": "code",
    "customerPhoneNumber": "+44 07456111300",
    "customerSessionId": "123456",
    "orderDescription": "Taxi fare",
    "billingAddress": {
        "country": "GB",
        "address1": "billingAddress1",
        "town": "billingTown",
        "county": "billingCounty",
        "postcode": "AB1C23",
        "phoneNumber": "+44 07891110000",
        "firstName": "billingFirstName",
        "lastName": "billingLastName"
    },
    "browserData": {
        "acceptHeader": "application/json",
        "colorDepth": "32",
        "javaEnabled": true,
        "language": "EN_en",
        "screenHeight": 768,
        "screenWidth": 1024,
        "timeZone": 0,
        "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36"
    },
    "customerDateOfBirth": "2024-02-24",
    "paymentInstrument": {
       "type": "trueLayer",
       "returnUrl": "https://br-dge.to/",
       "verifyCustomerName": true,
       "verifyCustomerAge": true,
       "signupPlus": true
    }
}

You should expect to receive a response similar to the following:

{
    "code": "2101",
    "message": "Pending",
    "id": "68e3b21e4c90e49225e57522080a56ea",
    "paymentId": "d576c518-721b-4bae-9dc5-04a4d0abcbb0",
    "amount": 1000,
    "currencyCode": "GBP",
    "actionRequired": true,
    "action": {
        "type": "REDIRECT",
        "paymentId": "d576c518-721b-4bae-9dc5-04a4d0abcbb0",
        "data": {
            "url": "https://payment.truelayer-sandbox.com/payments#payment_id=5181a1bc-df81-4d88-9a8f-4b14f5f5eecc&resource_token=eyJhbGciOiJSUzUxMiIsImtpZCI6IkRCejExcEFuUGNXVndqaFBNWERuckNyQ0ZrT1p0Y2FqYWtjU21GNmJiVk0iLCJ0eXAiOiJKV1QifQ&return_uri=https://br-dge.to/",
            "status": "authorization_required",
            "providerTransactionId": "5181a1bc-df81-4d88-9a8f-4b14f5f5eecc"
        }
    },
    "psp": {
        "name": "TrueLayer",
        "transactionId": "5181a1bc-df81-4d88-9a8f-4b14f5f5eecc"
    },
    "pspId": "TRUELAYER",
    "customerOrderCode": "98679ac5-bd47-405b-a1b0-99787a430f5c"
}

You should then redirect the customer to the link provided in action.data.url to complete the payment.

⚠️

You should not change or alter the redirect URL in any way.

Once the customer has completed the payment you will receive a webhook from BR-DGE indicating that the payment status has changed. If you are not subscribed to BR-DGE notifications then you can query the result of the payment using the GET /v1/payments/{paymentId}/status endpoint.

At the end of the TrueLayer payment flow your customer will be returned to the URL you specified in paymentInstrument.returnUrl when creating the TrueLayer payment.

User Bank Selection

When setting providerId to a valid provider ID your customer will not be able to change their Bank provider in the TrueLayer payment page, instead they will be directed to the provider you specify in the providerId field.

📘

The Provider ID is generated by TrueLayer after the first successful payment is completed using an account from the Provider Bank.

Omitting this field from the paymentInstrument object when creating a TrueLayer payment will allow your customer to select their bank account within the TrueLayer payment page.

The following JSON shows an example of how you can use paymentInstrument.providerId to force the bank or financial institution used in the payment.

...
    "paymentInstrument": {
        "type": "trueLayer",
        "returnUrl": "https://br-dge.to/",
        "providerId": "ob-natwest"
    },
...

TrueLayer SignUp+

SignUp+ is a TrueLayer feature that enables you to retrieve additional user details like your customers first and last name, date of birth, and registered address; as it shows on their bank account.

The additional data can be used to streamline user onboarding processes, or support KYC & AML regulations.

SignUp+ can be used through BR-DGE by setting paymentInstrument.signupPlus to true when the Payment Instrument is of type trueLayer

📘

The SignUp+ flag can be seen in the request example above

Cancellations (void)

TrueLayer payments made via BR-DGE can be cancelled prior to the payment entering an AUTHORIZEDstatus using the BR-DGE Void Payment REST API. To cancel a TrueLayer Payment send a request to POST /v1/payments/{paymentId}/void using the paymentId returned when you created the original payment.

See the API examples on our void endpoint for details on how to perform a cancellation of a TrueLayer payment via BR-DGE.

Refunds

Payments made using TrueLayer via BR-DGE can be refunded using the Refund REST API. To refund a TrueLayer payment send a request to POST /v1/payments/{paymentId}/refund using the paymentId returned when you created the original payment.

📘

BR-DGE support both full & partial refunds of TrueLayer payments. See the API examples on our refund endpoint for details on how to perform a refund of a TrueLayer payment via BR-DGE

Payouts

BR-DGE support bank payouts via TrueLayer using the Create a Payout REST API. When performing a payout using TrueLayer there are 4 different methods of account selection.

• Payment Source Id - a Payout to an account identifier obtained from a previous payment.
• SCAN (Sort Code and Account Number) - where the account details of the account the payout is intended for are known in advance.
• IBAN (International Bank Account Number) - where the IBAN details of the account the payout is intended for are known in advance.
• Verified Payout - when you want to confirm the user has made a specific debit from the account to ensure a closed loop payout.

TrueLayer Payouts via BR-DGE work in the following way:

• Step 1 - You send a Payout request to BR-DGE

  Your server side sends a TrueLayer payout request to BR-DGE using a paymentInstrument type of trueLayer.

• Step 2 - You receive a synchronous response

  You will receive a synchronous response from BR-DGE on the outcome of the payout.

• Step 3 - You receive a Payment Confirmation notification

  You will receive a BR-DGE notification on the outcome of the payout once it has been fully processed by TrueLayer.

Payout with a Payment Source ID

To perform a TrueLayer Payout with Payment Source ID via BR-DGE, send a Payout request to POST /v1/payouts with the paymentInstrument.paymentSourceId and customerId specified in the paymentInstrument object

The paymentInstrument.paymentSourceId is the BR-DGE Payment ID from a previous TrueLayer payment made via BR-DGE.

{
  "amount": 1000,
  "currencyCode": "GBP",
  "paymentInstrument": {
    "type": "trueLayer",
    "paymentSource": {
      "paymentSourceId": "41b500a4-5379-4f30-9eda-2fcc032afc37"
    }
  },
  "recipient": {
    "firstName": "Ray",
    "lastName": "Patyou",
    "customerId": "17e5e9e8-3122-4dae-a8be-884e917e1729",
    "email": "[email protected]",
    "dateOfBirth": "2002-02-20"
  },
  "reference": "1234",
  "customerId": "17e5e9e8-3122-4dae-a8be-884e917e1729",
  "merchantTransactionId": "1234"
}

You should expect to receive a response similar to the following:

{
    "code": "1000",
    "id": "68e3d6add61befec660704c234aee432",
    "message": "Approved",
    "paymentId": "0bd418ff-91d4-44b7-bd62-a31d95c43b20",
    "psp": {
        "name": "TrueLayer",
        "transactionId": "d6d84254-d604-4332-b180-72c265340217"
    },
    "merchantTransactionId": "1234",
    "amount": 1000,
    "currencyCode": "GBP"
}

Payout with Sort Code & Account Number (SCAN)

To perform a TrueLayer Payout with a SCAN via BR-DGE, send a Payout request to POST /v1/payouts with the sortCode and accountNumber specified in the paymentInstrument.bankDetails object.

⚠️

It is your responsibility to ensure you collect the correct details from the customer prior to submitting a Payout request with a sort code & account number

{
  "amount": 1000,
  "currencyCode": "GBP",
  "paymentInstrument": {
    "type": "trueLayer",
    "bankDetails": {
        "bankCountry": 'GB',
        "sortCode": 560029,
        "accountNumber": 26207729
    }
  },
  "recipient": {
    "firstName": "Ray",
    "lastName": "Patyou",
    "customerId": "0a3a0f14-1225-466f-be8b-868285ac4ead",
    "email": "[email protected]",
    "dateOfBirth": "2002-02-20"
  },
  "reference": "12345",
  "customerId": "0a3a0f14-1225-466f-be8b-868285ac4ead",
  "merchantTransactionId": "1234
}

You should expect to receive a response similar to the following:

{
    "code": "1000",
    "id": "68e3d6add61befec660704c234aee432",
    "message": "Approved",
    "paymentId": "0bd418ff-91d4-44b7-bd62-a31d95c43b20",
    "psp": {
        "name": "TrueLayer",
        "transactionId": "d6d84254-d604-4332-b180-72c265340217"
    },
    "merchantTransactionId": "1234",
    "amount": 1000,
    "currencyCode": "GBP"
}

Payout with an International Bank Account Number (IBAN)

To perform a TrueLayer Payout with an IBAN via BR-DGE, send a Payout request to POST /v1/payouts with the bankDetails.bankDetailsFormat set to IBAN and the customers IBAN number in the bankDetails.iban field, of the paymentInstrument object.

⚠️

It is your responsibility to ensure you collect the correct details from the customer prior to submitting a Payout request with an IBAN

{
  "amount": 1000,
  "currencyCode": "GBP",
  "paymentInstrument": {
    "type": "trueLayer",
    "bankDetails": {
        "bankCountry": 'IBAN',
        "iban" : "BE1234567890"
    }
  },
  "recipient": {
    "firstName": "Ray",
    "lastName": "Patyou",
    "customerId": "0a3a0f14-1225-466f-be8b-868285ac4ead",
    "email": "[email protected]",
    "dateOfBirth": "2002-02-20"
  },
  "reference": "1234",
  "customerId": "0a3a0f14-1225-466f-be8b-868285ac4ead",
  "merchantTransactionId": "1234"
}

You should expect to receive a response similar to the following:

{
    "code": "1000",
    "id": "68e3d6add61befec660704c234aee432",
    "message": "Approved",
    "paymentId": "0bd418ff-91d4-44b7-bd62-a31d95c43b20",
    "psp": {
        "name": "TrueLayer",
        "transactionId": "d6d84254-d604-4332-b180-72c265340217"
    },
    "merchantTransactionId": "1234",
    "amount": 1000,
    "currencyCode": "GBP"
}

Verified Payout

To perform a TrueLayer Verified Payout via BR-DGE, send a Payout request to POST /v1/payouts with the searchTokens[], amount, currencyCode andpaymentDate fields in the paymentInstrument.verification populated with the details from a previously processed TrueLayer payment.

You must also provide a returnUrl when doing a Verified Payout.

📘

verificationDetails.searchTokens[] is an array of values that TrueLayer can use to attempt to identify a previous payment in their system.

{
  "recipient": {
    "firstName": "John",
    "ipAddress": "123.100.100.200",
    "customerId": "Customer001",
    "email": "[email protected]",
    "lastName": "Smith"
  },
  "paymentInstrument": {
    "type": "trueLayer",
    "verification": {
      "providerId": "mock-payments-gb-redirect",
      "returnUrl": "br-dge.to",
      "verificationDetails": {
        "searchTokens": [
          "foo",
          "bar",
          "baz"
        ],
        "amount": 100,
        "currencyCode": "GBP",
        "paymentDate": "2025-04-23"
      }
    }
  },
  "psp": "TrueLayer",
  "amount": 100,
  "currencyCode": "GBP",
  "reference": "abc123",
  "purpose": "leisure"
}

You should expect to receive a response similar to the following:

{
    "code": "2101",
    "id": "68e3d70a4bcf20de8ee0095ee26638ee",
    "message": "Pending",
    "paymentId": "9cf0ddb8-8539-4ed6-a69c-9b9396f08e1d",
    "psp": {
        "name": "TrueLayer",
        "transactionId": "fce1068c-6082-4af2-ac20-3a3c59b49698"
    },
    "action": {
        "type": "REDIRECT",
        "paymentId": "9cf0ddb8-8539-4ed6-a69c-9b9396f08e1d",
        "data": {
            "redirectUrl": "https://app.truelayer-sandbox.com/payouts#payout_id=fce1068c-6082-4af2-ac20-3a3c59b49698&resource_token=eyJhbGciOiJSUzUxMiIsAQvvOwi8EWy3YndbGPZxJGDjA&return_uri=https://br-dge.to/"
        }
    },
    "actionRequired": true,
    "amount": 1000,
    "currencyCode": "GBP"
}

The link returned in the action.data.redirectUrl field should be used to redirect the payer to complete the payout.

Notifications

A subset of TrueLayer notifications are supported via BR-DGE. The following TrueLayer notification types are currently supported by BR-DGE:

• payment_authorized
• payment_executed
• payment_settled
• payment_failed
• payment_settlement_stalled
• payment_reversed
• payout_executed
• payout_failed
• refund_execute
• refund_failed

The following table indicates the notifications TrueLayer will send in different transaction scenarios, the type of BR-DGE notification they are normalised to, and the associated BR-DGE transaction status you should expect:

BR-DGE TrueLayer notifications follow the same standard format as all our other notification types. The following JSON are examples of different notifications for TrueLayer via BR-DGE:

{
  "type": "payment",
  "merchantAccountId": "4667f308-8518-4daa-9b40-4c68ca7aa668",
  "id": "b058aef0-5cb6-4325-980f-5bf30f6fc52e",
  "code": "1000",
  "message": "No message provided",
  "status": "CAPTURED",
  "psp": {
    "name": "TrueLayer",
    "transactionId": "c44a5403-9bc5-4f91-aa65-93a0a4291a6b",
    "message": "{\"type\":\"payment_settled\",\"event_version\":1,\"event_id\":\"d2d00358-6a48-42d1-9a2d-84acaeba992a\",\"payment_id\":\"c44a5403-9bc5-4f91-aa65-93a0a4291a6b\",\"payment_method\":{\"type\":\"bank_transfer\",\"provider_id\":\"mock-payments-gb-redirect\",\"scheme_id\":\"faster_payments_service\"},\"settled_at\":\"2025-10-16T14:22:05.315Z\",\"payment_source\":{\"id\":\"0db040f6-03d9-5bb9-1710-7878f7c4b0ef\",\"account_identifiers\":[{\"type\":\"sort_code_account_number\",\"sort_code\":\"040668\",\"account_number\":\"00000871\"},{\"type\":\"iban\",\"iban\":\"GB75CLRB04066800000871\"}],\"account_holder_name\":\"JOHN SANDBRIDGE\"},\"user_id\":\"7467806d-6b3f-414a-bf4f-1795c5e835da\"}",
    "additionalInfo": {
      "customer": {
        "customerId": "7467806d-6b3f-414a-bf4f-1795c5e835da"
      },
      "paymentSourceId": "0db040f6-03d9-5bb9-1710-7878f7c4b0ef",
      "providerId": "mock-payments-gb-redirect",
      "type": "truelayer"
    }
  },
  "hashCode": "rErRK6MN1ADzGuYjqn786YVB12vtiSQxhyPI1peWSOg=",
  "customerOrderCode": "653b6ce6-1103-4025-adeb-ae59f59ca986",
  "amount": 1000,
  "currencyCode": "GBP",
  "paymentInstrument": "trueLayer"
}

{
  "type": "payout",
  "merchantAccountId": "4667f308-8518-4daa-9b40-4c68ca7aa668",
  "id": "7fd82f4f-212f-4dee-94ce-d62df6e6cbff",
  "code": "1000",
  "message": "No message provided",
  "status": "APPROVED",
  "psp": {
    "name": "TrueLayer",
    "transactionId": "4a4218d6-512a-45c1-bac7-2b0966b3f113",
    "message": "{\"type\":\"payout_executed\",\"event_id\":\"d107eca0-6e24-40cc-6746-2e18c3e6007b\",\"event_version\":1,\"payout_id\":\"4a4218d6-512a-45c1-bac7-2b0966b3f113\",\"executed_at\":\"2025-10-17T10:31:41.612366Z\",\"beneficiary\":{\"type\":\"payment_source\",\"user_id\":\"7467806d-6b3f-414a-bf4f-1795c5e835da\",\"payment_source_id\":\"0db040f6-03d9-5bb9-1710-7878f7c4b0ef\"},\"scheme_id\":\"faster_payments_service\"}",
    "additionalInfo": {
      "customer": {
        "customerId": "7467806d-6b3f-414a-bf4f-1795c5e835da"
      },
      "paymentSourceId": "0db040f6-03d9-5bb9-1710-7878f7c4b0ef",
      "type": "truelayer"
    }
  },
  "hashCode": "LPpYOO7sWWd+tOylBDgNR6Ziv4MJiMK+1uu6qGl0kK0=",
  "reference": "Handcrafted",
  "merchantTransactionId": "system",
  "amount": 1000,
  "currencyCode": "GBP",
  "paymentInstrument": "trueLayer"
}

The fields of a TrueLayer notification are populated in the following way:

Support

To get started with TrueLayer via BR-DGE, or if you have any questions, please get in contact with support.