Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
OverviewExplore all products
Start building
Start developing
Sample projects
About the APIs
Build with LLMs
Use Stripe without code
Set up Stripe
Create an account
Web Dashboard
Mobile Dashboard
Migrate to Stripe
Manage fraud risk
Understand fraud
Radar fraud protection
Manage disputes
    Overview
    How disputes work
    Handling
    Respond to disputes
    Manage disputes programmatically
      Visa Compelling Evidence 3.0
      Visa compliance
    Dispute withdrawals
    High risk merchant lists
    Analytics
    Measuring disputes
    Monitoring programs
    Optimization
    Dispute Prevention
    Smart Disputes
Verify identities
HomeGet startedManage disputes

Use the API to respond to disputes

Learn how to manage disputes programmatically.

Copy page

You can respond to disputes in the Stripe Dashboard, where we guide you through submitting the optimal evidence for each dispute reason.

You can also programmatically manage disputes using the API. With the API, you can upload evidence, respond to disputes, and receive dispute events using webhooks.

Retrieve a dispute

For details about a dispute, retrieve a Dispute object:

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

The response contains information about the dispute and any response or evidence that’s already been provided.

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

Update a dispute

You update the Dispute object and pass structured evidence with the evidence parameter.

Command Line
cURL
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}}

To view all available fields for the evidence parameter, see Dispute evidence. There are two types of evidence you can provide, depending on the field being updated:

  • Text-based evidence, such as customer_email and service_date. These types of evidence take a string of text.
  • File-based evidence, such as service_documentation and customer_communication. These take a file_upload object ID.

Note

The combined character count for all text-based evidence field submissions is limited to 150,000.

You can provide documents or images (for example, a contract or screenshot) as part of dispute evidence using the File Upload API. You first upload a document with the purpose of dispute_evidence, which generates a File_upload object that you can use when submitting evidence. Make sure the file meets Stripe’s recommendations before uploading it for evidence submission.

If you’re only interested in submitting a single file or a large amount of plaintext as evidence, use uncategorized_text or uncategorized_file. However, fill in as many fields as possible so you have the best chance at overturning a dispute.

Multiple disputes on a single payment

It’s not typical, but it’s possible for a customer to dispute the same payment more than once. For example, a customer might partially dispute a payment for one of the items in an order if it was damaged in delivery, and then file a second dispute against a different item in the same order because the item didn’t work properly.

Stripe distinguishes all disputes by a unique identifier, regardless of whether they’re related to a single payment. When you list disputes, you can filter the results to show only disputes for a particular payment by specifying the id of the PaymentIntent or Charge object and including the payment_intent filter or charge filter.

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

When a payment has multiple disputes, use the id provided for each returned dispute in the list to make sure you’re responding to the correct dispute by specifying its id when you retrieve or update the dispute.

See also

  • Dispute categories
  • Measuring disputes
  • Preventing disputes and fraud
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc