/
10 minute read
January 28, 2022

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

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

The dispute type indicates the category of a dispute, which can be FRAUD, 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 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 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

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
Copied

Is this helpful?

Yes
No

For detailed information on processing errors, see The incorrect_transaction_code_details object on the Disputes (Visa) page in the Core API Reference.

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
Copied

Is this helpful?

Yes
No

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

Reason codes indicate the reason for a dispute. For a list, see Reason codes 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. The OPEN, 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 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

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.

  • Re-create the dispute case, if necessary.

Each of these steps are described in detail in the following sections.

Creating the dispute case

Create a dispute case by sendig 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

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

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

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

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

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

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

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

Visa dispute responses are required within a specific timeline. The Visa lifecycle proceeds differently for Allocation or Collaboration disputes as shown in following diagram.

Visa Dispute Lifecycle

Is this helpful?

Yes
No

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

Join our developer newsletter