15 minute read

October 3, 2020

About Disputes

Transaction disputes are a necessary part of card issuing. Marqeta enables you to manage the dispute process using the Marqeta Dashboard or with the /cases endpoint. You can manage disputes by performing tasks such as submitting a dispute, retrieving information such as dispute status, and uploading supporting documents.

This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.

The Marqeta Cases Team is available to help you implement best practices for submitting the required dispute documentation and optimizing your win rates.

This page provides information on the dispute process and best practices. For specific details on how to integrate with the Visa network, see Managing Visa Disputes. For reference information, see Dispute Cases (Visa) in the Core API Reference. For information on participating in a limited beta for Mastercard dispute cases, contact your Marqeta Representative.

What is a dispute?

A dispute is often initiated if a cardholder:

  • Did not receive a product or service.

  • Did not recognize the charge or business name on their statement.

  • Believes the product to be damaged, defective, or not as described.

  • Was the victim of fraud, card theft, or identity theft.

Best practices

The following are best practices for resolving your disputes and optimizing your win rates:

  • When a card is reported lost or stolen, immediately deactivate the card to ensure a tight timeline between a lost card and potential transactions. Submit the dispute case immediately after the dispute has been opened by the cardholder.

  • If your team is working directly with cardholders, create a dispute form or use an example from Marqeta for gathering as much information as possible along with the cardholder’s attestation of the dispute.

  • Provide the strongest possible level of documentation, such as communication with the merchant, receipts, and timelines. Incomplete dispute information or lack of documentation can decrease the likelihood of winning a dispute.

  • To submit a dispute to the Visa network, the dispute amount must be over $25. There is a cost to processing a dispute case, so even if the card network decides in your favor, you will have lost from a cost perspective if the disputed transaction amount is less than $25.

  • If the dispute involves goods and services issues with a merchant, have a representative of your company or the cardholder first contact the merchant directly, which can result in a refund and make a dispute unnecessary.

No more than 15 fraud-related disputes can be initiated against the same primary account number (PAN, also known as the card number).

The dispute lifecycle

Disputes are required to follow a series of steps defined by the card networks and participating banks. This is the overall lifecycle of a dispute process after a dispute is claimed by the cardholder:

Dispute Lifecycle

Is this helpful?

  1. Presentment: The transaction clears. This is a typical transaction clearing event. In order for there to be a dispute, the transaction must first clear.

  2. Initiated: Marqeta disputes the transaction on behalf of the cardholder. The acquiring bank can respond to the dispute directly or forward it to the merchant. If forwarded to the merchant, the merchant can accept the loss or provide documentation to refute the dispute claim. At this point, the dispute enters the initiated state.

  3. Representment (Second Presentment): The acquiring bank attempts to refute the claim, likely because they believe it is invalid or incomplete. Merchants have recourse to defend against the claim by submitting a representment. For example, if a cardholder claims fraud in a card present transaction, the merchant may provide the card network with a representment that includes a signed copy of the receipt. In this case, the merchant has complied with their requirements and is not liable. The dispute enters the representment state.

  4. Pre-arbitration: Upon receipt of the representment, Marqeta may choose to reach out to the acquiring bank once again. Visa refers to this additional step as pre-arbitration. This optional step allows the merchant an additional opportunity to provide supporting documentation. The dispute enters the prearbitation state.

  5. Arbitration: The dispute is submitted to the card network for a decision. The card network’s decision is final and must be accepted by both Marqeta and the acquiring bank.

  6. Resolution: After arbitration, the dispute is resolved and enters into one of the following states: case.won, case.lost, network.rejected, written.off.issuer(internal only), or written.off.program (internal only).

The vast majority of disputes are resolved during the Initiated state. Disputes typically take 30-120 days to resolve. A dispute is won if the acquirer does not respond to the dispute within the expected timeline Expected timelines vary according to the card network, which are defined in their respective 30-day service level agreement (SLA) timelines. For the Visa SLA, see Managing Visa Disputes.

Dispute states

