> ## 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 | v2.refunds.succeeded | When a refund is successfully processed. | [Refund](/en/webhook/refund-2) |
| Refund Failed | v2.refunds.failed | When an attempt to process a refund fails. | [Refund](/en/webhook/refund-2) |

## 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 v2.refunds.succeeded theme={null}
  {
      "id": "572683623191290916",
      "type": "v2.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 v2.refunds.failed theme={null}
  {
      "id": "550627286320154211",
      "type": "v2.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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.