---
title: "爭議"
description: "瞭解如何透過 Tokenz 的爭議通知來處理付款爭議。"
source: "https://docs.tokenz.one/zh-TW/v1/disputes"
api_version: "v1"
locale: "zh-TW"
version_status: "legacy"
docs_stage: "prod"
---

# 爭議

瞭解如何透過 Tokenz 的爭議通知來處理付款爭議。

當客戶向銀行或發卡機構對某筆付款提出爭議時，Tokenz 會建立爭議記錄並透過 Webhook 通知您。瞭解爭議的處理流程並即時回應，有助於提高勝訴的機會。

## 概述

爭議系統提供以下功能：

- **即時通知**：在爭議開啟或關閉時，收到 Webhook 事件通知
- **爭議詳情**：查看爭議金額、原因和舉證截止時間
- **結果追蹤**：追蹤爭議的處理進度與最終結果

## 爭議流程

爭議會依照以下流程進行：

1. **爭議建立**：客戶或其銀行針對某筆付款提出爭議
2. **舉證期間**：您可以在 `evidenceDueBy` 截止日前，透過[配送登錄 API](https://docs.tokenz.one/zh-TW/v1/order#delivery-registration-api) 提交配送記錄作為證據
3. **爭議關閉**：銀行或發卡機構做出最終裁決，爭議隨即關閉

### 爭議狀態值

爭議可能的狀態如下：

- `created`：爭議已成立，等待處理
- `underReview`：證據已提交，銀行或發卡機構審核中。處於此狀態時，再提交的配送記錄將不會送交銀行或發卡機構
- `lost`：判定結果對客戶有利，款項已退還給客戶
- `won`：判定結果對商家有利，不會扣款

### 爭議結果值

當爭議關閉時，`outcome` 欄位會顯示最終結果：

- `lost`：銀行判定對客戶有利
- `won`：銀行判定對商家有利

```mermaid
sequenceDiagram;
autonumber;
participant C as 銀行／發卡機構;
participant T as Tokenz;
participant M as 商家應用程式;
C->>T: 客戶提出爭議;
T->>M: Webhook: dispute.created;
Note over T: 暫扣訂單金額;
Note over M: 查看爭議詳情;
Note over M: 提交配送記錄;
C->>T: 銀行發出最終裁決;
T->>M: Webhook: dispute.closed;
Note over T: 解除暫扣;
Note over T: 調整撥款（如敗訴）;
Note over M: 確認結果（勝訴／敗訴）;
```

## 爭議 Webhook

設定 Webhook 來接收爭議事件通知。Tokenz 會在爭議建立和關閉時發送 Webhook 事件。

### `dispute.created`

當您的訂單收到新的爭議時觸發：

```json
{
  "id": "d4584e9a-2734-4e32-8d3d-3db675ed329a",
  "object": "dispute.created",
  "createdAt": "2026-02-13T14:01:50Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v1",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "orderReference": "test-1770991267025",
        "amount": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "fraudulent",
        "status": "created",
        "createdAt": "2026-02-13T14:01:50.158Z",
        "evidenceDueBy": "2026-02-13T14:02:50.158Z",
        "updatedAt": "2026-02-13T14:01:50.158Z"
      }
    }
  }
}
```

### `dispute.closed`

當爭議結案時觸發。可透過 `outcome` 欄位來判斷勝訴或敗訴：

```json
{
  "id": "aa8ac3b5-6021-4d32-8fde-da600bcf3374",
  "object": "dispute.closed",
  "createdAt": "2026-02-13T14:03:09Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v1",
    "data": {
      "dispute": {
        "id": "dispute_2CjCzaPskfh",
        "object": "dispute",
        "orderId": "order_2CjCq5NEAXR",
        "orderReference": "test-1770991267025",
        "amount": {
          "amount": 1000,
          "currency": "USD"
        },
        "reason": "fraudulent",
        "status": "lost",
        "outcome": "lost",
        "createdAt": "2026-02-13T14:01:50.158Z",
        "evidenceDueBy": "2026-02-13T14:02:50.158Z",
        "updatedAt": "2026-02-13T14:03:09.220Z",
        "closedAt": "2026-02-13T14:03:09.220Z"
      }
    }
  }
}
```

## 爭議事件欄位

### 事件欄位

- `id`：Webhook 事件的唯一識別碼（UUID）
- `object`：事件類型（`dispute.created` 或 `dispute.closed`）
- `createdAt`：事件建立時間（RFC3339 / ISO 8601）
- `test`：是否為測試模式下產生的事件

### 爭議物件欄位

- `id`：爭議的唯一識別碼
- `object`：固定為 `"dispute"`
- `orderId`：有爭議訂單 ID
- `orderReference`：您的爭議訂單的參考編號
- `amount`：以消費者付款幣別計算的爭議金額


    - `amount`：最小貨幣單位的金額（例如美分）
    - `currency`：ISO 4217 貨幣代碼（例如 `USD`、`JPY`）
- `reason`：爭議原因，常見值包括：


    - `fraudulent`：客戶表示交易未經授權
    - `duplicate`：客戶表示被重複收費
    - `product_not_received`：客戶表示未收到商品或服務
    - `product_unacceptable`：客戶表示商品或服務有瑕疵或與描述不符
    - `unrecognized`：客戶表示不認識此筆收費
    - `general`：一般或未分類的爭議原因
- `status`：目前爭議狀態（`created`、`underReview`、`lost` 或 `won`）
- `outcome`：爭議關閉後的最終結果（`lost` 或 `won`），僅在 `dispute.closed` 事件中出現
- `createdAt`：爭議建立時間（ISO 8601）
- `evidenceDueBy`：舉證截止時間（ISO 8601）
- `updatedAt`：最後更新時間（ISO 8601）
- `closedAt`：爭議關閉時間（ISO 8601），僅在 `dispute.closed` 事件中出現

## 爭議測試

您可以在測試模式下模擬爭議，驗證您的爭議整合流程，不會影響實際資金。測試爭議可在正式上線前確認 Webhook 處理邏輯是否正確。請注意，測試爭議僅能針對[成功的測試信用卡付款](https://docs.tokenz.one/zh-TW/v1/checkout/testing#%E5%AE%8C%E6%88%90%E4%B8%80%E6%AC%A1%E6%88%90%E5%8A%9F%E7%9A%84%E6%B8%AC%E8%A9%A6%E6%94%AF%E4%BB%98)進行操作。

### 爭議測試的運作方式

當您完成一筆測試信用卡付款時，可以指定**測試爭議結果**，系統將自動針對該筆訂單模擬爭議。爭議會走完整個流程，並向您設定的端點發送真實的 Webhook 事件：

1. **授權**：完成一筆**成功的**測試信用卡付款，並將測試爭議結果設為**勝訴**或**敗訴**
2. **爭議建立**：數秒後，系統會針對該訂單建立爭議，並發送 `dispute.created` Webhook。訂單的爭議狀態會變更為 `disputed`
3. **爭議關閉**：再過數秒後，爭議會依您選擇的結果結案，並發送 `dispute.closed` Webhook。訂單的爭議狀態會變更為 `disputeWon` 或 `disputeLost`

### 觸發測試爭議

完成一筆**成功的**測試結帳付款並選擇爭議結果後，您將收到與上方[爭議 Webhook](https://docs.tokenz.one/zh-TW/v1/disputes#%E7%88%AD%E8%AD%B0-webhook) 章節範例一致的 Webhook。請利用這些 Webhook 來驗證您的整合是否正確處理 `dispute.created` 和 `dispute.closed` 事件。

|   |   |
| --- | --- |
| ![](https://docs.tokenz.one/docs/dispute_result_won.png) | ![](https://docs.tokenz.one/docs/dispute_result_lost.png) |

### 測試爭議結果

| 測試爭議結果 | `dispute.closed` 狀態 | `dispute.closed` 結果 | 說明 |
| --- | --- | --- | --- |
| **勝訴** | `won` | `won` | 模擬爭議判定對您有利的結果 |
| **敗訴** | `lost` | `lost` | 模擬爭議判定對客戶有利的結果 |

> 測試爭議 Webhook 僅會發送至您設定的**測試** Webhook 端點。請確保已設定測試 Webhook 端點以接收這些事件。