用 API 回应争议

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

如果您想使用仪表板而不是 API 来管理争议，请参见回应争议。

检索争议

有关争议的详细信息，请检索 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}}

要查看 evidence 参数的所有可用字段，请参见争议证据。根据要更新的字段，您可以提供两种类型的证据：

• 文本类型的证据，例如 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 或 charge 过滤器来过滤结果，仅显示特定付款的争议。

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

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