Refund webhooks
Notifications sent to your webhook URI registered in Console, when a refund is executed or fails.
You receive a webhook notification to your webhook URI in Console when a refund reaches one of two possible states:
executedfailed
For more information about statuses, see our guide to refund statuses.
Validate webhooks
You must always verify the authenticity of incoming webhook requests. To do this, we recommend that you use the webhook signing library, allowing your application to confirm that the request originated from TrueLayer and has not been tampered with.
To allowlist TrueLayer calls, add a unique query parameter to your webhook URI for identification. For enhanced security, include a self-signed JWT token as a callback parameter, which you can then decode to verify its contents. For example: https://mywebhook.app?unique_param=x
refund_executed
The table below shows the different fields you receive in the refund_executed webhook notification:
| Field | Type | Description |
|---|---|---|
type | string | Type of the event. In this case, it would be: refund_executed |
event_id | string | Unique event UUID |
event_version | number | Version of the event |
refund_id | string | UUID of the refund for which the webhook is being sent |
payment_id | string | UUID of the payment for which the refund is for |
executed_at | string | Time of the refund execution, in ISO8601 format |
scheme_id | string | The id of the scheme used to execute the payout. Values are: faster_payments_service, sepa_credit_transfer or sepa_credit_transfer_instant. |
{
"type": "refund_executed",
"event_version": 1,
"event_id": "f6321c84-1797-4e66-acd4-d768c09f9edf",
"refund_id": "9c4952c2-efcf-442f-86d6-ee207c2a1d1d",
"payment_id": "dfb531ca-8e25-4753-bc23-0c7eeb8d4f29",
"executed_at": "2021-12-25T15:00:00.000Z",
"scheme_id": "faster_payments_service",
}
refund_failed
The following table describes the different fields you receive in the refund_failed webhook notification:
| Field | Type | Description |
|---|---|---|
type | string | Type of the event. In this case, it would be: refund_failed |
event_id | string | Unique event ID |
event_version | number | Version of the event |
refund_id | string | ID of the refund for which the webhook is being sent |
payment_id | string | ID of the original payment being refunded |
failed_at | string | The time the refund failed, in ISO8601 format |
failure_reason | string | The reason for the refund failure |
{
"type": "refund_failed",
"event_version": 1,
"event_id": "d916d958-a96a-4767-96b0-e4841780eeca",
"refund_id": "af386a24-e5e6-4508-a4e4-82d4bc4e3677",
"payment_id": "3bf64c4c-8d92-4fdc-b8c1-c1efbb4c5a9f",
"failed_at": "2021-12-25T15:00:00.000Z",
"failure_reason": "insufficient_funds"
}
Updated 9 days ago