Payout webhooks

Set up webhooks to get updates on payouts from Payments API v3

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

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

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

{
  "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.

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

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.

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

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

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.

{
  "type": "payout_failed",
  "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"
  }
}

Did this page help you?