Create account
Sign in
Support
issuing
ยท
HomeFinancial servicesCard creation

Disputes

Learn how to dispute transactions.

The purpose of a dispute is to recover funds for transactions that have already been captured. Disputes are often used to redress fraudulent transactions or problems with the quality or delivery of the product.

Stripe offers a guided Dashboard process and an API to submit disputes and monitor them through to resolution. This process typically takes between 30 and 90 days. For users managing occasional disputes, we recommend using the Dashboard. Users that handle a high volume of disputes may find it easier to programmatically manage disputes using the API.

Considerations before initiating a dispute

Check that the transaction is eligible to be disputed.

  • The transaction must be a capture and not a refund.
  • No part of the transaction has been refunded.
  • Fewer than 110 days have passed since the transaction was captured.
  • The transaction is not an ATM transaction or mobile push payment transaction.

In the Dashboard, the Dispute transaction button will only be enabled for eligible transactions. Similarly, in the API, attempts to dispute ineligible transactions will result in an error.

Next, ensure that the cardholder has exhausted other means of resolving the issue. They must attempt to return any products they received, cancel any ongoing services, and seek a refund directly from the merchant. Collect documentation of these attempts to use as evidence when filing the dispute.

Lifecycle

Lifecycle of an Issuing dispute

Newly-created disputes begin in an unsubmitted status. At this point, their evidence and metadata can be updated. Once all the required evidence has been added, you can then submit the dispute. If a dispute isnโ€™t submitted within 110 days of the transaction clearing, it will be expired.

Disputes in the submitted status are being processed by Stripe and the card networks. As such, their evidence can no longer be updated โ€” only their metadata can be altered. When the dispute is resolved (often weeks later), Stripe transitions it into either the terminal won or lost status.

Creation

Click on Dispute transaction when viewing an eligible transaction. You will be redirected to a form which requests different information based on the dispute reason and product type (merchandise, services or digital goods). A dispute is created the first time you click Save. If you click Submit without saving, we create a dispute before submitting it.

Use the Create method by specifying the transaction you wish to dispute. You must also specify an evidence object whose reason determines its other fields. In these example, observe that not_received is populated because reason takes the value โ€œnot_receivedโ€.

curl https://api.stripe.com/v1/issuing/disputes \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d transaction=ipi_1GW0GkKA9rkJS7vmeJlLI1Gp \
  -d "evidence[reason]"=not_received \
  -d "evidence[not_received][expected_at]"=1590000000 \
  -d "evidence[not_received][explanation]"="Never shipped" \
  -d "evidence[not_received][product_description]"="Baseball bat" \
  -d "evidence[not_received][product_type]"=merchandise

stripe issuing disputes create \
  -d transaction=ipi_1GW0GkKA9rkJS7vmeJlLI1Gp \
  -d "evidence[reason]"=not_received \
  -d "evidence[not_received][expected_at]"=1590000000 \
  -d "evidence[not_received][explanation]"="Never shipped" \
  -d "evidence[not_received][product_description]"="Baseball bat" \
  -d "evidence[not_received][product_type]"=merchandise

# 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::Issuing::Dispute.create({
  transaction: 'ipi_1GW0GkKA9rkJS7vmeJlLI1Gp',
  evidence: {
    reason: 'not_received',
    not_received: {
      expected_at: 1590000000,
      explanation: 'Never shipped',
      product_description: 'Baseball bat',
      product_type: 'merchandise',
    },
  },
})

# 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.issuing.Dispute.create(
  transaction="ipi_1GW0GkKA9rkJS7vmeJlLI1Gp",
  evidence={
    "reason": "not_received",
    "not_received": {
      "expected_at": 1590000000,
      "explanation": "Never shipped",
      "product_description": "Baseball bat",
      "product_type": "merchandise",
    },
  },
)

// 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\Issuing\Dispute::create([
  'transaction' => 'ipi_1GW0GkKA9rkJS7vmeJlLI1Gp',
  'evidence' => [
    'reason' => 'not_received',
    'not_received' => [
      'expected_at' => 1590000000,
      'explanation' => 'Never shipped',
      'product_description' => 'Baseball bat',
      'product_type' => 'merchandise',
    ]
  ]
]);

// 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";

