Banked provides several webhook notifications to keep you informed about the status of a refund. These webhooks allow you to track the progress of a refund from initiation to completion or failure.
This guide will explain the following:
- Refund Webhook Types: Overview of the different webhook types available.
- Refund Webhook Payloads: Detailed examples of the JSON payloads for each refund webhook type.
Refund Webhook Types
Below is a summary of the available refund webhook types:
| Webhook | Description |
|---|---|
refund_pending | Indicates that the refund has been authorized but Banked has not yet received confirmation that the refund has left the merchant's account. |
refund_sent | Indicates that the refund has left the merchant's account and is now within the payment network. |
refund_failed | Indicates that the refund was not authorized by the merchant's account. |
refund_canceled | Indicates that the refund was aborted before it could be completed. |
Each webhook includes a JSON payload with detailed information about the Refund. Refer to the sections below to view examples and learn more about each webhook type.
New to Refund Webhooks? Start with our Webhook Overview to understand how to set up and handle webhooks effectively.
Refund Webhook Payloads
All v3 refund webhook payloads share the same envelope structure:
{
"id": "<webhook-event-uuid>",
"type": "<event-type>",
"version": "v3",
"data_version": 1,
"data": { ... }
}
The data field contains the refund object. The refund status is reflected in data.status_details.status.
Refund Pending
The Refund Pending notification indicates that the Refund has yet to be concluded.
The JSON below shows an example of a refund_pending notification payload:
{
"id": "3a7e0e66-3b15-496a-8948-458a0a50488e",
"type": "refund_pending",
"version": "v3",
"data_version": 1,
"data": {
"amount": 1,
"created_at": "2025-05-22T10:26:55.815053234Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "71dd52df-b05b-41fb-9a28-16c543a1abf6"
},
"expiration": "2025-06-21T10:26:55.815054084Z",
"id": "eec4e4be-40ce-4c81-a6bc-3e24f1ad0667",
"original_payin_information": {
"amount": 10000,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"payment_identification": {
"end_to_end_identification": "end-to-end-id"
},
"remittance_information": {
"structured": {
"creditor_reference_information": {
"reference": ""
}
}
},
"status_details": {
"status": "PENDING"
},
"updated_at": "2025-05-22T10:26:55.863891998Z"
}
}
Refund Sent
The Refund Sent notification indicates that the Refund has been successfully concluded.
The JSON below shows an example of a refund_sent notification payload:
{
"id": "3a7e0e66-3b15-496a-8948-458a0a50488e",
"type": "refund_sent",
"version": "v3",
"data_version": 2,
"data": {
"amount": 1,
"created_at": "2025-05-22T10:26:55.815053234Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "71dd52df-b05b-41fb-9a28-16c543a1abf6"
},
"expiration": "2025-06-21T10:26:55.815054084Z",
"id": "eec4e4be-40ce-4c81-a6bc-3e24f1ad0667",
"original_payin_information": {
"amount": 10000,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"payment_identification": {
"end_to_end_identification": "end-to-end-id"
},
"remittance_information": {
"structured": {
"creditor_reference_information": {
"reference": ""
}
}
},
"status_details": {
"status": "SENT"
},
"updated_at": "2025-05-22T10:26:55.863891998Z"
}
}
Refund Failed
The Refund Failed notification indicates that the Refund was unsuccessful. Additional failure detail is available in status_details.reason.
The JSON below shows an example of a refund_failed notification payload:
{
"id": "7095c887-b186-4f9a-8788-2128d4ab5303",
"type": "refund_failed",
"version": "v3",
"data_version": 2,
"data": {
"amount": 1,
"created_at": "2025-05-22T10:26:55.815053234Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "71dd52df-b05b-41fb-9a28-16c543a1abf6"
},
"expiration": "2025-06-21T10:26:55.815054084Z",
"id": "eec4e4be-40ce-4c81-a6bc-3e24f1ad0667",
"mandate": {
"id": "3f80b430-4127-46f9-a86f-3ce18a02a53d"
},
"original_payin_information": {
"amount": 10000,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"payment_identification": {
"end_to_end_identification": "end-to-end-id"
},
"remittance_information": {
"structured": {
"creditor_reference_information": {
"reference": ""
}
}
},
"status_details": {
"status": "FAILED",
"reason": {
"code": "MANDATE_INELIGIBLE_AMOUNT_EXCEEDED",
"message": "Amount Requested Exceeds Mandate Limit"
}
},
"updated_at": "2025-05-22T10:26:56.086017458Z"
}
}
Refund Canceled
The Refund Canceled notification indicates that the Refund was aborted before it could be completed.
The JSON below shows an example of a refund_canceled notification payload:
{
"id": "7095c887-b186-4f9a-8788-2128d4ab5303",
"type": "refund_canceled",
"version": "v3",
"data_version": 2,
"data": {
"amount": 1,
"created_at": "2025-05-22T10:26:55.815053234Z",
"currency": "AUD",
"debtor_account": {
"account_type": "BANKED_BANK_ACCOUNT_ENTITY",
"bank_account_id": "71dd52df-b05b-41fb-9a28-16c543a1abf6"
},
"expiration": "2025-06-21T10:26:55.815054084Z",
"id": "eec4e4be-40ce-4c81-a6bc-3e24f1ad0667",
"metadata": {
"key1": "value",
"key2": "value"
},
"original_payin_information": {
"amount": 10000,
"id": "82a649c5-af14-474a-997a-b25b0d3f45be"
},
"payment_identification": {
"end_to_end_identification": "end-to-end-id"
},
"remittance_information": {
"structured": {
"creditor_reference_information": {
"reference": ""
}
}
},
"status_details": {
"status": "CANCELED",
"reason": {
"code": "PAYEE_ACTION_GRACEFUL_EXIT",
"message": "User exited the payment"
}
},
"updated_at": "2025-05-22T10:26:56.086017458Z"
}
}