When to use payouts

This section details the various scenarios where a payout can be used in your business and payout status transitions.

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.

51315131

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.

46414641
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:

StatusDefinition
pendingThe payout has been created with TrueLayer's API but it has not yet been authorized and sent to the payment scheme for execution.
authorizedThe payout has been created via TrueLayer's API and has been sent to the payment scheme for execution.
executedThe payout was executed. The payout amount has been deduced from your Merchant Account.
failedThe payout failed. The payout amount has not been deduced from your Merchant Account.

Status transition diagram

16321632

Payout statues transitions