Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Fraud detection
    Overview
    Risk evaluation
    Risk settings
    Reviews
    Lists
    Rules
    Radar Session
    Testing
    Integration
    Disputes and fraud
      How disputes work
      Responding to disputes
        Best practices
        Using the API
        Categories
      Dispute withdrawals
      Fraud prevention
      Measuring disputes
      Disputes on Connect
      Monitoring programs
      High risk merchant lists
    Analytics
Stripe data
Financial reports
Payment authentication reports
Revenue recognition
Startup incorporation
Climate
Identity
Tax
Financial Connections
Account
Dashboard
Radar
·
HomeBusiness operationsFraud detectionDisputes and fraudResponding to disputes

Responding to disputes using the API

Learn how to manage disputes programmatically.

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. For more details, retrieve a Dispute object:

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

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

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

Command Line
curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}} \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
\ -d "evidence[customer_email_address]"="email@example.com" \ -d "evidence[shipping_date]"=2/18/2023 \ -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.

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.

See also

  • Dispute categories
  • Measuring disputes
  • Preventing disputes and fraud
Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$