---
updatedAt: 2026-08-17T14:56:14.000Z
agentTools:
  projectIndex: https://docs.truelayer.com/llms.txt
---

# Make a payout to your business account

Make a secure payout to a preconfigured business account.

When you onboard with TrueLayer, you can link your merchant account to an existing business bank account. Once you have done this, there is a specific `type` of payout you can make which can only be sent to the linked business account.

<Image src="https://files.readme.io/5533f67fcc16be1b24e076741470928fc5dcef16e3eae076c304e764b834da99-Linked-business-account-example.svg" alt="Business account payouts are useful for withdrawing funds from your merchant account. As they can only be made to a single predefined account, they reduce the chance of human error. (light)" align="center" caption="Business account payouts are useful for withdrawing funds from your merchant account. As they can only be made to a single predefined account, they reduce the chance of human error." />

<br />

<Image src="https://files.readme.io/8a47fe8c9a8e30301903f3c1f4df4dc2c3442ff7ff59909d883399c9cc07d61d-Linked-business-account-example-dark.svg" alt="business account payouts (dark)" align="center" caption="Business account payouts are useful for withdrawing funds from your merchant account. As they can only be made to a single predefined account, they reduce the chance of human error." />

<br />

> 📘 Sweeping in Console
>
> Instead of making multiple manual payouts to your business account, you can set up regular payments from your <Glossary>merchant account</Glossary> to your business account from the [merchant account dashboard](/docs/merchant-account-dashboard) in Console. Alternatively, you can[Configure merchant account sweeping](/docs/merchant-account-sweeping).

## Business account payout overview

