Submitting Dispute Evidence

To help resolve disputes in your favor, submit evidence about the legitimacy of a charge to your customer's bank or card issuer through Stripe. If you need help after reading this, check out our answers to common questions.

A dispute occurs when a customer initiates a chargeback with their bank or credit card issuer. However, a dispute can be overturned by the customer’s bank if they receive enough information showing that the chargeback isn’t justified. When the bank or issuer finds the dispute in your favor, you are refunded the disputed amount that had been withdrawn, including the chargeback fee.

What evidence to provide depends upon the type of dispute. While it’s not required that you include every piece of information to submit your evidence, providing as much evidence as you can greatly improves your chances of overturning a dispute.

There are two ways you can submit evidence to Stripe:

Using the Dashboard

You can manage disputes in the Dashboard and it’s the recommended route for most users. The Dashboard guides you through the submission process, step-by-step—automatically formatting the information you provide. You’re asked to provide different pieces of evidence and upload any necessary files, depending on the dispute type. All this works to increase the likelihood of a dispute being found in your favor.

The disputes overview page.

Responding to a dispute.

Using the API

While we do recommend handling disputes through the Dashboard, you may prefer to use the Stripe API to submit dispute evidence directly from your integration. Structured evidence is submitted using an API request to update the Dispute object, with the necessary information provided as fields within the evidence parameter.

Evidence fields

All available fields for the evidence parameter are found in the API reference. There are two types of evidence you can provide, depending on the field being updated:

  • Text evidence, such as customer_email and service_date, take a string of text
  • File evidence, such as service_documentation and customer_communication, take a file token

A file token is a unique ID that represents a document or image uploaded with the File Upload API. A document is first uploaded with the purpose of dispute_evidence, which generates a file token that you can use in the appropriate field.

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

Submitting evidence

This example updates the dispute evidence with the following evidence fields:

  • customer_email
  • shipping_date
  • shipping_documentation (a file token)
curl https://api.stripe.com/v1/disputes/dp_17sGETLpSdVJN1iVw8BHvseP \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d evidence[customer_email_address]="email@example.com" \
   -d evidence[shipping_date]=2016-11-10 \
   -d evidence[shipping_documentation]=file_17sapWLpSdVJN1iV0X1yRT8Z
# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = Stripe::Dispute.retrieve("dp_17sGETLpSdVJN1iVw8BHvseP")
dispute.evidence = {
  :customer_email_address => "email@example.com",
  :shipping_date => "2016-11-10",
  :shipping_documentation => "file_17sapWLpSdVJN1iV0X1yRT8Z"
}
dispute.save
# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

dispute = stripe.Dispute.retrieve("dp_17sGETLpSdVJN1iVw8BHvseP")
dispute.evidence = {
  "customer_email_address": 'email@example.com',
  "shipping_date": '2016-11-10',
  "shipping_documentation": 'file_17sapWLpSdVJN1iV0X1yRT8Z'
}
dispute.save()
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

$dp = \Stripe\Dispute::retrieve("dp_17sGETLpSdVJN1iVw8BHvseP");
$dp->evidence = array(
  "customer_email_address" => "email@example.com",
  "shipping_date" => "2016-11-10",
  "shipping_documentation" => "file_17sapWLpSdVJN1iV0X1yRT8Z"
);
$dp->save();
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute dp = Dispute.retrieve("dp_17sGETLpSdVJN1iVw8BHvseP");
Map<String, Object> params = new HashMap<String, Object>();
Map<String, Object> evidence = new HashMap<String, Object>();
evidence.put("customer_email_address", "email@example.com");
evidence.put("shipping_date", "2016-11-10");
evidence.put("shipping_documentation", "file_17sapWLpSdVJN1iV0X1yRT8Z");
params.put("evidence", evidence);
dp.update(params);
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.disputes.update("dp_17sGETLpSdVJN1iVw8BHvseP",
  {
    evidence: {
      customer_email_address: 'email@example.com',
      shipping_date: '2016-11-10',
      shipping_documentation: 'file_17sapWLpSdVJN1iV0X1yRT8Z'
    }
  },
  function(err, dispute) {
    // asynchronously called
  }
);
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Update("dp_17sGETLpSdVJN1iVw8BHvseP",
  &stripe.DisputeParams{
    Evidence: &stripe.DisputeEvidenceParams{
      CustomerEmail: "email@example.com",
      ShippingDate: "2016-02-24",
      ShippingDoc: "file_17sapWLpSdVJN1iV0X1yRT8Z"
    },
  },
)

Fetching evidence

The Dispute object contains information about its evidence, when it’s due, and how many submissions have been attempted. Fetch the evidence status of a disputed charge using an API request:

curl https://api.stripe.com/v1/disputes/dp_17sGETLpSdVJN1iVw8BHvseP \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2:
# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

Stripe::Dispute.retrieve("dp_17sGETLpSdVJN1iVw8BHvseP")
# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

stripe.Dispute.retrieve("dp_17sGETLpSdVJN1iVw8BHvseP")
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

\Stripe\Dispute::retrieve("dp_17sGETLpSdVJN1iVw8BHvseP");
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";

Dispute.retrieve("dp_17sGETLpSdVJN1iVw8BHvseP");
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");

stripe.disputes.retrieve("dp_17sGETLpSdVJN1iVw8BHvseP",
  function(err, dispute) {
    // asynchronously called
  }
);
// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"

d, err := dispute.Get("dp_17sGETLpSdVJN1iVw8BHvseP", nil)

The above returns the following in response:

{
  object: "dispute"
  id: "dp_17sGETLpSdVJN1iVw8BHvseP",
  charge: "ch_5Q4BjL06oPWwho",
  evidence: {
    customer_name: "Jane Austen",
    customer_email_address: "email@example.com",
    customer_purchase_ip: "127.0.0.1",
    product_description: "Widget ABC, color: red",
    shipping_date: "2016-11-10",
    shipping_tracking_number: "Z01234567890",
    uncategorized_text: "Additional notes and comments",
    uncategorized_file: "file_17sapWLpSdVJN1iV0X1yRT8Z"
  },
  evidence_details: {
    due_by: 1403047735,
    submission_count: 1
  }
  ...
}