---
title: "退款"
description: "了解如何通过 Tokenz 退款 API 处理已完成付款的退款。"
source: "https://docs.tokenz.one/zh-CN/v1/refunds"
api_version: "v1"
locale: "zh-CN"
version_status: "legacy"
docs_stage: "prod"
---

# 退款

了解如何通过 Tokenz 退款 API 处理已完成付款的退款。

退款 API 允许您为已完成的订单向客户退还资金。您可以发起退款、跟踪退款状态并管理退款生命周期。

**金额格式：** API 中所有货币值（如 `amount` 字段）均以各货币的最小单位表示。请参阅[支持的货币](https://docs.tokenz.one/zh-CN/v1/checkout/currency)了解每种货币的确切编码。

## 概述

退款系统提供退款管理功能：

- **退款创建**：为已完成的订单发起指定原因的退款
- **状态跟踪**：通过 pending 或 failed 状态监控退款进度
- **审计追踪**：跟踪谁发起了退款以及何时发起
- **测试模式**：完整的测试环境支持用于开发和测试

## 退款生命周期

退款经历定义的生命周期：

1. **退款发起**：商户或 API 为已完成的订单发起退款
2. **处理中**：退款异步处理（状态保持为 `pending`）
3. **失败**：如果出现问题，退款可能失败（状态变为 `failed`）

### 退款状态值

退款可以有以下状态：

- `pending`：退款已发起并正在处理中
- `failed`：退款尝试失败

```mermaid
sequenceDiagram;
autonumber;
participant M as 商户应用;
participant T as Tokenz API;
%% 退款创建流程;
M->>T: POST /v1/refunds (发起退款);
T->>T: 验证订单和金额;
T-->>M: 返回退款 (状态: pending);
T->>T: 异步处理退款;
T->>M: Webhook 通知 (created/failed);
```

## 创建退款

要发起退款，请向退款端点发送包含订单 ID 和退款原因的 POST 请求：

```bash
curl --request POST \
  --url https://api.tokenz.one/v1/refunds \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --data '{
    "orderId": "order_1p4LPTRKB5Z",
    "reason": "customer_cancellation",
    "detail": "Customer requested cancellation"
  }'
```

### 必需参数

- `orderId`：要退款的订单 ID（必须是已完成的订单）
- `reason`：退款原因。有效值：


    - `customer_cancellation`：客户取消了订单
    - `duplicate_payment`：付款重复
    - `other`：其他原因（需要 `detail` 字段）
- `detail`：可选的详细说明（当 reason 为 `other` 时必需）

### 响应

成功创建退款返回退款对象：

```json
{
  "refund": {
    "id": "refund_1p4LS47fB1h",
    "object": "refund",
    "orderId": "order_1p4LPTRKB5Z",
    "amount": {
      "amount": 10000,
      "currency": "JPY"
    },
    "status": "pending",
    "reason": "customer_cancellation",
    "initiatedBy": "apikey",
    "test": false,
    "createdAt": "2024-10-07T10:30:00Z",
    "updatedAt": "2024-10-07T10:30:00Z"
  }
}
```

## 获取退款

获取特定退款的当前状态和详细信息：

```bash
curl --request GET \
  --url https://api.tokenz.one/v1/refunds/refund_1p4LS47fB1h \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'
```

### 响应字段

- `id`：退款的唯一标识符
- `orderId`：退款订单的 ID
- `amount`：以最小货币单位表示的退款金额
- `status`：当前退款状态（pending、failed）
- `reason`：提供的退款原因
- `initiatedBy`：谁发起了退款（merchantUser、apikey、admin）
- `test`：这是否为测试退款
- `createdAt`：创建退款的时间戳
- `updatedAt`：最后状态更新的时间戳

## 列出退款

使用可选过滤器列出所有退款：

```bash
curl --request GET \
  --url 'https://api.tokenz.one/v1/refunds?orderId=order_1p4LPTRKB5Z&limit=10' \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'
```

### 查询参数

- `orderId`：按订单 ID 过滤退款
- `status`：按退款状态过滤（pending、failed）
- `limit`：返回的最大退款数（1-100，默认：10）
- `createdAfter`：过滤在此时间戳之后创建的退款（ISO 8601）
- `createdBefore`：过滤在此时间戳之前创建的退款（ISO 8601）

### 响应

```json
{
  "refunds": {
    "items": [
      {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "status": "pending",
        "reason": "customer_cancellation",
        "initiatedBy": "apikey",
        "test": false,
        "createdAt": "2024-10-07T10:30:00Z",
        "updatedAt": "2024-10-07T10:30:00Z"
      }
    ],
    "hasMore": false
  }
}
```

## 退款 Webhook

配置 webhook 以接收有关退款事件的通知：

### `refund.created`

退款创建时触发：

```json
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "object": "refund.created",
  "createdAt": "2024-10-07T10:30:00Z",
  "test": false,
  "eventData": {
    "type": "refund",
    "version": "v1",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "status": "pending",
        "reason": "customer_cancellation",
        "initiatedBy": "apikey",
        "test": false,
        "createdAt": "2024-10-07T10:30:00Z",
        "updatedAt": "2024-10-07T10:30:00Z"
      }
    }
  }
}
```

### `refund.failed`

退款失败时触发：

```json
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "object": "refund.failed",
  "createdAt": "2024-10-07T10:40:00Z",
  "test": false,
  "eventData": {
    "type": "refund",
    "version": "v1",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "status": "failed",
        "reason": "customer_cancellation",
        "initiatedBy": "apikey",
        "test": false,
        "createdAt": "2024-10-07T10:30:00Z",
        "updatedAt": "2024-10-07T10:40:00Z"
      }
    }
  }
}
```

## 错误处理

退款 API 返回标准 HTTP 状态代码和详细的错误消息：

### 常见错误

- `400 Bad Request`：无效的请求参数或格式错误的请求
- `401 Unauthorized`：无效或缺少 API 密钥
- `403 Forbidden`：执行退款的权限不足
- `404 Not Found`：未找到订单或退款
- `422 Unprocessable Entity`：业务逻辑错误

### 错误响应格式

```json
{
  "status": 422,
  "code": "refund.amount-exceeds-available",
  "message": "Refund amount exceeds available refund amount for this order"
}
```

## 测试退款

使用测试模式开发和测试您的退款集成：

1. 使用测试 API 密钥（以 `test_` 为前缀）
2. 使用测试结账会话创建测试订单
3. 测试退款的 ID 中将有 `_t` 后缀（例如 `refund_1p4LS47fB1h_t`）
4. 测试 webhook 发送到您配置的测试 webhook 端点

## API 参考

### 端点

- `POST /v1/refunds` - 创建新退款
- `GET /v1/refunds/{refundId}` - 获取特定退款
- `GET /v1/refunds` - 使用可选过滤器列出退款

### 认证

所有端点都需要通过 Bearer 令牌进行认证：

```
Authorization: Bearer secret_test_YOUR_KEY_HERE
```