争议

了解如何通过 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:50.158Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v2",
    "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:09.220Z",
  "test": true,
  "eventData": {
    "type": "dispute",
    "version": "v2",
    "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：事件创建时间戳（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 端点以接收这些事件。