Managing Visa 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 Visa card 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 (Visa) in the Core API Reference.
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, AUTH, PROCESSING, or CONSUMER.
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.
Auth
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
Copy section link
A processing dispute occurs when the transaction was expected, but data or metadata is incorrect, such as the transaction amount or account number.
Consumer
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.
Dispute questionnaires
Copy section link
When a cardholder opens a Processing or Consumer dispute, they are presented with a corresponding set of questions.
These are exposed as either PROCESSING 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
Copy section link
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:
For detailed information on processing errors, see The processing_error_type_dispute_details object on the Disputes (Visa) page in the Core API Reference.
Consumer disputes
Copy section link
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:
For detailed information on consumer disputes, see The consumer_dispute_type_dispute_details object on the Disputes (Visa) page in the Core API Reference.
Reason codes
Copy section link
Reason codes indicate the reason for a dispute. For a list, see Reason codes in the Visa Cases API Reference.
Uploading documents
Copy section link
Cardholders must attach necessary documents to support their claim. Visa requires that supporting documents be uploaded only for Consumer disputes. The OPEN, OPEN_WITH_ACTION_REQUIRED, and READY states where documents can be uploaded.
About associated transactions
Copy section link
When an additional transaction or credit is attached to a transaction dispute, the dispute can become invalid at the 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 network. If a transaction dispute that has an associated transaction is submitted to the network, it will be invalidated, requiring the dispute to be resubmitted.
Submitting a dispute
Copy section link
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.
Each of these steps are described in detail in the following sections.
Creating the dispute case
Copy section link
Create a dispute case by sending a POST request to the /cases endpoint.
The associated_transaction_selection_required field of the dispute_details object indicates whether there are 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
Copy section link
After the required information has been provided, transition the dispute case to READY 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
Copy section link
Send a GET 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
Copy section link
To submit a list to the network indicating which transactions are associated with a dispute case, send a POST 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 network
Copy section link
A dispute case is sent to the network when the dispute case is transitioned to the CHARGEBACK_INITIATED state. Once the dispute case is submitted to the network, it moves through the network dispute transitions until the dispute is resolved by the network, and can then be closed.
Resubmitting associated transactions
Copy section link
When you transition a dispute case to READY 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 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.
Closing or withdrawing a dispute
Copy section link
When a POST 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
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
Visa dispute responses are required within a specific timeline. The Visa lifecycle proceeds differently for Allocation or Collaboration disputes as shown in following diagram.
The following describes the expected timelines from the Visa SLA for responses to an allocation or collaboration dispute.
Fraud and authorization (allocation):
-
Prearbitration: 30 days
-
Prearbitration response: 30 days
-
Arbitration response: 10 days
Processing errors and consumer disputes (collaboration):
-
Dispute response: 30 days
-
Prearbitration: 30 days
-
Prearbitration response: 30 days
-
Arbitration response: 10 days
Reporting fraud
Copy section link
The Visa network requires issuers and programs to report fraud to the network regardless of the amount.
Whenever a cardholder reports fraud, a subsequent fraud report must be created with the network.
Noncompliance with 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 object.
For an example, see Sample request body.
Rejection from the Visa network for Compelling Evidence 3.0-enabled merchants
Copy section link
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 network can happen at two points in the dispute workflow:
-
Pre-dispute
-
Post-dispute
Pre-dispute rejects
Copy section link
If a rejection happens in this case, one of the following errors are generated when you attempt to initiate the dispute with the network.
These disputes move to OPEN_WITH_ACTION_REQUIRED.
For the /cases endpoint, the following error messages are captured in the 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 network. |
Post-dispute rejects
Copy section link
Merchants can provide Compelling Evidence 3.0 data during pre-arbitration of a 10.4 dispute. In this case, the dashboard displays the pre-arbitration 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 pre-arbitration after reviewing the Compelling Evidence 3.0 data. If you decline pre-arbitration, sufficient evidence should be provided to dispute the Compelling Evidence 3.0 data.
Criteria for compelling evidence 3.0
Copy section link
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.
For details and exceptions to these guidelines, see the Visa FAQ.