Payout webhook specifications

Payment API v3 will send webhooks for two among all the statuses in the lifecycle of a payout - Executed and Failed. For more information about statuses, please refer to the payouts statues 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	Unique event UUID
`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
`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`, `bacs`, `chaps`, `internal_transfer`, `sepa_credit_transfer` or `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	Unique event UUID
`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. In case of `invalid_scan` failure_reason please retry with the iban.
`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 payment source

When the payout is made to a payment source. This is also called a "close-loop" payout.

payout_executed

Field	Type	Description
`type`	string	Type of the event. In this case, it would be: `payout_executed`
`event_id`	string	Unique event UUID
`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.
`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`, `bacs`, `chaps`, `internal_transfer`, `sepa_credit_transfer` or `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",
  "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	Unique event UUID
`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
`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	Unique event UUID
`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`
`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`, `bacs`, `chaps`, `internal_transfer`, `sepa_credit_transfer` or `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",
  "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	Unique event UUID
`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"
  }
}