When to use payouts

Payouts represent money leaving your merchant account into a beneficiary of your choice. Unlike pay-ins via bank_transfer payment method, this action does not require extra authorisation by any user.

Pay out to a user

When one of your users requests to withdraw funds back to their account, you can facilitate this exchange by executing payouts from your merchant-account via /payouts resource.

5131 — You can call `POST /payouts` to initiate a payment with a beneficiary type `payment_source_external_account` if your user has made a payment into your `merchant account` before. You can view payment sources of a user on a merchant account via calling `GET /merchant-accounts/{id}/payment-sources?user_id={user_id}`

You can facilitate a payout to a user via a call to POST /payouts

POST /payouts
{
    "merchant_account_id": "5e26d112-d5f1-45d7-a66a-1db269155db9",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
        "type": "payment_source",
        "payment_source_id": "e2b41c9d-176k-67aa-b2da-fe1a2b97253c",
        "user_id": "6b481e48-5505-4a2d-8763-2bfc75560a9e",
        "reference": "winnings"
    }
}

Pay out to an external account

You can also make payouts to any supported bank account by using the beneficiary type external_account and submitting the relevant account details. To test a payout in sandbox, try with the IBAN GB75CLRB04066800000871.

POST /payouts
{
    "merchant_account_id": "d4a7572a-6a4a-440f-bca0-0db8e9859567",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
        "type": "external_account",
        "account_holder_name": "John Smith",
        "account_identifier": {
            "type": "iban",
            "iban": "GB75CLRB04066800000871"
        },
        "reference": "winnings"
    }
}

Pay out to a business account

You can make payouts to your business bank account that you've specified during your onboarding process with TrueLayer with beneficiary type business_account and the relevant details.

POST /payouts
{
    "merchant_account_id": "ef82b06a-f40a-4ec6-aa90-8f123a563edd",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
        "type": "business_account",
        "reference": "winnings"
    }
}

Payout statuses

A payout has four different statuses during its lifecycle, detailed below:

Status	Definition
`pending`	The payout has been created with TrueLayer's API but it has not yet been authorized and sent to the payment scheme for execution.
`authorized`	The payout has been created via TrueLayer's API and has been sent to the payment scheme for execution.
`executed`	The payout was executed. The payout amount has been deduced from your Merchant Account.
`failed`	The payout failed. The payout amount has not been deduced from your Merchant Account.

Status transition diagram