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

# 退款

了解如何透過 Tokenz 退款 API 處理已完成付款的退款。

退款 API 允許您為已完成的訂單向客戶退還資金。您可以發起退款、追蹤退款狀態並管理退款生命週期。

**金額格式：** API 中所有貨幣值（如 `amount` 欄位）均以各貨幣的最小單位表示。請參閱[支援的貨幣](https://docs.tokenz.one/zh-TW/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
```