Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Risk evaluation
Risk settings
Reviews
Lists
Rules
Testing
Integration
Disputes and fraud
How disputes work
Responding to disputes
Using the API
Categories
Dispute withdrawals
Fraud prevention
Measuring disputes
Disputes on Connect
Monitoring programs
High risk merchant lists
Analytics
Climate
radar
·
HomeBusiness operationsFraud detectionDisputes and fraudResponding to disputes

Responding to disputes using the API

Learn how to manage disputes programmatically.

In response to the elevated disputes faced by many merchants in the travel and entertainment industries due to COVID-19, Visa and Mastercard have issued guidelines for resolving them. These guidelines relate specifically to goods and services canceled directly due to a government order or prohibition. If your business is receiving disputes that fall into this category and you need to submit dispute evidence before the submission date, please proceed to this guide.

For all industries, the best actions you can take are to proactively communicate with your customers and issue refunds where appropriate, especially when requested.

While we recommend most users respond to disputes through the Dashboard, you can 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:

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

Terminal
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]"=4/28/2022 \ -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. A document is first uploaded 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, Stripe strongly recommends filling in as many fields as possible so you have the best chance at overturning a dispute.

If you require assistance with a dispute, please contact Stripe support.

See also

  • Dispute categories
  • Measuring disputes
  • Preventing disputes and fraud
Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
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! This is a graphical user interface of the Stripe CLI. You can use it to discover webhook events and manage your Stripe resources. By pressing ctrl + ` you can toggle it open from any page within the Stripe documentation. - View supported commands: - Listen for webhook events: - Trigger webhook events: - Call Stripe APIs: stripe [api resource] [api operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$