Payout webhooks

The Payments API sends webhooks for two of the statuses in the lifecycle of a payout: executed and failed. Learn about the other payout statuses, pending and authorized.

There are three different ways to specify the beneficiary of a payout: payouts to a payment source, payouts to an external account, and payouts to a business account. This guide includes webhook examples for payouts to each beneficiary type.

Payout to payment source webhooks

Also called a closed-loop payout.

payout_executed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_executed`
`event_id`	string	The UUID of that specific event.
`event_version`	number	Version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`executed_at`	string	Timestamp of the event, in ISO8601 format
`beneficiary.type`	string	Value would be `payment_source`. This indicates that the payout is made to the `payment_source`.
`beneficiary.payment_source_id`	string	ID of the external account which has become a payment source.
`beneficiary.user_id`	string	ID of the user that owns the external account.
`scheme_id`	string	The id of the scheme used to execute the payout. Values are: - `unknown` - `faster_payments_service` - `internal_transfer` - `sepa_credit_transfer` - `sepa_credit_transfer_instant`
`merchant_account_id`	string	The merchant account the payout was made from.
`current_balance_in_minor`	number	The current balance of the merchant account in minor.
`available_balance_in_minor`	number	The available balance of the merchant account in minor.
`metadata`	string	Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a maximum key length of 40 characters and a maximum value length of 500 characters.

{
  "type": "payout_executed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "beneficiary": {
    "type": "payment_source",
    "payment_source_id": "4a59c822-3bfb-42ba-9202-b6d89988a195",
    "user_id": "a0977be8-c406-4f75-bb81-b5ca0689b29b",
  },
  "scheme_id": "faster_payments_service",
}

payout_failed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_failed`
`event_id`	string	The UUID of that specific event
`event_version`	number	The version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`failed_at`	string	Timestamp of the event, in ISO8601 format
`failure_reason`	string	The reason of the payout failure
`beneficiary.type`	string	Value would be `payment_source`. This indicates that the payout is made to the `payment_source`.
`beneficiary.payment_source_id`	string	ID of the external account which has become a payment source.
`beneficiary.user_id`	string	ID of the user that owns the external account.
`merchant_account_id`	string	The merchant account the payout was made from.
`current_balance_in_minor`	number	The current balance of the merchant account in minor.
`available_balance_in_minor`	number	The available balance of the merchant account in minor.
`metadata`	string	Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a maximum key length of 40 characters and a maximum value length of 500 characters.

{
  "type": "payout_failed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_reason": "insufficient_funds",
  "beneficiary": {
    "type": "payment_source",
    "payment_source_id": "9ac7ab1f-6229-47db-9e17-81072d2dbdf3",
    "user_id": "9775a22c-23c7-41c8-9e7c-1508997db9c0",
  }
}

Payout to an external account webhooks

When you make a payout to an external account with its own specified account identifiers. This is also called an open-loop payout.

payout_executed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_executed`
`event_id`	string	The UUID of that specific event
`event_version`	number	The version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`executed_at`	datetime	Timestamp of the event, in ISO8601 format
`beneficiary.type`	string	Value will be `external_account`
`scheme_id`	string	The id of the scheme used to execute the payout. Values are: - `unknown` - `faster_payments_service` - `internal_transfer` - `sepa_credit_transfer` - `sepa_credit_transfer_instant`

payout_failed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_failed`
`event_id`	string	The UUID of that specific event
`event_version`	number	The version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`failed_at`	string	Timestamp of the event, in ISO8601 format
`failure_reason`	string	The reason of the payout failure
`beneficiary.type`	string	Value will be `external_account`
`merchant_account_id`	string	The merchant account the payout was made from.
`current_balance_in_minor`	number	The current balance of the merchant account in minor.
`available_balance_in_minor`	number	The available balance of the merchant account in minor.
`metadata`	string	Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a maximum key length of 40 characters and a maximum value length of 500 characters.

{
  "type": "payout_executed",
  "event_version": 1,
  "event_id": "66eb019a-f103-4c0f-ae2e-c4a9f3bcb82d",
  "payout_id": "796cab79-cd1a-4e01-8241-93ac28bf4260",
  "executed_at": "2024-01-17T12:09:54.117Z",
  "beneficiary": {
    "type": "external_account"
  },
  "scheme_id": "internal_transfer"
}

{
  "type": "payout_failed",
  "event_version": 1,
  "event_id": "24089aed-4fd4-9e13-f8b2-f458f30c836c",
  "payout_id": "0a495e9f-2f41-4669-ba33-85407c0b26cb",
  "failed_at": "2024-01-12T14:56:05.117850644Z",
  "failure_reason": "insufficient_funds",
  "beneficiary": {
    "type": "external_account"
  }
}

Verified payout webhooks

Webhooks for a verified payout contain more information.