DisputeCreateParams params =
  DisputeCreateParams.builder()
    .setTransaction("ipi_1GW0GkKA9rkJS7vmeJlLI1Gp")
    .setEvidence(
      DisputeCreateParams.Evidence.builder()
        .setReason(DisputeCreateParams.Evidence.Reason.NOT_RECEIVED)
        .setNotReceived(
          DisputeCreateParams.Evidence.NotReceived.builder()
            .setExpectedAt(1590000000)
            .setExplanation("Never shipped")
            .setProductDescription("Baseball bat")
            .setProductType(DisputeCreateParams.Evidence.NotReceived.Product.MERCHANDISE)
            .build())
        .build())
    .build();

Dispute dispute = Dispute.create(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');
const stripe = Stripe('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const dispute = await stripe.issuing.disputes.create({
  transaction: 'ipi_1GW0GkKA9rkJS7vmeJlLI1Gp',
  evidence: {
    reason: 'not_received',
    not_received: {
      expected_at: 1590000000,
      explanation: 'Never shipped',
      product_description: 'Baseball bat',
      product_type: 'merchandise',
    },
  },
});

// 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.IssuingDisputeParams{
  Transaction: stripe.String("ipi_1GW0GkKA9rkJS7vmeJlLI1Gp"),
  Evidence: &stripe.IssuingDisputeEvidenceParams{
    Reason: stripe.String(string(stripe.IssuingDisputeEvidenceReasonNotReceived)),
    NotReceived: &stripe.IssuingDisputeEvidenceNotReceivedParams{
      ExpectedAt: stripe.Int64(1590000000),
      Explanation: stripe.String("Never shipped"),
      ProductDescription: stripe.String("Baseball bat"),
      ProductType: stripe.String(string(stripe.IssuingDisputeEvidenceNotReceivedProductTypeMerchandise)),
    },
  },
}

idp, _ := dispute.New(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 DisputeCreateOptions
{
  Transaction = "ipi_1GW0GkKA9rkJS7vmeJlLI1Gp",
  Evidence = new DisputeEvidenceOptions
  {
    Reason = "not_received",
    NotReceived = new DisputeEvidenceNotReceivedOptions
    {
      ExpectedAt = 1590000000,
      Explanation = "Never shipped",
      ProductDescription = "Baseball bat",
      ProductType = "merchandise",
    },
  },
};

var service = new DisputeService();
var dispute = service.Create(options);

Learn more in the Dispute reasons and evidence section below. During creation, all evidence fields are optional for flexibility while you collect more evidence.

All Issuing dispute API methods return a Dispute object.

Update

Use the Unsubmitted tab to access disputes that are in progress. The Submit before date indicates when the dispute expires.

From the individual dispute page, click on Edit submission to access the form where you can update the evidence.

The Update method can be used to update the evidence and metadata of unsubmitted disputes. For submitted disputes, only metadata can be updated.

The table below describes possible updates to evidence. Suppose we start with evidence in this state:

"evidence": {
  "reason": "not_received",
  "not_received": {
    "additional_documentation": null, // We refer to these as "evidence fields"
    "expected_at": null,
    "explanation": "Not shipped",
    "product_description": "Baseball cards",
    "product_type": "merchandise"
  }
}
Action Input Result
Add, replace, and remove evidence fields 
"evidence": {
  "reason": "not_received",
  "not_received": {
    "expected_at": 1590000000, // Add
    "explanation": "Lost", // Replace
    "product_description": "" // Remove
  }
}

"evidence": {
  "reason": "not_received",
  "not_received": {
    "additional_documentation": null,
    "expected_at": 1590000000,
    "explanation": "Lost",
    "product_description": "",
    "product_type": "merchandise"
  }
}
Change reason 
"evidence": {
  "reason": "fraudulent"
}

"evidence": {
  "reason": "fraudulent",
  "fraudulent": {
    "additional_documentation": null,
    "explanation": "Not shipped"
    // ^Transferred from "not_received",
  }
}
Update evidence fields without supplying reason 
"evidence": {
  "not_received": {
    "explanation": "Lost"
  }
}
Error. The evidence object must always contain the reason field.
Unset all evidence fields 
"evidence": {
  "reason": "not_received",
  "not_received": ""
}

"evidence": {
  "reason": "not_received",
  "not_received": {,
      "additional_documentation": null,
      "expected_at": null,
      "explanation": null,
      "product_description": null,
      "product_type": null
  }
}

Submission

The Submit button on the evidence form is enabled when all required evidence is present.

The Submit endpoint validates that all the required evidence for the given dispute reason is present. The Dispute reasons and evidence section provides more details.

curl https://api.stripe.com/v1/issuing/disputes/idp_1GW0GkKA9rkJS7vmeJlLI1Gp/submit \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -X POST

stripe issuing disputes submit idp_1GW0GkKA9rkJS7vmeJlLI1Gp

# 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::Issuing::Dispute.submit(
  'idp_1GW0GkKA9rkJS7vmeJlLI1Gp',
)

