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 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 |
---|---|
| The payout has been created with TrueLayer's API but it has not yet been authorized and sent to the payment scheme for execution. |
| The payout has been created via TrueLayer's API and has been sent to the payment scheme for execution. |
| The payout was executed. The payout amount has been deduced from your Merchant Account. |
| The payout failed. The payout amount has not been deduced from your Merchant Account. |
Status transition diagram


Payout statues transitions
Updated about 1 month ago