> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Mastercard Disputes

> Manage Mastercard disputes by integrating your dispute cases with the Mastercard network.

This page provides information on how to integrate your dispute cases with the Mastercard network using the `/cases` endpoint. With the `/cases` endpoint you can manage disputes, including tasks such as initiating a dispute, uploading supporting documents, and receiving status updates. You can also use the `/cases` endpoint to track dispute progress by retrieving information such as:

* A list of dispute cases and their current state

* Information on a specific dispute case

* A specific dispute case transition

* An array of all dispute transitions related to a particular dispute case

* Dispute case documents

For general information on disputes, chargebacks, and best practices, see [About Disputes](/developer-guides/about-disputes/). For detailed reference information, see [Disputes (Mastercard)](/core-api/disputes-mastercard/) in the Core API Reference.

<h2 id="_dispute_cases">
  Dispute cases
</h2>

Each `case` object corresponds to a dispute case. The `case` object requires a transaction token. This must always be a `CLEARING` transaction. The amount disputed by the cardholder, indicated in `dispute_amount`, must be less than or equal to the clearing amount. Multiple partial disputes are accepted on the same clearing transaction as long as the total amount is not greater than the dispute amount.

<h2 id="_dispute_categories">
  Dispute categories
</h2>

The dispute type indicates the category of a dispute, which can be `FRAUD`, `AUTHORIZATION`, `POINT_OF_INTERACTION_ERROR`, or `CARDHOLDER_DISPUTE`.

<h3 id="_fraud">
  Fraud
</h3>

A cardholder submits a fraud dispute when they see a transaction on their statement that they do not recognize, which can result from a lost or stolen card or a stolen PAN.

<h3 id="_authorization">
  Authorization
</h3>

An authorization dispute occurs when the partner program attempts to reclaim money that the cardholder has spent that has resulted in a negative balance. This typically happens when there is a clearing transaction without an authorization transaction. In this case, the cardholder has found a way to spend money without permission from the program, such as spending more money than they have in their account balance.

<h3 id="_point_of_interaction_error">
  Point of interaction error
</h3>

A point of interaction (POI) error dispute occurs when the transaction was expected, but data or metadata is incorrect, such as the transaction amount or account number.

<h3 id="_cardholder_disputes">
  Cardholder disputes
</h3>

A cardholder dispute occurs when the cardholder has a dispute with the merchant, such as a claim that incorrect or defective merchandise was received, or that they did not receive the goods or services they paid for. In this case, the cardholder is demanding their money back and the merchant has refused.

<h2 id="_dispute_reasons">
  Dispute reasons
</h2>

Reason codes indicate the rationale behind a dispute. For a list, see [Dispute case reasons](/core-api/disputes-mastercard/#_dispute_case_reasons) in the Mastercard Cases API Reference.

<h2 id="_uploading_documents">
  Uploading documents
</h2>

Cardholders must attach the necessary documents to support their claim. Mastercard requires that supporting documents be uploaded for all dispute claims. `OPEN`, `OPEN_WITH_ACTION_REQUIRED`, and `READY` are states for which documents can be uploaded.

<h2 id="_managing_provisional_credits">
  Managing provisional credits
</h2>

[Regulation E](https://www.federalreserve.gov/supervisionreg/regecg.htm), the United States regulation implementing the Electronic Fund Transfer Act, provides a framework for protecting customers who use electronic methods to transfer money, as well as guidelines for electronic debit card issuers throughout the dispute investigation process.

Regulation E allows for up to 45 days to resolve these disputes but, during that time, you must typically issue a provisional credit for the disputed amount. The provisional credit must be provided within 10 days after the customer made first contact. If a dispute is not resolved within the required 45-day time frame, the provisional credit is automatically granted to the cardholder.

You can manage provisional credits in Marqeta Dashboard for your Regulation E compliant programs. For more details, see [Disputes in the Dashboard](/developer-guides/disputes-dashboard/). For details on managing provisional credits using the `/cases` endpoint, see [Managing Provisional Credits](/developer-guides/disputes-regulation-e/).

<h2 id="_closing_or_withdrawing_a_dispute">
  Closing or withdrawing a dispute
</h2>

When a `POST` request to the `/cases/{token}/transitions` endpoint is called with the state set to `CLOSE` and the action set to `WITHDRAW_AND_CLOSE` with a `reason_code` of `40`, Marqeta determines whether the dispute case is in a state that allows the transition. If so, an entry is created in the dispute case transitions history with the new transition, and then the state of the dispute case is set to `CLOSED`.

For any disputes that are returned as an associated transaction, close those disputes using the `/cases/{token}/transitions` endpoint. If there are no associated transactions, no action is necessary.

A dispute case can only be withdrawn if it is in one of the following states: `OPEN`, `READY`, or `OPEN_WITH_ACTION_REQUIRED`. The dispute case can only move to `CLOSED` with a `WITHDRAW_AND_CLOSE` action. Your transition will fail if you attempt to transition a dispute case to the `CLOSED` state with the `WITHDRAW_AND_CLOSE` action and the dispute case state is not in one of the valid states listed above.

<h2 id="_monitoring_states_using_the_webhooks_endpoint">
  Monitoring states using the Webhooks endpoint
</h2>

Marqeta receives state changes for each dispute from the card network and makes them available to you through webhooks. To monitor these, use the `/webhooks` endpoint to subscribe to the chargeback transition events described in [Webhooks](/core-api/webhooks/).

You can also subscribe to the following additional events, as a way to track chargeback progress:

* `authorization.clearing.chargeback`

* `authorization.clearing.chargeback.completed`

* `authorization.clearing.chargeback.provisional.credit`

* `authorization.clearing.chargeback.provisional.debit`

* `authorization.clearing.chargeback.reversal`

* `authorization.clearing.representment`

* `pindebit.chargeback`

* `pindebit.chargeback.completed`

* `pindebit.chargeback.provisional.credit`

* `pindebit.chargeback.provisional.debit`

* `pindebit.chargeback.reversal`

* `pindebit.representment`

For a detailed description of these events, see [Transaction Events](/core-api/event-types/#_transaction_events).

<h2 id="_resolution_time_frames">
  Resolution time frames
</h2>

Mastercard dispute responses are required within a specific timeline. The following are the expected timelines from the Mastercard SLA for responses to a dispute.

* Presentment: Acquirer must send the presentment within seven calendar days.

* Chargeback:

  * Initial chargeback: 45 days.

  * Prearbitration chargeback: 45 days.

* Second presentment (representment): 45 days.

* Arbitration chargeback: 30 days.

  * ATM must be submitted within 90 days of settlement.

  * All other chargebacks must be submitted within 120 days.


## Related topics

- [Disputes (Mastercard)](/docs/core-api/disputes-mastercard.md)
- [About Disputes](/docs/developer-guides/about-disputes.md)
- [Transitioning Cases](/docs/developer-guides/disputes-portal-transitioning-and-closing.md)
- [Release Notes](/docs/developer-guides/release-notes-2025.md)
- [Managing Visa Disputes](/docs/developer-guides/managing-visa-disputes.md)