/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 CLEARING transaction token. 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, AUTH, PROCESSING, or CONSUMER.
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.Auth
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
A processing dispute occurs when the transaction was expected, but the data or metadata is incorrect, such as the transaction amount or account number.Consumer
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.Dispute questionnaires
When a cardholder opens a Processing or Consumer dispute, they are presented with a corresponding set of questions. These are exposed as eitherPROCESSING or CONSUMER in the dispute_reason field. Visa provides decision trees that require answers to certain questions if other questions are answered by the cardholder or have a certain value.
Processing errors
For processing errors, the questionnaire asks the cardholder for details about what is incorrect about the transaction. As the cardholder moves through the questionnaire, the specific questions presented depend on the answers provided. The decision tree for processing errors is shown below:JSON
Consumer disputes
For consumer disputes, the questionnaire asks the cardholder for details about the dispute. As the cardholder moves through the questionnaire, the specific questions presented depend on the answers provided. The decision tree for consumer disputes is shown below:JSON
Dispute reasons
Reason codes indicate the reason for a dispute. For a list, see The dispute_details.dispute_reason field in the Visa Cases API Reference.Uploading documents
Cardholders must attach necessary documents to support their claim. Visa requires that supporting documents be uploaded only for Consumer disputes. TheOPEN, OPEN_WITH_ACTION_REQUIRED, and READY states where documents can be uploaded.
About associated transactions
When an additional transaction or credit is attached to a transaction dispute, the dispute can become invalid at the card network, requiring additional steps to transition the dispute case. As part of the dispute process, Marqeta proactively identifies transactions such as a credit, reversal, or adjustment that may be associated with the disputed transaction and could render the dispute invalid. Some transactions may appear to be but are not associated with a transaction. These transactions must be identified before submitting them to the card network. If a transaction dispute that has an associated transaction is submitted to the card network, it will be invalidated, requiring the dispute to be resubmitted.Submitting a dispute
To submit a dispute and check for and resolve associated transactions, follow these steps:- Create the dispute case.
- If there are possible associated transactions, get the list.
- Submit the batch of associated transactions.
-
Transition the dispute case to
READY. -
Transition the dispute case to
CHARGEBACK_INITIATED. - Update the associated transactions, if necessary.
- Close or withdraw a dispute.
- Recreate the dispute case, if necessary.
Creating the dispute case
Create a dispute case by sending aPOST request to the /cases endpoint. The associated_transaction_selection_required field of the dispute_details object indicates whether there are any transactions that may be associated with the current dispute. If so, a list of those transactions is downloaded, the associatedTransactionSelectionRequired field is set true, and the case is put into the OPEN_WITH_ACTION_REQUIRED state.
Transitioning the dispute case to READY
After the required information has been provided, transition the dispute case toREADY by sending a POST request to the /cases/{token}/transitions endpoint with the action field set to REVIEW, Marqeta determines if there are any associated transactions for the dispute case. If there are associated transactions, the transition to READY will fail because the associated transactions must be resolved and the dispute case will be moved to the OPEN_WITH_ACTION_REQUIRED state.
Getting a list of potentially associated transactions
Send aGET to the /cases/{case_token}/associated_transactions endpoint to get a list of transactions that are potentially associated with the given dispute case. For details, see List Associated Transactions in the Disputes API (Visa) reference.
Submitting a batch of associated transactions
To submit a list to the card network indicating which transactions are associated with a dispute case, send aPOST to the /cases/{case_token}/associated_transactions/selection endpoint with the details of each transaction. For details, see Submit a batch of associated transactions in the Cases API (Visa) reference.
Sending a dispute case to the card network
A dispute case is sent to the card network when the dispute case is transitioned to theCHARGEBACK_INITIATED state. Once the dispute case is submitted to the card network, it moves through the card network dispute transitions until the dispute is resolved by the card network, and can then be closed.
Resubmitting associated transactions
When you transition a dispute case toREADY or CHARGEBACK_INITIATED by calling the /cases/{token}/transitions endpoint with the state set to READY, Marqeta determines if there are any new associated transactions for the dispute case. If there are any new associated transactions, the transition to READY will fail because the associated transaction must be resolved and the dispute case will be moved to the OPEN_WITH_ACTION_REQUIRED state.
To resubmit the associated transactions after they have been submitted to the card network, send a PUT request to the /cases/{token}/associated_transactions/selection endpoint. If the associated transaction does not equal the total amount, resubmit the dispute for the partial amount. For details, see Update submitted associated transactions in the Disputes API (Visa) reference.
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 credit 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 stateTo set to CLOSE and action WITHDRAW_AND_CLOSE with a reason_code of 40, Marqeta determines if 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 the dispute case state 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 the dispute case is in the following the OPEN, READY, or OPEN_WITH_ACTION_REQUIRED state. The dispute case can only move to CLOSED with a WITHDRAW_AND_CLOSE action. If the transition is to CLOSED with WITHDRAW_AND_CLOSE and the dispute case state is not in the previously stated valid states, the transition will fail.
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 in order 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 timeframes
Visa dispute responses are required within a specific timeline. The Visa lifecycle proceeds differently for Allocation or Collaboration disputes as shown in following diagram.- Prearbitration: 30 days
- Prearbitration response: 30 days
- Arbitration response: 10 days
- Dispute response: 30 days
- Prearbitration: 30 days
- Prearbitration response: 30 days
- Arbitration response: 10 days
Reporting fraud
The Visa network requires issuers and programs to report fraud to the card network regardless of the amount. Whenever a cardholder reports fraud, a subsequent fraud report must be created with the card network. Noncompliance with card network rules results in fines and suspension of the ability to process chargebacks. Fraud reports can be submitted from the Disputes dashboard or using the/cases endpoint.
To submit a fraud report using the /cases endpoint, send a POST /cases request with FRAUD_REPORT as the dispute_reason in the dispute_details_dispute_reason field and the required information in the [fraud_category_type_dispute_details](/disputes-visa/#_The fraud_category_type_dispute_details_object) object. For an example, see Sample request body.
Rejection from the Visa network for Compelling Evidence 3.0-enabled merchants
In response to the growth of digital commerce, Visa Compelling Evidence 3.0 expands the list of compelling evidence you can use to help invalidate certain customer disputes. Compelling evidence is proof the cardholder participated in the transaction, received the goods or services, or benefitted from the transaction. This determines how much and the types of evidence you must submit to resolve customer disputes before submitting a dispute. If the merchant is enabled for Compelling Evidence 3.0, and there are at least two historic transactions that meet the Remedy Prior Undisputed transaction criteria, rejection from the card network can happen at two points in the dispute workflow:- Pre-dispute
- Post-dispute
Pre-dispute rejects
If a rejection happens in this case, one of the following errors are generated when you attempt to initiate the dispute with the card network. These disputes move toOPEN_WITH_ACTION_REQUIRED. For the /cases endpoint, the following error messages are captured in the card network reject webhooks:
| Error Code | Message | Meaning and Expected User Action |
|---|---|---|
| E-900003544 | Dispute is invalid as prior transactions were detected for this merchant with the same data elements (IP Address, Device ID, etc.). Neither of these transactions were reported as fraud activity to Visa. This transaction will not be counted as a fraud activity. | Remedy Prior Undisputed Transactions conditions have been met—that is, the merchant has signed up for Remedy Prior Undisputed transactions and there are at least two historical transactions (120-365 days old), which establishes the undisputed transaction history between the merchant and the cardholder. There are no dispute rights on this transaction. You can mark these disputes as Program Write-off or Case Lost. If you have enough evidence that the dispute was rejected incorrectly, you can request an exception review, with an additional fee. |
| E-900003545 | This dispute is still processing and please resubmit. | Indicates that the merchant has signed up for Compelling Evidence 3.0 and Visa is attempting to retrieve the Compelling Evidence 3.0 data from the merchant. You can attempt to resubmit these disputes after a brief waiting period. |
| E-900003543 | Dispute is invalid as it was qualified under the Visa Remedy criteria. This transaction will not be counted as a fraud activity. | Appears if you attempt to raise a 10.4 dispute against a transaction that already had a fraud dispute reject due to Compelling Evidence 3.0 (E-900003544). The chargeback cannot be initiated with the card network. |
Post-dispute rejects
Merchants can provide Compelling Evidence 3.0 data during prearbitration of a 10.4 dispute. In this case, the dashboard displays the prearbitration reason as RE (Remedy Prior Undisputed transaction), along with historic data that establishes undisputed transaction history between the merchant and the cardholder. You can either accept liability or respond to the prearbitration after reviewing the Compelling Evidence 3.0 data. If you decline prearbitration, sufficient evidence should be provided to dispute the Compelling Evidence 3.0 data.Criteria for Compelling Evidence 3.0
Compelling Evidence 3.0 rules require that merchants share data that helps establish a historical footprint of previous purchase history by sharing two previous transactions that meet certain criteria, including:- The transactions must be at least 120 days old (calculated from the dispute date).
- The transaction must have no active fraud report.
- The transaction must have no active fraud dispute.
- At least two of the core data elements (user ID, IP address, shipping address, device ID/fingerprint) match between prior transactions and the disputed transaction, and one of the two must be either the IP address or device ID/fingerprint.
- Transactions must be from the same merchant.
- An item description must be provided for the transactions.