> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subotiz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refund

## Event List

| **Event Name**   | **Event Type**    | **Trigger Condition**                      | **Data Structure**             |
| :--------------- | :---------------- | :----------------------------------------- | :----------------------------- |
| Refund Succeeded | refunds.succeeded | When a refund is successfully processed.   | [Refund](/en/webhook/refund-1) |
| Refund Failed    | refunds.failed    | When an attempt to process a refund fails. | [Refund](/en/webhook/refund-1) |

## Event Object

| **Field Name**  | **Type**             | **Description**                                                                                                                                         |
| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| access\_no      | string               | Access number assigned to your platform by Subotiz                                                                                                      |
| merchant\_id    | string               | Merchant ID for your platform                                                                                                                           |
| refund\_id      | string               | Refund order ID                                                                                                                                         |
| trade\_id       | string               | Trade order ID                                                                                                                                          |
| currency        | string               | Currency of the refund amount                                                                                                                           |
| reason          | string               | Reason for initiating the refund                                                                                                                        |
| refund\_amount  | string               | Amount refunded                                                                                                                                         |
| refund\_status  | string               | Status of the refund:<br />pending: Processing<br />failed: Refund failed<br />succeeded: Refund succeeded                                              |
| metadata        | map\<string, string> | Passthrough metadata. Key length must not exceed 40 bytes, value length must not exceed 500 bytes. Total size after JSON encoding must be ≤ 1024 bytes. |
| failure\_reason | string               | Reason for the failure refund                                                                                                                           |
| ref\_arn        | string               | Acquirer Reference Number (ARN) returned by the card issuer's bank, serving as proof of refund credential on the issuer side.                           |
| finished\_at    | string               | Refund completed time                                                                                                                                   |

## Example

<CodeGroup>
  ```json refunds.succeeded theme={null}
  {
      "id": 572683623191290916,
      "type": "refunds.succeeded",
      "created": "2025-10-28T07:20:15Z",
      "data": {
          "reason": "",
          "access_no": "77d52a21dc032b4",
          "merchant_id": "2816433",
          "refund_id": "20251028572683602265931714",
          "currency": "USD",
          "failure_reason": null,
          "ref_arn": "",
          "finished_at": "2025-10-28T07:20:15Z",
          "trade_id": "572679783406649282",
          "refund_amount": "15.57",
          "refund_status": "succeeded",
          "metadata": null
      }
  }
  ```

  ```json refunds.failed theme={null}
  {
      "id": 550627286320154211,
      "type": "refunds.failed",
      "created": "2025-08-28T10:36:15Z",
      "data": {
          "access_no": "78f3c0d56803a11",
          "merchant_id": "2816411",
          "currency": "USD",
          "metadata": null,
          "failure_reason": {
              "code": "100999",
              "message": "insufficient account balance"
          },
          "ref_arn": "",
          "refund_id": "20250828550582487160487110",
          "trade_id": "549527688117761146",
          "reason": "",
          "refund_amount": "39.00",
          "refund_status": "failed",
          "finished_at": null
      }
  }
  ```
</CodeGroup>