Issuing disputes

Learn how to use Issuing to dispute transactions.

When an issue with a transaction occurs, a User or their cardholder can dispute the charge. Common issues include fraud, product/service not received, or processing error.

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. If you manage a low volume of disputes, we recommend using the Dashboard. If you manage a high volume of disputes, we recommend using the API.

Considerations before initiating a dispute

Network Rules

We process disputes according to rules and guidelines of the card netowrk that handled the transaction. The contexts of this document are a simplification. For the complete details regarding the rules and guidelines that apply to disputes, please refer to the Visa and Mastercard rulebooks.

Submitting Valid Disputes

A dispute can only be submitted once. After submission, no additional edits or supplimental evidence are allowed to be added. It is the User’s responsibility to properly submit the dispute based on the requirements established by the card network. Filing an invalid or incomplete dispute may result in a loss.

Consumer Disputes

For consumer disputes (not recieved, cancelled, not as descrbied, etc), cardholders are required to attempt to resolve the dispute with the merchant before filing a dispute. Documentation regarding the cardholder’s attempt to resolve the dispute should be included in the dispute submission.

How Card Networks define fraud

For both Visa and Mastercard, a fraudulent transaction is defined as one where the cardholder denies participating in the charge. If the cardholder acknowledges they participated in the transaction (for example a scam); they should file the dispute under a different reason for which they have dispute rights.

Requirements for fraud disputes (for Platforms)

Platforms must allow their connected accounts to submit fraudulent disputes directly to Stripe through a dashboard that you, as the Platform, make available using our APIs or embedded components. You can’t restrict their ability to submit such disputes in any way. After fraud disputes are submitted, Stripe will review them to determine if the cardholder needs to be reimbursed.

Blocked dispute submissions

Stripe might block fraud dispute submission if the transaction doesn’t qualify for fraud protection under local regulations and the account holder has no dispute rights according to network rules.

For platforms

If you’re obligated to submit a dispute and you submit it, you’ve fulfilled your obligation, regardless of if Stripe blocks the submission.

Card networks might consider a dispute invalid for the following reasons (among others):

The transaction is a refund and not a capture.
The transaction is a mobile push payment transaction.
The dispute timeframe has expired

In the Dashboard, the dispute transaction button is only enabled for eligible transactions. In the API, attempting to dispute an ineligible transaction results in an error.

Note

Although you can file disputes in any language, our partner payment networks only acknowledge evidence in English or with an English translation.

Expiration

Card networks establish a timeframe by which a dispute can be submitted. A dispute submitted after this timeframe is considered expired and is lost. The timeframe varies depending on dispute reason and the card network.

For Visa, fraudulent and processing error disputes should be filed within 110 days of the transaction date. ‘Authorization’ disputes should be filed within 65 days of the transaction date. Consumer disputes such as ‘Canceled’, ‘Not Received’, and ‘Not as Described’ should be filed within 110 days of the merchandise/service expected at date.

Partial Amounts

Disputes can be filed for the full amount or for a partial amount. If there are refunds, they should be accounted for and only a partial dispute should be filed. Certain dispute reasons, such as incorrect amount, necessitate that only a partial dispute amount is filed. Lastly, for many consumer disputes, the dispute amount will be partial in cases when part of the merchandise order or service was received.

Lifecycle

Business terminology

In the above diagram, business refers to the acquiring business, the business receiving the payment.

Newly-created disputes begin in an unsubmitted status. At this point, you can update their evidence and metadata. After you’ve added all the required evidence, you can then submit the dispute. If you don’t submit a dispute within 110 days of the transaction clearing, its status becomes expired.

Stripe and card networks process disputes that have a status of submitted. As such, you can’t update dispute evidence, but you can still update their metadata. Submitted disputes enter into a multi-step process defined by card networks and participating banks. After a dispute is resolved, Stripe transitions it to either the terminal won or lost status.

Creation

Fill out the Dispute Amount field to indicate the disputed amount (full or partial). The field’s initial value is the transaction amount. Submissions that have empty Dispute Amount fields create disputes with the full transaction amount.

Dispute Amount field on the Issuing dispute creation page

Click Dispute transaction when viewing an eligible transaction. You’ll 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.

After you submit a dispute, you can’t modify the information or resubmit the dispute.

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 Edit submission to access the form where you can update the evidence.

Submission

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

Caution

Review the evidence thoroughly before you submit, because you can’t modify dispute information after submitting the dispute.

Resolution

Stripe updates a dispute’s status when we hear back from the card network.

If you win the dispute, its status changes to won and we credit your Issuing balance in the form of an issuing_dispute balance transaction. This balance transaction is accessible in the Dashboard under All transactions and on the bottom of the dispute details page.

Note

If you make a transaction in a currency other than your account’s default currency (for example, a GBP transaction that your USD card pays), Stripe refunds the won dispute in the transaction’s original currency.

If you lose the dispute, the dispute’s status changes to lost and we don’t credit any amount to your Issuing balance.

Viewing a dispute’s balance transactions in the Dashboard.

Testing

Stripe’s sandbox environments allow you to test dispute logic without any live effects. For example, we send webhook events, create balance transactions, and update your test Issuing balance without moving any funds or changing any balances on your live account.

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

When submitting a test dispute through the Dashboard, you can choose the dispute’s outcome. Selecting Won automatically changes the dispute’s explanation field to winning_evidence, and selecting Lost automatically changes the dispute’s explanation field to losing_evidence.

Webhooks

