Payout webhook specifications
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
. For more information about statuses, please refer to the payouts statuses page.
As there are a few ways to specify the beneficiary of a payout, this guide dedicates a section for each beneficiary type so dedicated request examples can be provided.
Payout to an external account
When the payout is made 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. |
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 the payout failed. Read more about payout failure reasons. |
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",
}
Closed-loop payout
When the payout is made to an account that has already paid in, also called a payment source
.
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 |
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. |
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 a business account
When the payout is made to the business account you've specified during your KYC process 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 |
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 . |
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 2 months ago