Once a dispute has been initiated, it flows through a series of states, or transitions. The following are the states involved in a dispute case resolution:

  • Initiated

  • Representment

  • Pre-arbitration

  • Arbitration

  • Case won

  • Case lost

  • Network rejected

  • Written off by the issuer (internal only)

  • Written off the program (internal only)

The following sections describe the details and responsibilities for the key states involved in resolving a dispute. For information on how to manage the progress of dispute states, see Managing the Dispute Process later in this guide.


After presentment, the dispute enters the initiated state. The request is reviewed and the dispute initiated with the card network as follows:

  • Depending on the reason for the dispute, Marqeta applies a provisional credit to the cardholder’s account.

  • If additional information or documentation is required, Marqeta requests this information from you.

  • You are notified when the dispute is initiated.

If the acquiring bank forwards the dispute claim to the merchant, the merchant may accept the loss or provide the additional information to refute the claim.


If the acquiring bank attempts to refute the claim, the merchant can defend the claim by submitting a representment, also known as the dispute response. The dispute then enters the representment state. For example, if a cardholder claims fraud in a card present transaction, the merchant could provide proof that the card was swiped and show that they have a copy of the receipt signed by the cardholder. The merchant has then complied with the card network requirements and is not liable.

Marqeta reviews the representment:

  • Marqeta may request additional documentation from the cardholder in order to resubmit the dispute case to the card network.

  • Marqeta resubmits the dispute case, if appropriate.

After the above actions, the information is reviewed by the card network to determine whether the cardholder or the merchant wins the dispute and returns the decision to Marqeta.


The dispute case enters the pre-arbitration state if Marqeta chooses to reach out to the acquiring bank once again after the dispute has entered representment. Marqeta may submit updated information to support the dispute.

Only relevant dispute cases assume this status.


The dispute case enters the arbitration state when the acquirer disputes a claim, and the issuer submits the case to the card network for arbitration. In arbitration, the card network decides who wins the dispute case.

Case won

If the dispute is won by the cardholder, it enters the case.won state. Marqeta completes the following actions:

  • If a provisional credit was not issued at the time when the dispute was initiated, the customer’s account is credited for the amount of the dispute.

  • If a provisional credit was issued at the time when the dispute was initiated, no further action is required.

Case lost

If the dispute is lost by the cardholder, it enters the case.lost state. Marqeta completes the following actions:

  • If a provisional credit was issued when the dispute was initiated, the provisional credit is reversed by debiting the customer’s account in the amount of the dispute.

  • If a provisional credit was not issued when the dispute was initiated, no further action is required.

Network rejected

If the card network rejects the dispute submission, the dispute enters the network.rejected state in which case the dispute amount may be written off by either the issuer or the program or resubmitted with updated details.

Written off by the issuer (internal only)

If the dispute amount is written off by Marqeta, it enters the written.off.issuer state. The dispute amount is credited to the GPA of the cardholder and Marqeta absorbs the cost. A dispute case can only transition to the written.off.issuer state from the case.lost or network.rejected states.

Written off by the program (internal only)

If the dispute is lost or rejected by the card network will be written off by the card program, it enters the written.off.program state. The dispute amount is credited to the GPA of the user or business and the Marqeta customer absorbs the cost through a debit from its program funding source. A dispute case can only transition to the written.off.program state from the case.lost or network.rejected states.

Managing the dispute process

The following sections describe how to initiate, manage, and resolve your dispute cases. Each action described in the following sections moves the dispute case through to the next transition state.

Initiating a dispute

Before you initiate a dispute, advise the cardholder to contact the merchant directly to resolve the issue. If the issue cannot be resolved, begin the dispute process by initiating a dispute case using either the Marqeta Dashboard or the /cases endpoint.

Have the cardholder complete a dispute form and submit that form with any supporting documentation that might assist in the dispute review process, such as receipts or email communication with the merchant. Incomplete dispute forms or insufficient details increase the likelihood of losing the dispute.

Once the cardholder has contacted you indicating their intention to dispute a transaction, the 30-day SLA timeline for compliance begins.

The dispute process is the same for both virtual and physical cards.

Initiating a dispute using the Marqeta Dashboard

