When to use payouts

Payouts represents 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.

Payout to an 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.

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"
    }
}

Payout to an external account

You can also make payouts to your own bank account by using the beneficiary type external_account with relevant details.

merchant account flows for documentation - Payout to client.jpg

POST /payouts
{
    "merchant_account_id": "d4a7572a-6a4a-440f-bca0-0db8e9859567",
    "amount_in_minor": 1,
    "currency": "GBP",
    "beneficiary": {
        "type": "external_account",
        "account_holder_name": "Flavio Butler Zanin",
        "account_identifier": {
            "type": "sort_code_account_number",
            "sort_code": "00-00-00",
            "account_number": "12345678",
        },
        "reference": "winnings"
    }
}

Payout 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, as 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