# 用 API 回应争议

了解如何程序化地管理争议

您可以通过 API 以编程方式管理争议。使用 API，您可以上传证据、回应争议，并通过 Webhook 接收争议事件。

如果您想使用仪表板而不是 API 来管理争议，请参见[回应争议](https://docs.stripe.com/disputes/responding.md)。

## 检索争议

有关争议的详细信息，请[检索](https://docs.stripe.com/api/disputes/retrieve.md)`Dispute` 对象：

```curl
curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

回应中包含有关争议的信息，以及任何已提供的回应或证据。

```json
{
  object: "dispute"
  id: "{{DISPUTE_ID}}",
  charge: "ch_5Q4BjL06oPWwho",
  evidence: {
    customer_name: "Jane Austen",
    customer_purchase_ip: "127.0.0.1",
    product_description: "Widget ABC, color: red",
    shipping_tracking_number: "Z01234567890",
    uncategorized_text: "Additional notes and comments",
  },
  evidence_details: {
    due_by: 1403047735,
    submission_count: 1
  }
  ...
}
```

## 更新争议

您需[更新](https://docs.stripe.com/api/disputes/update.md) `Dispute`对象并通过 `evidence` 参数传递结构化证据。

```curl
curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "evidence[customer_email_address]=email@example.com" \
  -d "evidence[shipping_date]=2024-02-01" \
  -d "evidence[shipping_documentation]={{FILE_ID}}"
```

如需查看 `evidence` 参数的所有可用字段，请参阅[争议证据](https://docs.stripe.com/api/disputes/update.md#update_dispute-evidence)。根据待更新字段的不同，您可提供两类证据：

- 文本类型的证据，例如 `customer_email` 和 `service_date`。这类证据是一个文本字串。
- 基于文件的证据，如 `service_documentation` 和 `customer_communication`。这些证据需填写[file_upload](https://docs.stripe.com/api/files/object.md#file_object-id) 对象 ID。

> 提交的所有文本型证据字段的总字符数不得多于 150,000。

在提交争议时，可以用[文件上传 API](https://docs.stripe.com/file-upload.md) 来提供文件或图片（例如合同或截图）。您首先以 `dispute_evidence` 为目的上传一个文件，它会生成一个 `File_upload` 对象，提交证据时可以使用它。将其作为证据上传之前务必确保文件满足 [Stripe 的建议](https://docs.stripe.com/disputes/best-practices.md#file-upload-recommendations)。

如果您想只提交单个文件或文字量较大的纯文本作为证据，可以使用 `uncategorized_text` 或 `uncategorized_file`。但是，请填写尽可能多的字段，以最大限度推翻争议。

## 单笔付款的多项争议

这种情况并不常见，但客户可能会不止一次对同一笔付款提出争议。例如，如果订单中的某个商品在交付过程中发生损坏，客户可能会对该商品的付款提出部分争议，然后因为该商品不能正常使用而对同一订单中的另一个商品第二次提出争议。

Stripe 通过唯一标识符区分所有争议，即使这些争议涉及同一笔付款。当您[列出争议](https://docs.stripe.com/api/disputes/list.md) 时，您可以通过指定 `PaymentIntent` 或 `Charge` 对象的 `id`，并添加 [payment_intent](https://docs.stripe.com/api/disputes/list.md#list_disputes-payment_intent) 或 [charge](https://docs.stripe.com/api/disputes/list.md#list_disputes-charge) 过滤器来过滤结果，仅显示特定付款的争议。

#### 按 PaymentIntent

```curl
curl -G https://api.stripe.com/v1/disputes \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_intent={{PAYMENT_INTENT_ID}}
```

#### 按 Charge

```curl
curl -G https://api.stripe.com/v1/disputes \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d charge={{CHARGE_ID}}
```

当一笔付款有多项争议时，请使用列表中为每个返回的争议提供的 `id`，确保您在[检索](https://docs.stripe.com/disputes/api.md#retrieve-a-dispute)或[更新争议](https://docs.stripe.com/disputes/api.md#update-a-dispute)时通过指定其 `id` 来回应正确的争议。

## See also

- [争议类别](https://docs.stripe.com/disputes/categories.md)
- [衡量争议](https://docs.stripe.com/disputes/measuring.md)
- [预防争议和欺诈](https://docs.stripe.com/disputes/prevention.md)