Marqeta allows you to initiate a dispute directly from the Marqeta Dashboard. Using the Dashboard, your teams can search for specific users or transactions and initiate disputes using a streamlined dispute submission process. Transactions can be disputed if they are in either a cleared or completion state. To initiate a dispute:

  1. In the Marqeta Dashboard, go to Customers > Cardholders, and select the cardholder’s row. To search for a cardholder, select Filter.

  2. Select the Transactions tab or select the Cards tab and then Card transactions, and select the row of the transaction. To search for the transaction, select Filter.

  3. Select … at the far right of the row and select Dispute.

    The Dispute option appears only for transactions that have cleared (that is, with a transaction type of authorization.clearing or pindebit.authorization.clearing.
  4. Enter the dispute amount, the reason for the dispute, whether or not the card was compromised, and any additional comments. Attach any documentation to assist in the dispute process such as receipts, email communication with the merchant, or tracking information. Use the Additional Reason field to provide any context or dispute details that may help advance the dispute process.

  5. Once you’ve completed the form, select File Dispute to initiate the transaction dispute. Marqeta reviews the information and promptly notifies you once the dispute has been initiated. If the merchant responds to the dispute with a representment, Marqeta may request further information or documentation related to the transaction.

Initiating disputes with batch processing

If you have not integrated with the Cases API to submit dispute cases in bulk, you can use the Cases Batch Chargeback Initiation Service to submit bulk dispute cases in a .xlsx file. The file must be in Microsoft Excel 2007 or higher format and must conform to the batch file data format described below.

This service must be provisioned by request. If you would like to use this service, contact your Marqeta representative. Provisioning involves Marqeta defining an email distribution list for submitting files, as well as creating a folder structure in Box for the receipt, processing, and review of the dispute cases.

Marqeta submits any properly formatted file it receives directly to the card network, which triggers dispute initiation. The Marqeta platform receives response messages from the card network on the success or failure of the dispute initiation. Marqeta automatically compiles a log of rejected disputes, where applicable, that Marqeta resolves through other channels before responding.

The current version of the Batch Chargeback Initiation Service supports only the “Fraud” and “No Authorization” dispute types on the Visa network.

Identifying cleared transactions

A transaction must be in a settled (cleared) state to initiate a dispute. Settled transactions can be identified by the following types:

  • authorization.clearing

  • pindebit.authorization.clearing

Batch file data format

To submit a batch file, create a .xlxs file with one dispute case per row that includes the columns described in the following table. Add the column headings to the top of the file. All of the columns are required, but the columns can be in any order.

Column Header Description


Original transaction token. This must be the token from a cleared (settled) transaction, not an authorization token.


Timestamp of the original transaction. This is not required to process a dispute, but could prove vital for file grooming and manual dispute review.


Amount disputed. If the cardholder wishes to dispute only a portion of the original transaction amount, include the partial amount here along with a reason in the DISPUTE_AMOUNT_CHANGE_REASON column. You should submit disputes only for disputes greater than the card network’s $25 threshold amount.

Note: Do not include any special characters such as a currency symbol. Format: 00.00


Reason code, which can be one of the following, regardless of the card network:





Note explaining the reason for disputing an amount less than the original transaction amount. If the disputed amount is less than the original transaction amount, this reason is required by the network.

In addition to the required columns and information described above, you can include any additional columns and information that may be useful for tracking and reconciliation; however, Marqeta parses and takes action only on the required columns. Below are some suggestions for additional columns that may be useful.

Column Header Description


Name of the merchant. This may be useful for researching dispute details, and can be obtained from the authorization event type in the card_acceptor object of the Webhooks endpoint.


Any additional information that may be useful.


Identifier that is unique to the dispute. 36 char max

Monitoring dispute progress

You can monitor dispute progress using Reports in the Marqeta Dashboard, or by subscribing to chargeback events using webhooks. Your team can generate reports with information regarding the disputes you’ve submitted. To access the Chargebacks report:

  1. Log into the Marqeta Dashboard.

  2. Go to Reports in the navigation bar.

  3. Select the Transaction - Chargebacks report.

The dashboard allows you to customize your report to include multiple data fields related to the status of your transaction disputes.

For details on using webhooks, see Monitoring States Using the Webhooks Endpoint.

Resolving disputes

The following sections describe how to resolve disputes by notifying the cardholder, managing partical chargebacks,

Notifying the cardholder

Once a dispute is resolved, notify the cardholder of the outcome. Example email templates are provided below for both the case won and case lost scenarios.

Case won email template

The review of the transaction you disputed on [DATE] has been completed. We are pleased to report that the dispute has been resolved in your favor and your account has been credited for the disputed amount.

  • Dispute details: XXXXX

  • Amount of the credit to your account: XXXXX

  • Date of the credit to your account: XXXXX

Case lost email template

The review of the transaction you disputed on [DATE] has been completed. We regret to inform you that the dispute has been resolved in favor of the merchant. The provisional credit to your account, if any, has been reversed.

  • Dispute details: XXXXX

  • Original transaction amount: XXXXX

  • Amount of the provisional credit reversal adjustment to your account: XXXXX

  • Date of the reversal: XXXXX

Managing partial chargebacks

If a merchant promises a product but delivers only a portion of their transaction obligation, a cardholder may request a chargeback for the undelivered portion of the total transaction amount. If a partial chargeback is indicated, Marqeta initiates the dispute for the partial amount.

Managing provisional credits

Some dispute scenarios require that a cardholder be issued a provisional credit. However, provisional credit can be issued in any dispute scenario.

Issuing provisional credits

Deciding when to issue a provisional credit is a joint responsibility shared between you and Marqeta. It is your responsibility to conform to regulations that govern provisional credits. However, since provisional credits can be issued in any dispute scenario at your discretion, it is your responsibility to request that Marqeta issue a provisional credit.

Reversing provisional credits

If a provisional credit must be reversed, it is your responsibility to request the reversal and Marqeta’s responsibility to implement the reversal.

Reconciling provisional credits

It is your responsibility to reconcile disputes for lost cases against any funds issued to the cardholder. To do this, subscribe to the webhooks described in Monitoring States Using the Webhooks Endpoint and maintain a ledger for tracking when cardholders have been compensated, when they should be compensated, and when their provisional credit should be reversed.

Reconciling disputes

You are responsible for reconciling all disputes, regardless of provisional credit issuance. To reconcile a dispute, use the Chargebacks page in Program Dashboard. To view reports on current dispute cases, see the Settlements report in the DiVA app.


Dispute mitigation is a joint responsibility shared between you and Marqeta. Vet your cardholders and take proactive steps to prevent transactions from entering the dispute stream.

True-up transactions

A monthly “true-up” transaction adjusts the funds between cardholder bank account balances and enterprise reserve bank accounts. The “true-up” corrects for any discrepancies based on provisional or other credits issued to the customer, as well as whether or not the dispute case was won by the cardholder.

Using Marqeta APIs to manage dispute cases

The /cases and /webhooks endpoints are available for monitoring and managing dispute cases.

Managing disputes with the cases endpoint

Use the /cases endpoint to 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 case progress by retrieving information such as:

  • A list of dispute cases and their current state.

  • Information on a specific dispute case.

  • A specific dispute transition.

  • An array of all transitions related to a particular dispute case.

For details, see Managing Visa Disputes. For reference information, see Dispute Cases (Visa) in the Core API Reference.

Monitoring states using the Webhooks endpoint

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 Management.

The following additional events are also available for subscription 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.chargeback.writeoff

  • authorization.clearing.representment

  • pindebit.chargeback

  • pindebit.chargeback.completed

  • pindebit.chargeback.provisional.credit

  • pindebit.chargeback.provisional.debit

  • pindebit.chargeback.reversal

  • pindebit.chargeback.writeoff

For a detailed description of these events, see Transaction Events.

Resolution timeframes

Disputes must conform to specific resolution timeframes, which vary among card networks. Expected timelines are defined in their respective 30-day service level agreement (SLA) timelines. For the Visa SLA, see Resolution Timeframes in Managing Visa Disputes.

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.