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
andaddress
- 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 should provide this information for AML/sanction screening reasons, and to reduce the number of RFIs raised. |
beneficiary.address | The address of the external account holder. This parameter contains six child fields for information including the first and second line of the address, the city/town, state/county, postal code, and country code. You should provide this information for AML/sanction screening reasons, and to reduce the number of RFIs raised. |
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 /v3/payouts HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature:{SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com
{
"merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51",
"amount_in_minor": 1,
"currency": "GBP",
"beneficiary": {
"type": "external_account",
"account_holder_name": "Jonathan Sandbridge",
"account_identifier": {
"type": "sort_code_account_number",
"sort_code": "040668",
"account_number": "00000871"
},
"reference": "TestCo-627364",
"address": {
"address_line1": "40 Finsbury Square",
"state": "London",
"city": "London",
"country_code": "GB",
"zip": "EC2A 1AE"
},
"date_of_birth": "1990-01-31"
}
}
This example contains the mandatory account_holder_name
and account_identifier
parameters, which identify the payout beneficiary. It also contains the option date_of_birth
and address
parameters, which should be provided for AML purposes and to reduce the number of RFIs raised.
Below is an example of a successful response, including the payout id
:
{
"id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20"
}
User information to collect
When you create an open-loop payout, you provide user information in the beneficiary
object. The available parameters that contain user information in the beneficiary
object are account_holder_name
, account_identifier
,date_of_birth
and address
.
In an open-loop payout you must provide user information in these two mandatory parameters:
- The
account_holder_name
of the user - The
account_identifier
for the user (this also specifies where the payout will be sent)
You should also provide user information in these two optional parameters, for AML/sanction screening purposes and to reduce the number of RFIs raised:
- The
date_of_birth
of the user - The
address
of the user
User information for businesses
If you are making a payment to a business using the
external_account
method for thebeneficiary
, you should still provide 'user information' in the payout. For theaccount_holder_name
,date_of_birth
andaddress
parameters, provide the business name, business founding date and business address respectively.
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 20 days ago