爭議

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

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

概述

爭議系統提供以下功能：

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

爭議流程

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

爭議建立：客戶或其銀行針對某筆付款提出爭議
舉證期間：您可以在 evidenceDueBy 截止日前，透過配送登錄 API 提交配送記錄作為證據
爭議關閉：銀行或發卡機構做出最終裁決，爭議隨即關閉

爭議狀態值

爭議可能的狀態如下：

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

爭議結果值

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

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

流程圖

爭議 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 處理邏輯是否正確。請注意，測試爭議僅能針對成功的測試信用卡付款進行操作。

爭議測試的運作方式

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

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

觸發測試爭議

完成一筆成功的測試結帳付款並選擇爭議結果後，您將收到與上方爭議 Webhook 章節範例一致的 Webhook。請利用這些 Webhook 來驗證您的整合是否正確處理 dispute.created 和 dispute.closed 事件。

測試爭議結果

可視需要左右捲動

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

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