# 退款接口

> 创建退款与查询退款。卡类退款为全额退款，且需审核后完成。

## 创建退款

`POST /api/v1/refunds/create`

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `original_order_no` | string | 二选一 | 原 HansaPay 系统支付订单号 |
| `original_merchant_order_no` | string | 二选一 | 原商户支付订单号 |
| `merchant_refund_no` | string | 是 | 商户退款单号，最长 64 个字符 |
| `refund_amount` | string | 是 | 退款金额，币种与原订单一致 |
| `reason` | string | 否 | 退款原因 |
| `notify_url` | string | 否 | 退款通知地址。不传则不发送退款通知 |
| `metadata` | string | 否 | 商户透传参数，在退款通知中回传 |

说明：

- 卡、Apple Pay 与 Google Pay 支付仅支持一次全额退款。部分金额会被拒绝，返回 `This payment channel does not support partial refunds; only full refunds are allowed`
- 此类退款初始为 `PENDING`，审核后才完成；HansaPay 每隔几分钟检查一次，完成后发送 `refund.updated`。30 分钟后上游仍无记录的退款会变为 `FAILED`
- Cash App 退款支持部分退款。退款先为 `PENDING`，通道确认后完成（通常在几分钟内），完成时 HansaPay 会发送 `refund.updated`
- 退款处理中时，退款金额与退款手续费会从可用余额中冻结，失败则解冻。余额不足以覆盖时，退款会被拒绝
- 被拒绝的退款同样占用其 `merchant_refund_no`；被拒绝的退款记录为 `FAILED`
- 退款状态：`PENDING` / `SUCCESS` / `FAILED`

### 成功 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `refund_no` | string | HansaPay 系统退款单号 |
| `merchant_refund_no` | string | 商户退款单号 |
| `original_order_no` | string | 原 HansaPay 系统订单号 |
| `original_merchant_order_no` | string | 原商户订单号 |
| `status` | string | 退款状态 |
| `refund_amount` | object | 退款金额 |
| `created_at` | string | 创建时间 |

### 完整成功响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202406240001",
    "merchant_refund_no": "MR202406240001",
    "original_order_no": "O202406240001",
    "original_merchant_order_no": "M202406240001",
    "status": "PENDING",
    "refund_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "created_at": "2026-06-24T11:00:00+08:00"
  }
}
```

## 查询退款

`POST /api/v1/refunds/query`

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `refund_no` | string | 二选一 | HansaPay 系统退款单号 |
| `merchant_refund_no` | string | 二选一 | 商户退款单号 |

### 成功 `data`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `refund_no` | string | HansaPay 系统退款单号 |
| `merchant_refund_no` | string | 商户退款单号 |
| `original_order_no` | string | 原 HansaPay 系统订单号 |
| `original_merchant_order_no` | string | 原商户订单号 |
| `status` | string | 退款状态 |
| `refund_amount` | object | 退款金额 |
| `reason` | string | 退款原因 |
| `created_at` | string | 创建时间 |
| `updated_at` | string | 更新时间 |

### 完整成功响应示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202406240001",
    "merchant_refund_no": "MR202406240001",
    "original_order_no": "O202406240001",
    "original_merchant_order_no": "M202406240001",
    "status": "SUCCESS",
    "refund_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "reason": "customer requested",
    "created_at": "2026-06-24T11:00:00+08:00",
    "updated_at": "2026-06-24T11:00:05+08:00"
  }
}
```
