When to use payouts

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

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

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

Payout statues transitionsPayout statues transitions

Payout statues transitions


Did this page help you?