> This page is for Afterpay Online Developer, version Chinese.
> For other versions, use one of these documentation indexes:
> - Main (default): https://developers.afterpay.com/afterpay-online-developer/main/llms.txt
> - v1: https://developers.afterpay.com/afterpay-online-developer/v-1/llms.txt
> - Chinese: https://developers.afterpay.com/afterpay-online-developer/chinese/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.afterpay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server.

# 争议概述

## 端到端争议流程

端到端争议流程概述如下：

1. Afterpay 收到客户的争议。
2. Afterpay 以程序化方式通知商户，并提供明确的争议原因代码。
3. 商户通过不同方法（可能包括 API、电子邮件、Business Hub 等）收到争议已开启的通知。
4. 商户通过 API 或 Business Hub 接受争议或提交证据。
5. Afterpay 评估证据，并通过 webhook 通知商户争议是胜诉或败诉。
6. Afterpay 通过消费者门户、电子邮件等方式通知客户争议已解决。

### **商户端争议生命周期图**

![商户端争议生命周期图](/_fern-img/0ad7b3ec12c8ef9d8b9193f3daf0058c520fa606eac8b35f61ae3ed4b89fe238.webp)

### **商户端争议 API 集成图**

![商户端争议 API 集成图](/_fern-img/31634aab56e3afeda8a713ce23bf8e28b78144152cea9f6d16f70dc625e54259.webp)

## API 端点概述

下表列出了提供给商户的 API。

> **Info**
>
> Afterpay 争议 API 使用[基本 HTTP 认证](https://en.wikipedia.org/wiki/Basic_access_authentication)，与其他 Afterpay 在线 API 端点相同。商户可以使用与其他端点相同的凭证。

| 端点                                                       | 类型   | 描述                               |
| -------------------------------------------------------- | ---- | -------------------------------- |
| [获取争议](Dispute-Open.md#get-dispute---endpoint)           | GET  | 使商户能够根据争议 ID 获取单个争议的状态信息。        |
| [接受争议](Dispute-Accept.md#accepting-a-dispute)            | POST | 使商户能够接受争议。在这些情况下，争议状态应显示为**失去**。 |
| [回应争议](Dispute-Accept.md#respond-to-the-dispute)（例如提交证据） | POST | 使商户能够提交证据或回应争议。                  |
| [列出争议](Dispute-Open.md#retrieving-disputes)              | GET  | 商户可以获取包括争议 ID 和最后修改日期的争议列表。      |
| [上传文件](Disputes-Retrieve.md#uploading-files)             | POST | 商户可以上传用于回应争议的文件（证据）。             |
| [获取文件](Disputes-Retrieve.md#retrieving-files)            | GET  | 商户可以使用文件 ID 获取文件。                |

## 争议通知

当创建争议以及每次更新时，Afterpay 都会通过 webhook 通知商户。Afterpay 期望收到带有 200 响应的 ACK（确认）。如果确认失败，Afterpay 将以指数退避方式重试几次发送 webhook。

下表概述了 webhook 调用的内容：

| 字段名称                 | 数据类型   | 描述                                           |
| -------------------- | ------ | -------------------------------------------- |
| `webhook_event_id`   | String | webhook 的 `event_id`。                        |
| `webhook_event_type` | String | 表示争议是创建还是更新的枚举变量。可能的值是 `created` 和 `updated` |
| `dispute_id`         | String | 争议标识符。                                       |
| `merchant_reference` | String | 商户标识符。                                       |

webhook 调用中会传递 `dispute_id`。商户可以使用[获取争议](Dispute-Open.md#get-dispute---endpoint)端点获取争议的详细信息。

### 通知设置

商户必须向 Afterpay 商户服务/争议团队提供 webhook URL 和商户 ID，以获取 HMAC 密钥并启用通知。

webhook 端点应由商户或合作伙伴维护，它应允许 `content-type` = `application/json` 的 POST 请求。

> **Info**
>
> 负载格式在前面的表格中定义。

### 通知认证

* （选项 1）密钥交换 Wiki：[通过 Openssl 的 Diffie-Hellman 密钥交换：快速指南](Disputes-Retrieve.md#key-exchange)
* （选项 2）从 [https://squareup.sendsafely.com/](https://squareup.sendsafely.com/) 安全获取 HMAC 密钥

### HMAC 签名

Afterpay 建议您使用 HMAC 进行 webhook 通知的认证。
考虑以下原始 HTTP 消息的结构。

```javascript
POST ${notification_uri} HTTP/1.1
Host: ${notification_base_url}
X-Afterpay-Request-Date: 1664239810
X-Afterpay-Request-Signature: ${signature}
Content-Type: application/json
{
    "webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe",
    "webhook_event_type": "created",
    "dispute_id": "dp_KvGaECApCMdsH8earUSa2V",
    "merchant_reference": "08CF65ZSFNHVM"
}
```

将有两个额外的字段用于认证。

* `X-Afterpay-Request-Date` 记录 webhook 请求的发送时间。我们建议在固定时间后中止过期通知（如果您收到 webhook 且当前时间戳 - `${X-Afterpay-Request-Date}` 大于 5 分钟）。
* `X-Afterpay-Request-Signature` 记录 HMAC 密钥的签名。通常我们使用以下步骤生成签名：

  ```javascript
  PAYLOAD={"webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe", "webhook_event_type":       "created", "dispute_id": "dp_KvGaECApCMdsH8earUSa2V", "merchant_reference": "08CF65ZSFNHVM"}
  URL= "${partner_notification_uri}"
  SECRET=<hmac secret key here>
  TIME=1664239810
  MESSAGE="$URL\n$TIME\n$PAYLOAD"
  X-Afterpay-Request-Signature=$(printf "${MESSAGE}" | openssl dgst -hmac ${SECRET} -sha256   -binary | base64)
  ```

当商户或商户代理收到 webhook 通知时，我们建议按以下步骤生成验证签名。

> **Info**
>
> 如果 `HMAC == X-Afterpay-Request-Signature`，则继续处理通知，否则商户应中止请求。

```javascript
PAYLOAD={"webhook_event_id": "b4df2187-4090-4845-be15-a73546107cbe", "webhook_event_type": "created", "dispute_id": "dp_KvGaECApCMdsH8earUSa2V", "merchant_reference": "08CF65ZSFNHVM"}
URL= "${Notification_uri}"
SECRET=<hmac secret key here>
TIME=${X-Afterpay-Request-Date}
MESSAGE="$URL\n$TIME\n$PAYLOAD"
HMAC=$(printf "${MESSAGE}" | openssl dgst -hmac ${SECRET} -sha256 -binary | base64)
```

## 争议决定和结束

### 争议取消

取消的争议（例如，可能因错误而开启并必须撤回的争议）可以以 `customer_cancelled` 作为 `closing_reason` 结束。

> **Info**
>
> 所有争议记录都保存在 Afterpay 系统中，并可通过争议 API 访问，我们不会删除任何争议记录。

### 结算和报告

在财务报告中，争议将有单独的记录。记录中包括订单 ID、争议 ID、财务变化（+/-）。

> **Afterpay 仅在商户争议败诉的情况下才会向商户收取相关款项。**