1. [**Authentication**](/docs/make-a-payout-to-your-business-account#1-authenticate-your--business-account-payout): Properly configure authentication before your request. This means you need a suitable `access_token` and headers for your request.
2. [**Request configuration**](/docs/make-a-payout-to-your-business-account#2-configure-your-business-account-payout): Provide information including the value of the payout, the bank details of the beneficiary of the payout and metadata.
3. [**Monitoring**](/docs/make-a-payout-to-your-business-account#3-monitor-your-business-account-payout): Set up webhooks for your payout so that you can track its progress and confirm its success.

## 1. Authenticate your  business account payout

Before you can make an business account payout, you must secure your requests.

### 1.1 Generate an `access_token`

You must include an `access_token` with the `payments` scope in order to make a business account payout. This should be included as a Bearer header along with your payout request.

### 1.2 Include headers for signing and idempotency

All requests to the Payments API v3, including payouts, should include a valid `Tl-Signature` header for security purposes. [Learn how to sign your requests](/docs/sign-your-payments-requests).

To help with payment signatures, try <a href="https://github.com/TrueLayer/truelayer-signing/tree/main" target="_blank">our signing libraries</a>.

It's also important that your requests include a valid `Idempotency-Key` header. This should be a unique key, and enables you to run your request multiple times without duplicating it.

## 2. Configure your business account payout

After setting up your `access_token` and headers, you're ready to configure and create your business account payout request.

To create a payout, send a POST request to the <a href="https://docs.truelayer.com/reference/create-payout" target="_blank">`/v3/payouts` endpoint</a>.

### 2.1 Request parameters

The table below contains an overview of all the parameters you need to specify to initiate a business account payout.

<Table>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `merchant_account_id`
      </td>

      <td>
        The unique `id` of the merchant account to make the business account payout from.
      </td>
    </tr>

    <tr>
      <td>
        `amount_in_minor`
      </td>

      <td>
        The value of the payout in a minor denomination.

        A minor denomination is the smallest unit of the specified currency, so 1 is equivalent to a penny or a cent.
      </td>
    </tr>

    <tr>
      <td>
        `currency`
      </td>

      <td>
        The currency of the payment, provided as a 3-letter ISO 4217 currency code. For example, `GBP` for pounds, or `EUR` for euros.

        The currency of your linked business account must match your merchant account.
      </td>
    </tr>

    <tr>
      <td>
        `beneficiary.type`
      </td>

      <td>
        This must be set to `business_account` for a business account payout.
      </td>
    </tr>

    <tr>
      <td>
        `beneficiary.reference`
      </td>

      <td>
        A reference for the payout.

        You see this reference alongside this payout on your statement or banking app.
      </td>
    </tr>

    <tr>
      <td>
        `metadata`
      </td>

      <td>
        This parameter is optional.

        You can include up to 10 key-value pairs in this object. This is typically used to attach metadata that helps you reconcile your payout.
      </td>
    </tr>
  </tbody>
</Table>

### 2.2 Merchant account `id`

Include the `id` of the merchant account you want to pay out from in your request. You include it in the `merchant_account_id` parameter. This ensures that you make the payout from the correct account.

The business account you want to pay must be linked to this merchant account.

You can get the `id` to use in `merchant_account_id` through two methods:

* Use the <a href="https://docs.truelayer.com/reference/list-operating-accounts" target="_blank">`/v3/merchant-accounts` endpoint</a> to return a list of your merchant accounts.
* Open the <a href="https://console.truelayer.com/payments/v3/merchant-account" target="_blank">**Merchant Account** page</a> in Console, select the correct currency, then open the **Details** tab.

This is an example of the `merchant_account_id` parameter filled out correctly:

```json merchant_account_id example
{  
	"merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51",  
//...  
}
```

### 2.3 Payout amount and currency

When you make a business account payout, you must specify the value and currency of the payout.

To specify the value of your payout, provide a numeric value for the `amount_in_minor` parameter. This should be the value of your payout in a minor denomination. This means that a value of 1500 corresponds to 15 GBP or 15 EUR.

To specify the currency of your payout, provide a <a href="https://en.wikipedia.org/wiki/ISO_4217" target="_blank">three-letter ISO 4217 currency code</a> for the `currency` parameter. For example:

* GBP for pounds sterling
* EUR for euros.

This an example of the `amount_in_minor` and `currency` parameters filled out correctly:

```json amount_in_minor and currency example
{
//...
	"amount_in_minor": 1500,
	"currency": "GBP",
//...
}
```

### 2.4 Payout scheme selection

You can select a payment scheme for your payout to be made through by using the `scheme_selection` object. Unlike creating a payment, the `scheme_selection` object for payouts is not contained within a provider selection object.

There are three different values that you can set for scheme selection:

#### `instant_preferred`

Preferably selects a payment scheme that supports instant payments for the currency and geography that you're making the payment in. However, the API will fall back to a non-instant scheme if instant payments are unavailable. The `payout_executed` webhook will specify the actual scheme used. This is optimal when you don't mind if a payout settles slowly, and can help you avoid fees and payment failures.

#### `instant_only`

Automatically selects a payment scheme that supports instant payments for the currency and geography that you're making the payment in. This type is optimal when you need payments to settle quickly.

#### `preselected`

Selects a payment scheme compatible with the currency of the payment and geographic region that you are paying in. This is useful if you want full control over the scheme that a payout goes through.

When you use a preselected scheme, you need to specify a `scheme_id`. Ensure that your scheme ID is compatible with the currency that you are using. Possible scheme IDs are:

* `faster_payments_service`
* `sepa_credit_transfer_instant`
* `sepa_credit_transfer`

See this code block for examples of each scheme selection type.

```json instant_preferred example
{
  //[...]
	"scheme_selection": {
		"type" : "instant_preferred"
	}
}
```
```json instant_only example
{
  //[...]
	"scheme_selection": {
		"type" : "instant_only"
	}
}
```
```json preselected example
{
  //[...]
	"scheme_selection": {
		"type" : "preselected",
		"scheme_id": "polish_domestic_express"
	}
}
```

We recommend using `instant_preferred` or `instant_only` for the best user experience.

#### <€100,000 payouts

Payouts that are €100,000 or over automatically move through the **SEPA Credit** scheme.

The payout appears as normal in the payments view on Console, with SEPA Credit displayed as the scheme.

Do not use the `instant_only` scheme selection object for these payments, as they will immediately fail.

### 2.5 Beneficiary details

For a business account payout, the beneficiary object is simpler than for other types of payout. You need to provide values for two parameters: `type` and `reference`. This is because the account being paid can only be the business account linked to the merchant account the payout is from.

#### 2.5.1 `type` parameter

In a business account payout, you must use a value of `business_account` for the `type` parameter.

You can use a value of `payment_source` or `external_account` for a [closed-loop payout](/docs/make-a-payout-to-an-account-that-paid-in) or [open-loop payout](/docs/make-a-payout-to-an-external-account) respectively.

#### 2.5.2 `reference` parameter

Include a string for the reference parameter in your payout. This reference appears alongside the payout in your statement or banking app.

A common approach to take is to programmatically generate a reference that starts with a string that identifies your business. Then attach a number to it, which you and your user can use to reconcile the payout if needed.

We recommend that you keep your reference under 18 characters, and include no special characters other than `-` or `.`.

### 2.6 Optional metadata

You don't need to include any values for the `metadata` object. However, if your business needs to include extra metadata in your payout requests (for internal processes for example), you can choose to include up to 10 key value pairs.

To include metadata, provide key value pairs in the object in the format below:

```json metadata parameter example
{
//...
  "metadata": {
    "Metadata_key_1": "Metadata_value_1",
    "Metadata_key_2": "Metadata_value_2",
    "Metadata_key_3": "Metadata_value_3"
  }
}
```

## Business account payout example request

When you specify the mandatory parameters above in your request, you can initiate a business account payout.

The code block below contains an example of a business account payout request:

```json Business account payout request example
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": "business_account",
		"reference": "ma-withdrawal-172",
		},
	}
}
```

Below is an example of the response to a successful request, including the payout `id`:

```json Example business account payout response
{  
  "id": "769bd377-dc7f-4e55-a04b-848f2dcb42ec"  
}
```

## 3. Monitor your business account payout

When you make a successful business account payout, you receive a response that contains the payout `id` only:

```json Example closed-loop payout response
{
	"id": "393c24a8-bfae-47b8-884d-66534bf3f6fd"
}
```

You also receive a webhook when you make payout is executed, which contains extra information.

You can use the `id` and webhook you receive to confirm whether your payout was successful, and take action if needed.

### Payout webhooks

We recommend that you use webhooks to monitor all of the requests you make with the Payments API v3. You receive webhooks for all events in your integration.

Webhooks for your integration are sent to the Webhook URI you have set on the [**Payments > Settings** page](/docs/payments-settings) in Console. You should ensure that you have [set up request signing for your webhook notifications](/docs/configure-webhooks-for-your-integration) to ensure that they are reliable and not from external sources.

The two webhooks that you receive for a business account payout are [`payout_executed`](/docs/payout-webhooks#payout_executed-2) or [`payout_failed`](/docs/payout-webhooks#payout_failed-2). You should receive these very soon after your payout request.

This is an example of a `payout_executed` webhook for a business account payout:

```json payout_executed webhook
{
  "type": "payout_executed",
  "event_id": "66eb019a-f103-4c0f-ae2e-c4a9f3bcb82d",
  "event_version": 1,
  "payout_id": "796cab79-cd1a-4e01-8241-93ac28bf4260",
  "executed_at": "2024-01-17T12:09:54.117Z",
  "beneficiary": {
    "type": "business_account"
  },
  "scheme_id": "internal_transfer"
}
```
```json payout_failed webhook
{
  "type": "payout_failed",
  "event_id": "24089aed-4fd4-9e13-f8b2-f458f30c836c",
  "event_version": 1,
  "payout_id": "0a495e9f-2f41-4669-ba33-85407c0b26cb",
  "failed_at": "2024-01-12T14:56:05.117850644Z",
  "failure_reason": "insufficient_funds",
  "beneficiary": {
    "type": "business_account"
  },
}
```

### GET payouts endpoint

You can use the payout `id` you received when you made the payout to get information about it.

To do so, make a POST request to the <a href="https://docs.truelayer.com/reference/get-payout" target="_blank">`/v3/payouts/{id}` endpoint</a>, including the payout `id` as a path parameter.

You receive a response in this format:

```json /v3/payouts/{id} endpoint response business account example
{
  "id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "merchant_account_id": "AB8FA060-3F1B-4AE8-9692-4AA3131020D0",
  "amount_in_minor": 0,
  "currency": "GBP",
  "beneficiary": {
    "type": "business_account",
    "reference": "string",
  },
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "scheme_id": "faster_payments_service",
  "status": "pending",
  "created_at": "string"
}
```

The `status` object is especially important, as you can use this to check the progression of your payout through its lifecycle.

## Payout lifecycle

After you create a payout, it moves through a series of different states depending on its outcome. See the [full list of payout statuses](/docs/payout-and-refund-statuses) for more information.

This is the journey a payout usually follows:

1. When a payout is first made, it has a status of `pending` before authorisation starts.
2. After the payout has been authorised, it has a status of `authorized`.<br />It usually takes just a few seconds for a successful payout to transition through the `pending` and `authorized` statuses.
3. Depending on whether the payment scheme executes the payout, it transitions to one of two statuses:
   1. `payout_executed` if the payout was successful.
   2. `payout_failed` if the payout could not be executed.

If a payout fails, the webhook contains a [`failure_reason` that you can use to identify why it failed](/docs/payout-and-refund-statuses#payout-failure-reasons).

### [Payout returns](/docs/payout-and-refund-returns)

A return occurs when a payout or refund is executed, but rejected by a banking provider. The money moves back to your merchant account.

<Image src="https://files.readme.io/315b948-payout_and_refund_return_flow.png" alt="payout returns (light)" align="center" />

![payout returns (dark)](https://files.readme.io/69e33f7844eb5baba8580c13b58f32325f864e254984919c8254d71f01f3d1e9-payout_and_refund_return_flow_dark.svg)

<br />

The reasons for a return are decided by banks. For example, if the account you're attempting to pay has been closed by the bank, or is under investigation.

This occurs in less than 0.01% of payouts, but you must make sure that your system can handle a payout transitioning from `executed` to `failed`.