Responding to disputes using the API
Learn how to manage disputes programmatically.
While we recommend most users respond to disputes through the Dashboard, you can programmatically manage disputes using the API. You can be notified of dispute events using webhooks, upload evidence, and respond to disputes. Retrieve a Dispute
object to find out more about it:
curl https://api.stripe.com/v1/disputes/dp_lcLtl7LsmT3jJhwlPUgE \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
# Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' dispute = Stripe::Dispute.retrieve('dp_lcLtl7LsmT3jJhwlPUgE')
# Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' dispute = stripe.Dispute.retrieve('dp_lcLtl7LsmT3jJhwlPUgE')
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); $dispute = \Stripe\Dispute::retrieve('dp_lcLtl7LsmT3jJhwlPUgE');
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; Dispute dispute = Dispute.retrieve("dp_lcLtl7LsmT3jJhwlPUgE");
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); const dispute = await stripe.disputes.retrieve('dp_lcLtl7LsmT3jJhwlPUgE');
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" dis, _ := dispute.Get("dp_lcLtl7LsmT3jJhwlPUgE", nil)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var service = new DisputeService(); var dispute = service.Get("dp_lcLtl7LsmT3jJhwlPUgE");
The response contains information about the dispute and any response or evidence that has already been provided.
{ object: "dispute" id: "dp_lcLtl7LsmT3jJhwlPUgE", 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 submit structured evidence within the evidence
parameter.
curl https://api.stripe.com/v1/disputes/dp_lcLtl7LsmT3jJhwlPUgE \ -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \ -d "evidence[customer_email_address]"="email@example.com" \ -d "evidence[shipping_date]"=2020-03-24 \ -d "evidence[shipping_documentation]"=file_IT2q8otZkBvOnAU2qNTg
# Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' Stripe::Dispute.update( 'dp_lcLtl7LsmT3jJhwlPUgE', { evidence: { customer_email_address: 'email@example.com', shipping_date: '2020-03-24', shipping_documentation: 'file_IT2q8otZkBvOnAU2qNTg', }, } )
# Set your secret key. Remember to switch to your live secret key in production! # See your keys here: https://dashboard.stripe.com/account/apikeys stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc' stripe.Dispute.modify( 'dp_lcLtl7LsmT3jJhwlPUgE', evidence={ 'customer_email_address': 'email@example.com', 'shipping_date': '2020-03-24', 'shipping_documentation': 'file_IT2q8otZkBvOnAU2qNTg', }, )
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys \Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); \Stripe\Dispute::update( 'dp_lcLtl7LsmT3jJhwlPUgE', [ 'evidence' => [ 'customer_email_address' => 'email@example.com', 'shipping_date' => '2020-03-24', 'shipping_documentation' => 'file_IT2q8otZkBvOnAU2qNTg', ], ] );
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; Dispute dispute = Dispute.retrieve("dp_lcLtl7LsmT3jJhwlPUgE"); DisputeUpdateParams params = DisputeUpdateParams.builder() .setEvidence( DisputeUpdateParams.Evidence.builder() .setCustomerEmailAddress("email@example.com") .setShippingDate("2020-03-24") .setShippingDocumentation("file_IT2q8otZkBvOnAU2qNTg") .build()) .build(); dispute.update(params);
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc'); const dispute = await stripe.disputes.update( 'dp_lcLtl7LsmT3jJhwlPUgE', { evidence: { customer_email_address: 'email@example.com', shipping_date: '2020-03-24', shipping_documentation: 'file_IT2q8otZkBvOnAU2qNTg', }, } );
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc" params := &stripe.DisputeParams{ Evidence: &stripe.DisputeEvidenceParams{ CustomerEmailAddress: stripe.String("email@example.com"), ShippingDate: stripe.String("2020-03-24"), ShippingDocumentation: stripe.String("file_IT2q8otZkBvOnAU2qNTg"), }, } dis, _ := dispute.Update("dp_lcLtl7LsmT3jJhwlPUgE", params)
// Set your secret key. Remember to switch to your live secret key in production! // See your keys here: https://dashboard.stripe.com/account/apikeys StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"; var options = new DisputeUpdateOptions { Evidence = new DisputeEvidenceOptions { CustomerEmailAddress = "email@example.com", ShippingDate = "2020-03-24", ServiceDocumentation = "file_IT2q8otZkBvOnAU2qNTg", }, }; var service = new DisputeService(); var dispute = service.Update("dp_lcLtl7LsmT3jJhwlPUgE", options);
All available fields for the evidence
parameter are found by looking at the Dispute evidence object. There are two types of evidence you can provide, depending on the field being updated:
- Text-based evidence, such as
customer_email
andservice_date
. These types of evidence take a string of text. - File-based evidence, such as
service_documentation
andcustomer_communication
. These take a file_upload object ID.
You can provide documents or images (e.g., 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 which you can use when submitting evidence. Before uploading a file as dispute evidence, make sure that it meets our recommendations to ensure readability is preserved.
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, we strongly recommend filling in as many fields as possible so you have the best chance at overturning a dispute.
Next steps
Now that you have learned how to manage disputes programmatically, you may want to learn more about the different reasons for disputes, or move on to related subjects:
If you require assistance with a dispute, please contact Stripe support.