> 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.

# 接收和获取争议

在本节中，您可以了解：

* [接收争议](#接收争议)
* [获取争议](#获取争议)

当客户开启争议时，Afterpay 将调用带有 `webhook_event_type = created` 的 webhook。
商户可以使用下面的**获取争议**端点获取争议的详细信息。

## 接收争议

### 获取争议 - 端点

GET https\://\{afterpay\_global\_url}/v2/disputes/\{dispute\_id}

#### 连接超时

| 超时类型    | 时间（秒） |
| ------- | ----- |
| `OPEN`  | 10    |
| `Read ` | 20    |

#### 请求头

| 头部           | 类型     | 示例                                                                                                                   |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `User-Agent` | String | `MyAfterpayModule/1.0.0 (E-Commerce Platform Name/1.0.0; PHP/7.0.0; Merchant/60032000) https://merchant.example.com` |

| 头部       | 类型     | 默认值              |
| -------- | ------ | ---------------- |
| `Accept` | String | application/json |

#### 请求参数

| 字段名称          | 数据类型   | 描述        |
| ------------- | ------ | --------- |
| `dispute_id ` | String | （必需）争议标识符 |

#### 响应

| 字段名称      | 数据类型          | 描述      |
| --------- | ------------- | ------- |
| `dispute` | DisputeObject | 更新的争议对象 |

#### 争议对象

| 字段名称                     | 数据类型                                                          | 描述                                                                               |
| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `id`                     | String                                                        | 争议标识符                                                                            |
| `order`                  | String                                                        | 争议所针对的订单令牌                                                                       |
| `amount`                 | String                                                        | 争议金额（示例：40.13）                                                                   |
| `currency`               | String                                                        | 争议货币（ISO-4217 标准，示例：AUD）                                                         |
| `reason`                 | String                                                        | 争议原因。请参见下面的[争议原因](#争议原因)部分建议。                                                    |
| `status`                 | String                                                        | 争议的当前状态。值取决于争议状态机的建模方式。请参见下面的[争议状态](#争议状态)部分建议。                                  |
| `open`                   | Boolean                                                       | 如果尚未对争议做出最终决定，则为 `True`。                                                         |
| `responseDueBy`          | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\))      | 商户必须对此争议作出响应的截止日期。（以秒为单位的纪元时间戳，时区：UTC +0:00）                                     |
| `createdAt`              | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\))      | 表示争议创建时间的时间戳。（以秒为单位的纪元时间戳，时区：UTC +0:00）                                          |
| `openingNote`            | String                                                        | 客户描述开启争议原因或投诉原因的文本。虽然争议类别代码有助于告知商户应该提供什么，但它不提供客户投诉背后的原因。在某些情况下，这可以帮助商户直接与客户解决争议。 |
| `openingNoteAttachments` | FileId                                                        | 补充 `openingNote` 的附件。如果客户在描述争议原因时提供了照片或截图                                        |
| `updatedAt`              | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\)) (可选) | 争议更新的时间戳。（以秒为单位的纪元时间戳，时区：UTC +0:00）                                              |
| `closingReason`          | String                                                        | 表示如何达成争议最终决定的原因。建议的可能值列在下面的[结束原因](#结束原因)中。                                       |
| `closingNote`            | String (可选)                                                   | 详细描述如何达成争议最终决定的文本。这补充了 `closingReason`。                                          |
| `merchantOrderId`        | String                                                        | 商户端的交易标识符。                                                                       |
| `transactionDate`        | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\))      | 客户创建订单的时间戳。（以秒为单位的纪元时间戳，时区：UTC +0:00）                                            |
| `settlementAmount`       | String                                                        | 用于审计的结算金额。                                                                       |
| `meta`                   | MetaObject (可选)                                               | 供商户匹配支付的额外信息。                                                                    |

#### Meta 对象

| 字段名称                 | 数据类型        | 描述                                |
| -------------------- | ----------- | --------------------------------- |
| `transactionAmount`  | String      | 订单的交易金额。                          |
| `network`            | String (可选) | 客户使用的支付网络。（通常是 Visa 或 MasterCard） |
| `networkReferenceId` | String(可选)  | 支付的标识符。（对于店内支付，此字段存在）             |
| `orderType`          | String      | 订单类型，应为 `ONLINE` 或 `INSTORE`。     |

#### 争议对象示例

