跳至內容

瀏覽文件

指南API 參考
用 AI 建置
訂單生命週期退款

退款

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

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

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

概述

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

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

退款生命週期

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

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

退款狀態值

退款可以有以下狀態：

  • pending：退款已發起並正在處理中
  • failed：退款嘗試失敗
流程圖
流程圖
100%
捲動瀏覽 · 放大查看細節

建立退款

要發起退款，請向退款端點發送包含訂單 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 權杖進行認證：

Code
Authorization: Bearer secret_test_YOUR_KEY_HERE