API を使用して不審請求の申請に対応する

API を使用して、プログラムで不審請求の申し立てを管理することができます。API を使用すると、証拠をアップロードし、不審請求の申し立てに応答し、Webhooks を使用して不審請求の申し立てイベントを受信することができます。

API を使用する代わりにダッシュボードを使用して不審請求の申し立てを管理したい場合は、不審請求の申し立てに対応する を参照してください。

不審請求の申請を取得する

不審請求の申し立ての詳細については、retrieve 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`パラメータのすべての利用可能なフィールドについては、不審請求の申し立ての証拠 を参照してください。更新される分野によって、提出できる証拠には 2 種類あります。

• customer_email や service_date などのテキストベースの反証資料。これらのタイプの反証資料は、テキストの文字列を使用します。
• service_documentation や customer_communication などのファイルベースの証拠。これらは file_upload オブジェクト ID を取ります。

File Upload API を使用して、不審請求の申請の反証資料の一部として書類や画像 (契約書やスクリーンショットなど) を提供できます。まず、dispute_evidence の目的で書類をアップロードします。これにより、反証資料を提出する際に使用できる File_upload オブジェクトが生成されます。反証資料として提出するファイルをアップロードする前に、そのファイルが Stripe の推奨事項に適合していることを確認してください。

ファイル 1 つのみ、または大量のプレーンテキストを反証資料として提出する場合は、uncategorized_text または uncategorized_file を使用します。ただし、不審請求の申請を覆す可能性を高くするために、できるだけ多くのフィールドに入力してください。

1 つの支払いに対する複数の不審請求の申請

頻繁に発生するわけではありませんが、顧客が同じ支払いに対して複数の不審請求の申請を行うことがあります。たとえば、ある注文の商品が配送中に破損していた場合、顧客はその商品の支払いに対して部分的に不審請求の申請を行い、その後、同じ注文の別の商品に対して、その商品が正常に機能しないという理由で 2 回目の不審請求の申請を行うというケースが考えられます。

Stripe では、1つの決済に関連しているかどうかにかかわらず、すべての不審請求の申し立てを一意の識別子で区別します。不審請求の申し立てリスト で、PaymentIntentまたはChargeオブジェクトの id を指定し、payment_intent または charge フィルタを含めることで、特定の決済に関する不審請求の申し立てだけを表示するように結果をフィルタリングすることができます。

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

1 つの支払いに複数の不審請求の申請がある場合、一覧で返された個々の不審請求の申請に設定された id を使用して、不審請求の申請の取得または更新時にその id を指定することで、正しい不審請求の申請に対応していることを確認します。