Skip to main content
The Disputes portal is in early access. Contact your Marqeta representative to begin using the Disputes portal.
The Disputes portal is the Marqeta dispute management platform for handling payment dispute cases from initial filing through final resolution. It provides a centralized workspace where you can create disputes, review case details and transaction history, manage supporting documentation, transition cases through each stage, and monitor dispute performance through reporting. This guide explains the core concepts behind the Disputes portal for both operations users (dispute analysts and case managers) and developers integrating with the Marqeta platform to provide a shared understanding of how disputes are structured and resolved. This guide focuses on concepts and terminology rather than step-by-step procedures to serve the mixed audience. At the end of this guide, you will understand:
  • What the Disputes portal is and what it does
  • What a dispute case is and how it’s organized
  • The key terms involved in the dispute lifecycle
  • How cases move through different stages
  • How the Disputes portal fits into the broader payments and reporting picture

​
What the Disputes portal does

The Disputes portal centralizes dispute resolution, allowing you to manage each dispute in one place with access to its details, history, and documentation. The platform provides the following core capabilities:
  • Case management — Track cases through each stage of the dispute lifecycle.
  • Case visibility — View case details, transaction history, and documentation together.
  • Investigation tools — Analyze disputes with tools for detailed case examination.
  • Search and filtering — Locate specific cases and transactions.
  • Reporting and insights — Monitor dispute performance and identify trends.
These capabilities serve the people who work disputes day to day, while the underlying case and transaction data align with the objects developers already work with on the Marqeta platform.

​
Dispute cases

A case is the central object in the Disputes portal. Each case represents one dispute and carries everything related to that dispute, such as the disputed transaction, the current state, supporting documents, activity history, and the case’s progression over time.
Single disputes case view
When you open a case, its information is organized into tabs:
  • Dispute Lifecycle — The main workspace for managing the case.
  • Documents — Where you upload and review case files.
  • Evidences — Where you upload evidence for the case.
  • Activity — A history of every action taken on the case.
  • Related Transactions — The complete transaction timeline, from authorization through chargeback.
  • User Transactions — Transactions associated with the cardholder.
A side panel stays visible while you work and provides quick reference information, including point of interaction details, merchant information, the cardholder profile, card details, a summary of the cardholder’s disputes, and a transaction disputes overview. Each case also has a set of details that identify and describe it, including its current dispute state, the transaction token, the card network case number, the assigned team member, the dispute amount, and the dispute reason code.

​
Key terms

The following describes recurring terms that are used throughout the Disputes portal:
  • Transaction token — The unique identifier for a transaction. You can use it to look up a transaction, create a dispute, and search for an existing case.
  • Case token — The unique identifier for a dispute case. You can use it to locate a case directly.
  • Dispute reason code — The card network reason code that classifies why a transaction is disputed.
  • Transition — A movement of a case from one stage to the next. The Disputes portal records transitions in reverse chronological order so the most recent action appears first.
  • Provisional credit — A temporary credit issued to the cardholder while a dispute is investigated. The Disputes portal tracks when provisional credit must be issued, how long it has been active, and when it becomes permanent.
  • Loss reason — The reason selected when a case is closed as lost or withdrawn, accompanied by guidance and any required evidence.

​
How disputes are created

The Disputes portal supports several ways to create a dispute case. You can start from a transaction token, from a cardholder’s profile and their associated transactions, or from a card and the transactions made with it. Administrators can also create disputes in bulk for specific scenarios. To create a single dispute, choose a creation method:
  • Questionnaire — Creates the dispute through a step-by-step questionnaire. The guided questions determine the card network reason code automatically. This method is best for guided dispute creation when you need detailed prompts.
  • Fraud only — Reports fraud without initiating a chargeback. This method is best for fraud reporting that doesn’t require immediate chargeback action.
After you create a dispute, the Disputes portal creates a new case, opens it to the Dispute Lifecycle tab, and adds it to your case views for tracking.

​
How cases move through the lifecycle

The dispute lifecycle is the sequence of stages a case passes through from creation to closure. You advance a case by transitioning it, and the Disputes portal records each transition along with the evidence and documents attached at that point. For a full description of lifecycle stages, states, and network interactions, see About Disputes.

​
How the Disputes portal fits the bigger picture

The Disputes portal sits downstream of the payments flow. A dispute begins with a transaction processed on the Marqeta platform, and the Related Transactions view ties a case back to the full transaction timeline, from authorization through clearing and chargeback. This connects the operational work of resolving a dispute to the same transaction data that developers integrate with through the Marqeta platform. On the reporting side, the Disputes portal includes dashboards that summarize dispute activity over time, such as case status, wins and losses, reject rate, dispute volume, and win rate by reason. These insights help teams monitor performance and prioritize process improvements.

​
Related resources