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

evidence パラメータに使用可能なすべてのフィールドを表示するには、Dispute 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 を指定することで、正しい不審請求の申請に対応していることを確認します。