退款

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

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

金額格式： API 中所有貨幣值（如 amount 欄位）均以各貨幣的最小單位表示。請參閱支援的貨幣以了解每種貨幣的確切編碼。

概述

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

退款建立：為已完成的訂單發起指定原因的退款
狀態追蹤：透過 pending 或 failed 狀態監控退款進度
稽核追蹤：追蹤誰發起了退款以及何時發起
測試模式：完整的測試環境支援用於開發和測試

退款生命週期

退款經歷定義的生命週期：

退款發起：商家或 API 為已完成的訂單發起退款
處理中：退款異步處理（狀態保持為 pending）
失敗：如果出現問題，退款可能失敗（狀態變為 failed）

退款狀態值

退款可以有以下狀態：

pending：退款已發起並正在處理中
failed：退款嘗試失敗

流程圖

建立退款

要發起退款，請向退款端點發送包含訂單 ID 和退款原因的 POST 請求：

bash

curl --request POST \
  --url https://api.tokenz.one/v2/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 時必要）

回應

成功發起退款返回 Refund 物件：

json

{
  "refund": {
    "id": "refund_1p4LS47fB1h",
    "object": "refund",
    "orderId": "order_1p4LPTRKB5Z",
    "amount": {
      "amount": 10000,
      "currency": "JPY"
    },
    "consumerAmount": {
      "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/v2/refunds/refund_1p4LS47fB1h \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

回應欄位

id：退款的唯一識別碼
orderId：退款訂單的 ID
amount：以最小貨幣單位表示的退款金額
consumerAmount：以消費者貨幣表示的退款金額（選填）
status：目前退款狀態（pending、failed）
reason：提供的退款原因
initiatedBy：誰發起了退款（merchantUser、apikey、admin）
test：這是否為測試退款
createdAt：發起退款的時間戳記
updatedAt：最後狀態更新的時間戳記

列出退款

列出所有退款。可使用選用的篩選條件以縮小結果範圍:

bash

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

查詢參數

orderId：按訂單 ID 篩選退款
status：按退款狀態篩選（pending、failed）
limit：返回的最大 Refund 物件數量（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"
        },
        "consumerAmount": {
          "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": "v2",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "consumerAmount": {
          "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": "v2",
    "data": {
      "refund": {
        "id": "refund_1p4LS47fB1h",
        "object": "refund",
        "orderId": "order_1p4LPTRKB5Z",
        "amount": {
          "amount": 10000,
          "currency": "JPY"
        },
        "consumerAmount": {
          "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"
}

測試退款

使用測試模式開發和測試您的退款整合：

使用測試 API 金鑰（以 test_ 為前綴）
使用測試結帳會話建立測試訂單
測試退款的 ID 中將有 _t 後綴（例如 refund_1p4LS47fB1h_t）
測試 webhook 發送到您配置的測試 webhook 端點

API 參考

端點

POST /v2/refunds - 建立新退款
GET /v2/refunds/{refundId} - 取得特定退款
GET /v2/refunds - 使用可選篩選器列出退款

認證

所有端點都需要透過 Bearer 權杖進行認證：

Code

Authorization: Bearer secret_test_YOUR_KEY_HERE