payout_executed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_executed`
`event_id`	string	The UUID for that specific event
`event_version`	number	Version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`executed_at`	string	Timestamp of the event, in ISO8601 format
`merchant_account_id`	string	The merchant account the payout was made from.
`current_balance_in_minor`	number	The current balance of the merchant account in minor.
`available_balance_in_minor`	number	The available balance of the merchant account in minor.
`metadata`	string	Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a maximum key length of 40 characters and a maximum value length of 500 characters.
`beneficiary.type`	string	The type of bank account you're paying out to. Can be `external_account`, `payment_source`, `user_determined` or `business_account`.
`beneficiary.user.id`	string	A UUID that represents the user.
`beneficiary.provider_id`	string	The `provider_id` that represents the bank the payout is being made to.
`beneficiary.account_holder_name`	string	The name of the beneficiary.
`beneficiary.account_identifiers.type`	string	Can be `sort_code_account_number` or `iban`.
`scheme_id`	string	The id of the scheme used to execute the payout. Values are: - `unknown` - `faster_payments_service` - `internal_transfer` - `sepa_credit_transfer` - `sepa_credit_transfer_instant`

{
  "type": "payout_executed",
  "event_id": "cc7095af-8238-e04f-944f-5eebc5254d0e",
  "event_version": 1,
  "payout_id": "033d656f-989a-43a5-8dad-954005167857",
  "executed_at": "2025-05-28T13:51:38.335373Z",
  "beneficiary": {
    "type": "user_determined",
    "user": {
      "id": "e0442cbf-dd4f-4539-ab4f-3abfd0822f76"
    },
    "provider_id": "ob-hsbc",
    "account_holder_name": "John Test",
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "010101",
        "account_number": "01234567"
      },
      {
        "type": "iban",
        "iban": "GB29NWBK60161331926819"
      }
    ]
  },
  "scheme_id": "faster_payments_service"
}

payout_failed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_failed`
`event_id`	string	The UUID of that specific event
`event_version`	number	Version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`failed_at`	string	Timestamp of the event, in ISO8601 format
`failure_reason`	string	The reason of the payout failure
`merchant_account_id`	string	The merchant account the payout was made from.
`current_balance_in_minor`	number	The current balance of the merchant account in minor.
`available_balance_in_minor`	number	The available balance of the merchant account in minor.
`metadata`	string	Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a maximum key length of 40 characters and a maximum value length of 500 characters.

{
  "type": "payout_failed",
  "event_version": 1,
  "event_id": "f8a144dc-a550-4681-844b-4de231ec3764",
  "payout_id": "f8a144dc-a550-4681-844b-4de231ec3764",
  "failed_at": "2022-09-14T16:41:21.006718283Z",
  "failure_reason": "insufficient_funds",
  "beneficiary": {
    "type": "user_determined",
    "account_holder_name": "John Doe",
    "account_identifier": {
      "type": "sort_code_account_number",
      "sort_code": "040075",
      "account_number": "58114637"
    }
  },
  "merchant_account_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
  "current_balance_in_minor": 500000,
  "available_balance_in_minor": 450000,
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  }
}

Payout to a business account

When you make a payout to the linked business account you specified during your onboarding with TrueLayer.

payout_executed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_executed`
`event_id`	string	The UUID of that specific event.
`event_version`	number	Version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`executed_at`	string	Timestamp of the event, in ISO8601 format
`beneficiary.type`	string	Value would be `business_account`
`scheme_id`	string	The id of the scheme used to execute the payout. Values are: - `unknown` - `faster_payments_service` - `internal_transfer` - `sepa_credit_transfer` - `sepa_credit_transfer_instant`
`merchant_account_id`	string	The merchant account the payout was made from.
`current_balance_in_minor`	number	The current balance of the merchant account in minor.
`available_balance_in_minor`	number	The avilable balance of the merchant account in minor.
`metadata`	string	Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a maximum key length of 40 characters and a maximum value length of 500 characters.

{
  "type": "payout_executed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "beneficiary": {
    "type": "business_account"
  },
  "scheme_id": "faster_payments_service",
}

payout_failed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_failed`
`event_id`	string	The UUID of that specific event.
`event_version`	number	Version of the event
`payout_id`	string	UUID of the payout for which the webhook is being sent
`failed_at`	string	Timestamp of the event, in ISO8601 format
`beneficiary.type`	string	Value would be `business_account`.
`merchant_account_id`	string	The merchant account the payout was made from.
`current_balance_in_minor`	number	The current balance of the merchant account in minor.
`available_balance_in_minor`	number	The available balance of the merchant account in minor.
`metadata`	string	Optional field for adding custom key-value data to a resource. This object can contain a maximum of 10 key-value pairs, each with a maximum key length of 40 characters and a maximum value length of 500 characters.

{
  "type": "payout_failed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "beneficiary": {
    "type": "business_account"
  }
}

{
  "type": "payout_failed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "beneficiary": {
    "type": "business_account"
  }
}