---
title: "争议"
description: "了解如何通过 Tokenz 争议通知处理支付争议。"
source: "https://docs.tokenz.one/zh-CN/v1/disputes"
api_version: "v1"
locale: "zh-CN"
version_status: "legacy"
docs_stage: "prod"
---

# 争议

了解如何通过 Tokenz 争议通知处理支付争议。

当客户向其银行或发卡机构对某笔支付提出异议时，Tokenz 将创建一个争议并通过 webhook 通知您。了解争议生命周期并及时响应，可以大幅提升获得有利结果的可能性。

## 概述

争议系统提供以下功能：

- **实时通知**：在争议开启或关闭时接收 webhook 事件
- **争议详情**：获取争议金额、原因及证据截止日期
- **结果追踪**：了解争议何时解决及最终结果

## 争议流程

争议按照以下流程推进：

1. **争议创建**：客户或其银行对某笔支付发起争议
2. **证据提交期**：您可在 `evidenceDueBy` 之前通过[配送登记 API](https://docs.tokenz.one/zh-CN/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: 查看结果 (won/lost);
```

## 争议 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-CN/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%B5%8B%E8%AF%95%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-CN/v1/disputes#%E4%BA%89%E8%AE%AE-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 端点以接收这些事件。