/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
Dispute cases
Eachcase 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
The dispute type indicates the category of a dispute, which can beFRAUD, AUTHORIZATION, POINT_OF_INTERACTION_ERROR, or CARDHOLDER_DISPUTE.
Fraud
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
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.Point of interaction error
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.Cardholder disputes
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.Dispute reasons
Reason codes indicate the rationale behind a dispute. For a list, see Dispute case reasons in the Mastercard Cases API Reference.Uploading documents
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.
Managing provisional credits
Regulation E, 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. For details on managing provisional credits using the/cases endpoint, see Managing Provisional Credits.
Closing or withdrawing a dispute
When aPOST 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.
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.
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
Resolution time frames
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.