Make a payout to an external account
Learn about open-loop payouts and how to make one.
In an open-loop payout, a payment is made from a merchant account to an external account. There's no need for the external account to have previously made a payment via TrueLayer.
Before you start
To make an open-loop payout, you need:
- A merchant account and its
id
- These details about the external account receiving the payment:
- The
account_holder_name
- The
account_identifier
(sort code and account number or IBAN, depending on whether you're making a payment in the UK or EU) - The account holder's
date_of_birth
- The
As with all Payments API requests, you also need to:
- Set up request signing so you can create a
Tl-Signature
header for your request. - Generate an access token to include as a bearer token for your request.
This should also have the appropriate scopes (payments
for a single payment).
You should also provide an Idempotency-Key
with each of your payout requests.
Create a payout to an external account
To create an open-loop payout, make a POST request to /v3/payouts
endpoint, providing the parameters below. You must select external_account
as the beneficiary.type
for an open-loop payout.
Parameter | Description |
---|---|
merchant_account_id | The unique ID of the merchant account to pay out from. |
amount_in_minor | The amount in minor units. Minor units are the smallest units of a currency, depending on the number of decimals. For example: 1 GBP = 100 pence. |
currency | The currency of the payment in ISO 4217. Can be GBP or EUR. You cannot make a payment from GBP currency to a EUR account, or the opposite. The beneficiary account is specified in the beneficiary.account_identifier object. |
beneficiary.type | Should be external_account for an open-loop payout. |
beneficiary.reference | A reference for the payment. |
beneficiary.account_holder_name | The name of the external account holder. If making a payout to an external business account, this should be the company name. You must provide this information for AML purposes. |
beneficiary.account_identifier | The identifier for the beneficiary's account. This can be sort_code_account_number or iban , which each contain further objects where you can input the relevant information. Use SCAN to identify providers in the UK and Ireland. Use IBAN to identify accounts in the EU.Note that you cannot make payments from a GBP account to a EUR account, or the other way round. |
beneficiary.date_of_birth | The date of birth of the external account holder. If making a payout to an external business account, this should be the date the company was founded. You must provide this information for AML purposes. |
Integration options
Although the example on this page uses HTTP, we also offer complete .NET and Java libraries you can use to integrate payout creation.
This is an example of a open-loop payout creation request using HTTP.
POST /payouts HTTP/1.1
Content-Type: application/json; charset=UTF-8
Idempotency-Key: random
Tl-Signature: {SIGNATURE}
Authorization: Bearer {TOKEN}
Host: api.truelayer.com
{
"beneficiary": {
"type": "external_account",
"account_identifier": {
"type": "sort_code_account_number"
},
"reference": "Winnings",
"account_holder_name": "Pa Yout",
"date_of_birth": "1990-01-31"
},
"merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
"amount_in_minor": 100
"currency": "GBP"
}
In this example, the account_holder_name
and date_of_birth
fields have been completed. This is required for AML purposes.
Below is an example of a successful response, including the payout id
:
{
"id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
}
User details to collect
When you create an open-loop payout, you provide user details as part of the beneficiary
object. The available fields in the beneficiary
object are account_holder_name
, date_of_birth
and address
.
In an open-loop payout you must provide a minimum of:
- The name of the beneficiary.
- The date of birth of the beneficiary.
User details for businesses
If you are making a payment to a business using the
external_account
method for thebeneficiary
, provide the business name, business founding date and business address.
The example request below shows an open-loop payout creation request with the mandatory user detail objects account_holder_name
and date_of_birth
completed. It also includes values for the non-mandatory address
object.
POST /v3/payouts
{
"merchant_account_id": "c6ba13f2-35ef-4556-a99e-a6afd6275044",
"amount_in_minor": 100,
"currency": "GBP",
"beneficiary": {
"type": "external_account",
"reference": "Withdrawal",
"account_holder_name": "John Smith",
"account_identifier": {
"type": "sort_code_account_number",
"sort_code": "<sort code>",
"account_number": "<account number>"
},
"date_of_birth": "1992-08-03",
"address": {
"address_line1": "1 Hardwick St",
"address_line2": "Clerkenwell",
"city": "London",
"state": "London",
"zip": "EC1R 4RB",
"country_code": "GB"
}
},
"metadata": {
"prop1": "value1",
"prop2": "value2"
}
}
Monitor the status of a payout
To keep track of the status of a closed-loop payout, you can:
- Make a GET request to the
/v3/payouts/{id}
endpoint, which retrieves data about an individual payout, including its status. - Set up webhooks to track payout webhook notifications.
To make a GET request to the /v3/payouts/{id}
endpoint, use the payout ID as a path parameter.
curl --request GET \
--url https://api.truelayer.com/v3/payouts/id \
--header 'accept: application/json; charset=UTF-8'
This is an example response for a successful open-loop payout with a status of executed
:
{
"id": "fb976298-dc3a-4207-b399-c1084ee8232c",
"merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57",
"amount_in_minor": 1,
"currency": "GBP",
"beneficiary": {
"type": "external_account",
"account_holder_name": "Pa Yout",
"account_identifier": {
"type": "sort_code_account_number",
"sort_code": "040668",
"account_number": "00013279"
},
"account_identifiers": [
{
"type": "sort_code_account_number",
"sort_code": "040668",
"account_number": "00013279"
}
],
"reference": "Reference Example"
},
"scheme_id": "internal_transfer",
"status": "executed",
"created_at": "2023-02-08T16:20:26.987609393Z",
"authorized_at": "2023-02-08T16:20:27.216404095Z",
"executed_at": "2023-02-08T16:20:28.183Z"
}
Low balance notifications
When you set up your merchant account you can can specify a balance that you don't want your merchant account to go below. This can help ensure that you always have sufficient funds in order to make payouts to external accounts when requested.
To specify a balance that you don't want to go below, contact TrueLayer.
If you specify a balance, you receive a merchant account webhook: balance_notification
. This webhook can have a status of:
approaching_threshold
, which you receive when the balance is within 150% of the value of the specified threshold.below_threshold
, which you receive when the balance goes under your specified threshold.recovered
, which you receive when the merchant account balance exceeds 200% of the specified threshold after you top up your account.
For example, if you specified a balance of 1000, you would receive the:
approaching_threshold
webhook notification at a balance of 1500 or under.below_threshold
webhook notification at a balance of 1000 or under.recovered
webhook notification at a balance of 2000 or above after you top up your account frombelow_threshold
.
Updated 3 months ago