# 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.issuing.Dispute.submit(
  "idp_1GW0GkKA9rkJS7vmeJlLI1Gp",
)

// 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\Issuing\Dispute::retrieve('idp_1GW0GkKA9rkJS7vmeJlLI1Gp');
$dispute->submit();

// 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(
    "idp_1GW0GkKA9rkJS7vmeJlLI1Gp"
  );

Dispute upadtedDispute = dispute.submit();

// 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');
const stripe = Stripe('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const dispute = await stripe.issuing.disputes.submit(
  'idp_1GW0GkKA9rkJS7vmeJlLI1Gp',
);

// 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"

idp, _ := dispute.Submit(
  "idp_1GW0GkKA9rkJS7vmeJlLI1Gp",
  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();
service.Submit("idp_1GW0GkKA9rkJS7vmeJlLI1Gp");

Resolution

Dispute statuses are updated once we hear back from the card network. If the acquiring merchant wins the dispute, the disputeโ€™s status changes to lost and no funds are transferred.

If you win the dispute, the status changes to won and funds are transferred back to your Issuing balance. The credit to your account takes the form of a balance transaction of type issuing_dispute accessible in the Dashboard under All transactions and on the bottom of the dispute detail page.

Viewing a disputeโ€™s balance transactions in the Dashboard.

Dispute statuses are updated once we hear back from the card network. If the acquiring merchant wins the dispute, the disputeโ€™s status changes to lost and no funds are transferred.

If you win the dispute, the status changes to won and funds are transferred back to your Issuing balance. The credit to your account takes the form of a balance transaction of type issuing_dispute.

The balance transaction is listed under balance_transactions on the Dispute object. However, this field is not returned by default. Request it using the expand field. See the Expand documentation for more details.

Testing

Stripe processes test mode disputes as if they are live to demonstrate the expected behavior. For example, we fire off webhook events, create balance transactions, and update your Issuing balance. All this happens in the seconds after you submit the dispute.

Select the desired test mode outcome on the top panel of the submission form. Selecting Won or Lost causes the explanation field to be auto-filled with โ€œwinning_evidenceโ€ or โ€œlosing_evidenceโ€ respectively to record the selected outcome.

Similar to live mode, a test mode dispute transitions to expired 110 days after the transaction is captured.

Stripe processes test mode disputes as if they are live to demonstrate the expected behavior. For example, we fire off webhook events, create balance transactions, and update your Issuing balance. All this happens in the seconds after you submit the dispute.

In the API, submitting a test mode dispute with โ€œwinning_evidenceโ€ or โ€œlosing_evidenceโ€ entered into the explanation field informs Stripe to transition the dispute to the won or lost status respectively. Otherwise, the dispute transitions to submitted status as it would in live mode.

Similar to live mode, a test mode dispute transitions to expired 110 days after the transaction is captured.

Webhooks

You can register a webhook endpoint to be informed of changes to your disputes. All Issuing dispute webhooks contain the latest Dispute object.

Webhook events Trigger
issuing_dispute.created Dispute created.
issuing_dispute.updated Dispute updated.
issuing_dispute.submitted Dispute submitted.
issuing_dispute.funds_reinstated Funds transferred to your Issuing balance for a won dispute.
issuing_dispute.closed Dispute transitioned into a won, lost, or expired status.

Dispute reasons and evidence

Disputes can be submitted with one of the following reasons:

  • Fraudulent
  • Not received
  • Duplicate
  • Merchandise not as described
  • Service not as described
  • Canceled
  • Other

In the Dashboard, โ€œMerchandise not as describedโ€ and โ€œService not as describedโ€ are consolidated under โ€œNot as describedโ€.

Each reason requires a different set of evidence:

Evidence Description
Explanation A description of the transaction and why the cardholder is disputing the purchase. This field can also be used to provide additional explanation not captured anywhere else.
Additional documentation Relevant documents such as card statements or return shipping tracking. Dispute evidence must be in the format of PDF or JPEG. Before submitting, ensure that any text or images are clear and large enough to show up clearly in a black and white fax transmission.
Evidence Description
Product type Required A selection of whether or not the purchase was merchandise, or service or digital product.
Product description Required A detailed description of the purchase.
Expected at Required The date the purchase was expected to arrive or date of scheduled service.
Explanation A description of the transaction and why the cardholder is disputing the purchase. This field can also be used to provide additional explanation not captured anywhere else.
Additional documentation Relevant documents such as card statements or return shipping tracking. Dispute evidence must be in the format of PDF or JPEG. Before submitting, ensure that any text or images are clear and large enough to show up clearly in a black and white fax transmission.
Evidence Description
Cash receipt* Receipt of the cash transaction.
Check image* Image of the front and back of the check.
Original transaction* Token of the original transaction that paid for the purchase. This transaction should have preceded the transaction being disputed.
Card statement* Card statement containing the transaction.
Explanation A description of the transaction and why the cardholder is disputing the purchase. This field can also be used to provide additional explanation not captured anywhere else.
Additional documentation Relevant documents such as card statements or return shipping tracking. Dispute evidence must be in the format of PDF or JPEG. Before submitting, ensure that any text or images are clear and large enough to show up clearly in a black and white fax transmission.
* Exactly one of the four types of payment evidence is required.
Evidence Description
Received at Required The date the cardholder received the merchandise.
Return status Required The outcome of the return. As explained in the Considerations section, the dispute is only valid if the cardholder attempted to return anything they received.
Returned at Required The date the cardholder initiated return of merchandise. Stripe validates that this date comes after the "Received at" date.
Return description Required A description of the how the return was carried out. Name the shipping carrier and provide the tracking number where possible.
Explanation Required A description of the transaction and why the cardholder is disputing the purchase. This field can also be used to provide additional explanation not captured anywhere else.
Additional documentation Relevant documents such as card statements or return shipping tracking. Dispute evidence must be in the format of PDF or JPEG. Before submitting, ensure that any text or images are clear and large enough to show up clearly in a black and white fax transmission.
Evidence Description
Received at Required The date the cardholder received the service or digital product.
Canceled at Required The date the cardholder canceled the service or digital product.
Cancellation reason Required The cardholderโ€™s rationale for canceling the service or digital product.
Explanation Required A description of the transaction and why the cardholder is disputing the purchase. This field can also be used to provide additional explanation not captured anywhere else.
Additional documentation Relevant documents such as card statements or return shipping tracking. Dispute evidence must be in the format of PDF or JPEG. Before submitting, ensure that any text or images are clear and large enough to show up clearly in a black and white fax transmission.

When disputing merchandise that was canceled and not received, please use "not received" instead. The "canceled" reason is for cases where the cardholder receives the merchandise in spite of canceling it. They are expected to prove that they returned or attempt to return what they received.


Evidence Description
Product type Required A selection of whether or not the purchase was merchandise, or service or digital product.
Product description Required A detailed description of the purchase.
Expected at Required The date the purchase was expected to arrive or date of scheduled service.
Cancellation policy provided Required A boolean indicating whether the merchant provided a cancellation policy.
Canceled at Required The date the cardholder canceled the purchase.
Cancellation reason Required The cardholderโ€™s rationale for canceling the purchase. In addition, if a cancellation policy was provided, explain how the cancellation was in line with the policy. The dispute is invalid if the cancellation was not in line with the policy.
Returned at The date the cardholder initiated return of the purchase. Stripe validates that this date comes after the "Received at" date. Required if the product type is "merchandise".
Return status The outcome of the return. As explained in the Considerations section, the dispute is only valid if the cardholder attempted to return anything they received. Required if the product type is "merchandise".
Explanation A description of the transaction and why the cardholder is disputing the purchase. This field can also be used to provide additional explanation not captured anywhere else.
Additional documentation Relevant documents such as card statements or return shipping tracking. Dispute evidence must be in the format of PDF or JPEG. Before submitting, ensure that any text or images are clear and large enough to show up clearly in a black and white fax transmission.
Evidence Description
Product type Required A selection of whether or not the purchase was merchandise, or service or digital product.
Product description Required A detailed description of the purchase.
Explanation Required A description of the transaction and why the cardholder is disputing the purchase. This field can also be used to provide additional explanation not captured anywhere else.
Additional documentation Relevant documents such as card statements or return shipping tracking. Dispute evidence must be in the format of PDF or JPEG. Before submitting, ensure that any text or images are clear and large enough to show up clearly in a black and white fax transmission.
Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
On this page
Considerations before initiating a dispute
Lifecycle
Creation
Update
Submission
Resolution
Testing
Webhooks
Dispute reasons and evidence