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

When you make a payout to a payment source. This is 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 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.
`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_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "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": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payout_id": "0cd1b0f7-71bc-4d24-b209-95259dadcc20",
  "failed_at": "2021-12-25T15:00:00.000Z",
  "failure_reason": "scheme_error",
}

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