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

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 should provide this information for AML/sanction screening reasons, and to reduce the number of RFIs raised.
beneficiary.addressThe 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 the beneficiary, you should still provide 'user information' in the payout. For the account_holder_name, date_of_birth and address 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:

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.