Managing Mastercard Disputes (Beta)
Note
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.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. For detailed reference information, see Disputes (Mastercard) in the Core API Reference.
Dispute cases
Copy section link
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.
Dispute categories
Copy section link
The dispute type indicates the category of a dispute, which can be FRAUD, AUTHORIZATION, PROCESSING_ERROR, or CONSUMER_DISPUTES.
Fraud
Copy section link
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.
Authorization
Copy section link
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.
Processing error
Copy section link
A processing error dispute occurs when the transaction was expected, but data or metadata is incorrect, such as the transaction amount or account number.
Consumer disputes
Copy section link
A consumer 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.
Reason codes
Copy section link
Reason codes indicate the reason for a dispute. For a list, see Reason codes in the Mastercard Cases API Reference.
Uploading documents
Copy section link
Cardholders must attach necessary documents to support their claim. Mastercard requires that supporting documents be uploaded for all dispute claims. The OPEN, OPEN_WITH_ACTION_REQUIRED, and READY states where documents can be uploaded.
Monitoring states using the Webhooks endpoint
Copy section link
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.
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.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.
Resolution timeframes
Copy section link
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.
-
-
Second presentment (representment): 45 days
-
Arbitration chargeback: 30 days