> ## 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.

# 退款

## 事件列表

| **事件名称** | **事件类型**             | **触发时机** | **通知数据结构**                      |
| :------- | :------------------- | :------- | :------------------------------ |
| 退款成功     | v2.refunds.succeeded | 退款成功时    | [Refund](/zh/api/refund-object) |
| 退款失败     | v2.refunds.failed    | 退款失败时    | [Refund](/zh/api/refund-object) |

## 事件对象

| **属性**          | **类型**               | **描述**                                                       |
| --------------- | -------------------- | ------------------------------------------------------------ |
| access\_no      | string               | 分配的接入方编号                                                     |
| merchant\_id    | string               | 接入方的商户号                                                      |
| refund\_id      | string               | 退款单 ID                                                       |
| trade\_id       | string               | 交易单 ID                                                       |
| currency        | string               | 金额对应的交易币种                                                    |
| reason          | string               | 退款原因                                                         |
| refund\_amount  | string               | 退款金额                                                         |
| refund\_status  | string               | 退款状态<br />pending: 处理中<br />failed：退款失败<br />succeeded: 退款成功 |
| metadata        | map\<string, string> | 透传的元数据，key 长度不超过 40 字节，value 长度不超过 500 字节，JSON编码后 ≤ 1024字节   |
| failure\_reason | string               | 失败原因                                                         |
| ref\_arn        | string               | 发卡行侧返回退款凭证                                                   |
| finished\_at    | string               | 退款完成时间                                                       |

## 示例数据

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