| 字段名称                     | 数据类型                                                          | 示例                                                         |
| ------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------- |
| `id`                     | String                                                        | dp\_N64jYg4RC4ZBUsXjLzE3W5                                 |
| `order`                  | String                                                        | 123456789                                                  |
| `amount`                 | String                                                        | 48.46                                                      |
| `currency`               | String                                                        | AUD                                                        |
| `reason `                | String                                                        | fraudulent                                                 |
| `status`                 | String                                                        | won                                                        |
| `open`                   | Boolean                                                       | false                                                      |
| `responseDueBy`          | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\))      | 1691884800                                                 |
| `createdAt`              | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\))      | 1691884800                                                 |
| `openingNote`            | String                                                        | Customer has no knowledge of the Payment.                  |
| `openingNoteAttachments` | FileId                                                        | \["fi\_48vmw3sXdVqvtJGXbgKbAZ"]                            |
| `updatedAt`              | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\)) (可选) | 1691884800                                                 |
| `closingReason`          | String                                                        | merchant\_accepted                                         |
| `closingNote`            | String (可选)                                                   | Merchant accepted the dispute.                             |
| `merchantOrderId`        | String                                                        | merchantorderid12345                                       |
| `transactionDate`        | [时间戳](https://en.wikipedia.org/wiki/Epoch_\(computing\))      | 1691884800                                                 |
| `settlementAmount`       | String                                                        | 48.46                                                      |
| `meta`                   | MetaObject (可选)                                               |   `"transactionAmount": "48.46"`,  `"orderType":"ONLINE"`  |

### 争议状态

Afterpay 支持以下争议状态：

> **Info**
>
> 我们在第一个版本中不支持 `partially_won` 状态，但计划在未来支持它。

| 状态                  | 描述                                        |
| ------------------- | ----------------------------------------- |
| `needs_response`    | Afterpay 已创建争议并通知商户，但商户尚未采取行动。            |
| `under_review`      | 商户已向 Afterpay 提交证据，目前正在审查中。               |
| `partially_won`     | 如果最终争议解决金额小于原始争议金额，则表示商户部分赢得争议。注意，这是一个终态。 |
| `won`               | 提交的证据被 Afterpay 接受，商户赢得争议。注意，这是一个终态。      |
| `lost`              | 提交的证据被 Afterpay 拒绝，商户失去争议。注意，这是一个终态。      |
| `merchant_refunded` | 商户已发起退款。如果退款金额等于或大于争议金额，则这是一个终态。          |
| `merchant_voided`   | 商户已取消全部或部分订单。如果取消金额等于或大于争议金额，则这是一个终态。     |

## 争议窗口

Afterpay 将根据争议窗口时间框架更新争议状态并触发争议通知。以下是行使和辩护拒付的时间框架（以日历天为单位）：

| 摘要            | 描述                                    |       |
| ------------- | ------------------------------------- | ----- |
| 争议开启窗口        | 可以开启争议的最大时间窗口（从交易日期起），超过此时间客户将无法发起争议。 | 120 天 |
| 商户证据提交窗口      | 从商户收到争议通知到最终提交证据的允许时间。                | 13 天  |
| Afterpay 决定窗口 | 从提交证据时刻到 Afterpay 做出最终决定的允许时间。        | 30 天  |

### 争议原因

当触发争议时，总会有一个争议原因。以下是争议 API 当前将响应和支持的争议原因：

> **Info**
>
> Afterpay 的争议原因目前仅限于 `product_not_received`，我们计划在未来更新这一点。Cash App Pay 的争议系统已完全实施，包含所有原因，包括卡网络拒付。

| 商户端争议原因                | 活动                              | 描述                                        |
| ---------------------- | ------------------------------- | ----------------------------------------- |
| `product_not_received` | Afterpay / Cash App Pay         | 客户声称他们没有收到购买的产品或服务。                       |
| `product_unacceptable` | Afterpay (Q4 发布) / Cash App pay | 收到了产品或服务，但有缺陷、损坏或与描述不符。                   |
| `credit_not_processed` | Afterpay (Q4 发布) / Cash App pay | 客户声称已退回购买的产品或交易已取消，但商户尚未提供退款或退款。          |
| `order_canceled`       | Cash App pay                    | 商品/服务已取消。                                 |
| `duplicate`            | Cash App pay                    | 客户声称他们被多次收取相同产品或服务的费用。                    |
| `incorrect_amount`     | Cash App pay                    | 支付金额与约定金额不符。                              |
| `paid_by_other_means`  | Cash App pay                    | 客户通过其他支付方式支付。                             |
| `fraudulent`           | Cash App pay                    | 客户声称他们没有授权支付。                             |
| `fraudulent_merchant`  | Cash App pay                    | 客户对支付没有认知，且由于共谋、欺诈监控程序阈值或任何其他原因，责任已转移给商户。 |

## 结束原因

向商户显示表明如何达成争议最终决定的结束原因。以下是结束原因及其描述：

| 商户端结束原因              | 描述                            |
| -------------------- | ----------------------------- |
| `merchant_accepted`  | 商户接受了争议。                      |
| `evidence_accepted`  | 商户提交的证据被接受，争议以商户胜诉结束。         |
| `evidence_rejected`  | 商户提交了证据但被拒绝，争议以客户胜诉结束。        |
| `deadline_expired`   | 商户未能为争议提交证据，提交窗口超时。争议以客户胜诉结束。 |
| `customer_cancelled` | 客户撤回了争议，因此以商户胜诉结束。            |

## 获取争议

### 列出争议 - 端点

根据特定条件列出某个日期范围内的争议。如果您无法使用 webhook 方法，此端点可用于调试或从 Afterpay 同步争议。

```
GET https://{afterpay_global_url}/v2/disputes
```

#### 连接超时

| 超时类型    | 时间（秒） |
| ------- | ----- |
| `OPEN`  | 10    |
| `Read ` | 20    |

#### 请求头

| 头部           | 类型     | 示例                                                                                                                   |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `User-Agent` | String | `MyAfterpayModule/1.0.0 (E-Commerce Platform Name/1.0.0; PHP/7.0.0; Merchant/60032000) https://merchant.example.com` |

| 头部       | 类型     | 默认值              |
| -------- | ------ | ---------------- |
| `Accept` | String | application/json |

#### 请求参数

| 字段名称           | 数据类型    | 描述                                                                                                 |
| -------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `order`        | Integer | 可用于筛选列表的支付或订单令牌。                                                                                   |
| `merchant`     | String  | 可用于筛选列表的商户令牌。                                                                                      |
| `status`       | String  | 可用于筛选列表的争议状态。                                                                                      |
| `openedAfter`  | 时间戳     | 筛选在此时间戳当天或之后创建的争议（包含）。                                                                             |
| `openedBefore` | 时间戳     | 筛选在此时间戳当天或之前创建的争议（包含）。                                                                             |
| `offset`       | Integer | 搜索结果的偏移量。示例：Offset = 0，limit = 10 意味着我们将显示前十个争议。Offset = 10，limit = 10 意味着我们将显示搜索结果中编号为 10-20 的争议。 |
| `limit`        | Integer | 您希望从此请求返回的最大记录数。                                                                                   |

#### 响应

| 字段名称     | 数据类型                  | 描述                                                                                                 |
| -------- | --------------------- | -------------------------------------------------------------------------------------------------- |
| `data`   | Array (DisputeObject) | 符合请求中筛选条件的争议对象数组。                                                                                  |
| `offset` | Integer               | 搜索结果的偏移量。示例：Offset = 0，limit = 10 意味着我们将显示前十个争议。Offset = 10，limit = 10 意味着我们将显示搜索结果中编号为 10-20 的争议。 |
| `limit`  | Integer               | 您希望从此请求返回的最大记录数。                                                                                   |
| `total`  | Integer               | 搜索条件中的总争议记录数。                                                                                      |

#### 响应示例

| 字段名称     | 数据类型                  | 示例         |
| -------- | --------------------- | ---------- |
| `data`   | Array (DisputeObject) | 见下面的数据示例代码 |
| `offset` | Integer               | 0          |
| `limit`  | Integer               | 1          |
| `total`  | Integer               | 1          |

#### 数据示例代码

```json
[
  {
    "id": "dp_N64jYg4RC4ZBUsXjLzE3W5",
    "order": "12312312312",
    "amount": "48.46",
    "currency": "AUD",
    "status": "won",
    "reason": "fraudulent",
    "open": false,
    "responseDueBy": -1,
    "openingNote": "Cash dispute: Customer has no knowledge of the Payment.",
    "openingNoteAttachments": [],
    "merchantOrderId": "12312312312",
    "transactionDate": 1690836227,
    "createdAt": 1691884800,
    "updatedAt": 1692067909,
    "meta": {
              "transactionAmount": "48.46",
              "orderType": "ONLINE"
            }
  }
]
```