Payout webhooks
Payout notifications sent to your webhook URI registered in Console, when a payout becomes executed or fails.
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"
}
}
Updated 7 months ago