To be notified of changes to your disputes, you can listen for Issuing dispute webhook events. All Issuing dispute events contain the updated 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 (usually associated with `won` dispute status).
`issuing_dispute.funds_rescinded`	Funds deducted from your Issuing balance (usually associated with a provisional credit clawback).
`issuing_dispute.closed`	Dispute transitioned into a `won`, `lost`, or `expired` status.

Dispute reasons and evidence

Different dispute reasons will have varying requirements on what is needed for a proper submission. Complete dispute submission and the quality of the associated documentation directly influences your chances of winning. The strongest disputes have clear, descriptive documentation.

Disputes can be submitted with one of these reasons:

Canceled: The cardholder canceled or returned merchandise or canceled services, and the business didn’t process a credit or void a transaction receipt.
Duplicate: Covers processing error dispute types, including duplicate transaction, incorrect amount, and paid by other means.
Fraudulent: The cardholder did not authorize the transaction.
Merchandise not as described: The cardholder received the merchandise, but it didn’t match what was presented at time of purchase, or it was damaged or defective.
Not received: The cardholder participated in the transaction but didn’t receive the merchandise or service.
No valid authorization: (API only) The business processed a transaction without a valid authorization.
Service not as described: The cardholder received the service, but it didn’t match what was presented at time of purchase.
Other: A dispute scenario that doesn’t clearly qualify as any other dispute reason. Disputes submitted under this reason will be manually recategorized by Stripe. Please include the actual dispute reason in the evidence explanation when filing these disputes.

Note that 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 it. You can also use this field to provide an additional explanation that’s not captured anywhere else. It’s important for the cardholder to verify that they didn’t participate in the transaction, and that the transaction wasn’t made by someone known to the cardholder.
Additional documentation	Relevant documents such as card statements or return shipping tracking. The files must be in PDF or JPEG format. Before submitting the dispute, make sure that all text and images are clear and large enough to be legible in a black-and-white fax transmission. Encouraging cardholders to keep their billing address up to date is a key component in the assessment of fraudulent disputes.

Fraud disputes

You can dispute a transaction for fraud if the cardholder claims they did not authorize the transaction.

Before filing a dispute:

Confirm with the cardholder that they didn’t make the transaction in error, and that it wasn’t made by someone known to them. Transactions made by a friend or family member, for example, don’t constitute fraud for dispute purposes.
Cancel the affected card if submitting a dispute via the API. Filing a dispute will automatically cancel the card if done via the Dashboard.

In certain situations, you can lose fraud dispute rights for a transaction:

For card-present transactions: A card network might automatically reject a fraud dispute because liability defaults to the issuer.
For card-not-present transactions: A card network might automatically reject a fraud dispute if the cardholder was authenticated during the transaction. That often happens when 3D Secure was requested or a secured payment method like Apple Pay was used.

Authorization disputes

Each time an acquiring business processes a transaction, they must first request an authorization from the issuer. If a business captures a payment without a valid authorization, or if they did obtain an authorization but it is expired; you can dispute the transaction. The reason you should choose depends on the method used to submit the dispute:

Filing a dispute through the API: File the dispute under the no_valid_authorization reason.
Filing a dispute through the Dashboard: File the dispute under the other reason and specify in the explanation field that you are filing a ‘no authorization’ dispute.

Authorization disputes are distinct from fraud disputes:

File a fraud dispute when the cardholder didn’t participate in the transaction.
File an authorization dispute when the business didn’t obtain a valid authorization for the transaction.

Another reason for an authorization dispute is an overcapture. An overcapture occurs when the captured amount exceeds the authorized amount. When you submit an authorization dispute for an overcapture, you must adjust the dispute amount to include only the amount that exceeded the authorization.

Note

Some Merchant Category Codes (MCCs) allow overcaptures of certain amounts or disallow authorization disputes. For details, refer to the current card network rules for your region.

Withdrawing

Stripe can only withdraw a dispute within 1 day of its submission to the card network. If you want to withdraw a dispute, contact Stripe Support immediately.

Liability for fraud

For platforms operating in the USA, Most aspects of Regulation Z don’t apply to business-purpose cards, but Regulation Z does protect users of business-purpose cards from fraud and other types of “unauthorized card use," which means the use of a charge card by a person who doesn’t have the authority to use it. In most cases, an accountholder can’t be held responsible for unauthorized use of cards linked to their account unless a reasonable investigation into the fraud is conducted. However, if the account holder has 10 or more employee authorized users, they might not qualify for this protection.

When one of your users disputes a transaction because the user believes it was unauthorized, Stripe sends the dispute to the card network for adjudication (as with any other type of disputed transaction). Stripe or the card network determines who must pay for the fraud: you or the business.

If Stripe or the card network determines the business is liable for the fraud, then neither you nor your user are responsible for the disputed transactions.

If Stripe or the card network determines that you’re liable for the fraud, then you might be required to pay for the disputed transaction. Stripe performs a reasonable investigation into the dispute to determine whether fraud actually occurred or whether the user doesn’t qualify for protection under Regulation Z. If the investigation uncovers that unauthorized card use actually occurred and that the user qualifies for protection, then you remain liable for the unauthorized transactions. Alternatively, if the investigation uncovers that unauthorized card use didn’t occur or that the user doesn’t qualify for protection, then we hold the accountholder responsible for the disputed charges.

Email connect accounts

Issuing platforms must send regulated notice emails to connected accounts when a dispute is submitted, and again when a dispute is won or lost. Learn more about regulated notices.

Use with Stripe Treasury

Disputes of ReceivedDebits on FinancialAccounts have a corresponding DebitReversal after the dispute is submitted.