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

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.

ParameterDescription
merchant_account_idThe unique ID of the merchant account to pay out from.
amount_in_minorThe 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.
currencyThe 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.typeShould be external_account for an open-loop payout.
beneficiary.referenceA reference for the payment.
beneficiary.account_holder_nameThe 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_identifierThe 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_birthThe 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 the beneficiary, 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:

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 from below_threshold.