用 API 回应争议

您可以在 Stripe 管理平台中回应争议，我们会在那里指导您提交每个争议原因的最佳证据。

您还可以用 API 程序化地管理争议。使用 API，您可以上传证据、回应争议，并用 Webhook 接收争议事件。

检索争议

有关争议的详细信息，请检索 Dispute 对象：

curl https://api.stripe.com/v1/disputes/
{{DISPUTE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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

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

更新争议

您更新 Dispute 对象，然后用 evidence 参数传递结构化的证据。

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

要查看证据参数的所有可用字段，请见争议证据。可提供的证据有两种类型，取决于更新中的字段：

• 文本类型的证据，例如 customer_email 和 service_date。这类证据是一个文本字串。
• 文件类型的证据，例如 service_documentation 和 customer_communication。这些需要一个 file_upload 对象 ID。

在提交争议时，可以用文件上传 API 来提供文件或图片（例如合同或截图）。您首先以 dispute_evidence 为目的上传一个文件，它会生成一个 File_upload 对象，提交证据时可以使用它。将其作为证据上传之前务必确保文件满足 Stripe 的建议。

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

单笔付款的多项争议

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

Stripe 通过一个唯一的标识符来区分所有争议，无论它们是否与一笔付款相关。当您列出争议时，您可以通过指定 PaymentIntent 或 Charge 对象的 id 并包含 payment_intent filter 或收款筛选器来筛选结果，以仅显示特定付款的争议。

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

当一笔付款有多项争议时，请使用列表中为每个返回的争议提供的 id，确保您在检索或更新争议时通过指定其 id 来回应正确的争议。