Dispute Handling

The dispute object covers the dispute process across different stages, which means there is one dispute with one unique disputeKey, but the disputeStage and disputeStatus change as the dispute plays out. For every stage and status change, a unique dispute history event with a unique eventHistoryKey maps to that event. Certain events coincide with or trigger a fund flow and an associated reconciliationDetail; others do not.

The different card networks use overlapping terminology for their dispute processes, but there are differences. For the sake of clarity, we have added a table with definitions and how they map to our API:

Silverflow will automatically notify clients on an endpoint specified by the client whenever we receive a new fraud notification, new dispute, or updates to an existing dispute status from any card network. To enable this, clients must create an event notification webhook:

Silverflow currently supports the following pre-dispute solutions:

Issuers may start a Mastercard dispute with a collaboration request instead of a chargeback. Resolving conflicts with the collaboration process before a chargeback is issued can be beneficial because it reduces the chargeback ratios for merchants, which helps the merchant (and the acquirer) avoid fines.

Our API currently supports two responses to an incoming collaboration request: if the collaboration request is accepted, a message is sent to Mastercard to refund the transaction for which the request was received. No further action is required from the client. If the collaboration request is rejected, a message is sent to the issuer to notify them that the client doesn’t intend to refund the transaction. In most cases, this will cause the issuer to file a chargeback for the same transaction.

Accept the Mastercard collaboration request using the disputeKey as the oath parameter:

This will trigger Mastercom to trigger a refund with an associated reconciliation detail.

Reject the collaboration request using the disputeKey as the path parameter.

Visa provides Rapid Dispute Resolution to merchants that have enrolled their BIN and MID combination with Visa through Verifi. A merchant can effectively reduce its dispute rates by enrolling a MID and associating it with RDR rules (for example, apply RDR for any incoming dispute with category code 10.4 and dispute amount smaller than [x]). We do not facilitate the onboarding of merchant MIDs with Verifi. However, any incoming disputes that have been automatically settled for the merchant through RDR are recognized by us and will lead to the following:

Visa Rapid Dispute Resolution Reconciliation Details

Issuers can dispute a transaction by filing a chargeback with the card networks based on the card network dispute rules. Chargebacks lead to a financial flow (the disputed amount is withheld from the acquirer settlement) and an information exchange (the reason and evidence for the disputed transaction). The incoming chargeback event generates a new dispute object with disputeStage : chargeback and disputeStatus: received, a related history event object with disputeStage: chargeback, disputeStatus: received and event specific eventDetails and a reconciliation detail object with typeSpecific: FirstChargebackDMSSpecific.

Get notified about new disputes or updates to a dispute status on a specified URL with a disputeKey (only if an event notification webhook for disputes exists).

Get the dispute from the Silverflow API using the disputeKey as a path parameter /disputes/{disputeKey}.

Get Mastercard Dispute

Get Mastercard Dispute Event History

Get the dispute event history using the disputeKey as a path parameter /disputes/{disputeKey}/eventHistory and get the dispute history event for the received chargeback using the eventHistoryKey of the chargeback event /disputes/eventHistory/{eventHistoryKey}.

In the above examples, there are a few Mastercard-specific values for the dispute object ( reason.code, reason.description, reason.category ) and a specific field for the dispute history event (eventDetails.messageText). The possible card network-specific values for these fields can be found in the Mastercard Chargeback Guide.

You can reconcile the disputed amount caused by the chargeback based on the reconciliation details by getting details from the Get Reconciliation Details endpoint with type typeSpecific: FirstChargebackDMSSpecific.

This works similarly to what is described above. You can get notified about new disputes or updates to a dispute status on a specified URL with a disputeKey (only if an event notification webhook for disputes exists).

Get the dispute from the Silverflow API using the disputeKey as a path parameter /disputes/{disputeKey}.

Get Visa Dispute

Get Visa Dispute Event History

Get the dispute event history using the disputeKey as a path parameter GET/disputes/{disputeKey}/eventHistory. Get the dispute history event for the received chargeback using the eventHistoryKey of the chargeback event GET/disputes/eventHistory/{eventHistoryKey}.

In the above examples, there are a few Visa-specific values for the dispute object ( reason.code, reason.description, reason.category ) and a couple of particular fields for the dispute history event ( eventDetails.issuerQuestionnaire, eventDetails.elaboration). The card network-specific values for these fields can be found in the Visa Chargeback Guide.

You can reconcile the disputed amount caused by the chargeback based on the reconciliation details by getting details from /reports/reconciliationDetails endpoint with type "typeSpecific" : "FirstChargebackDMSSpecific"

Acquirers can respond to incoming chargebacks in three different ways:

When defending a chargeback, the acquirer files a chargebackResponse (“Second Presentment” in Mastercard nomenclature, “Dispute Response” in Visa terminology) with the card networks. This is the case for all chargeback defenses, except Visa category 10 and category 11 disputes, for which a pre-arbitration must be filed if the acquirer wishes to defend against the chargeback. We will consider all these cases separately.

All incoming chargebacks have an expiry date (actionDueDate) by which a response must be filed. The acquirer loses the right to defend and recuperate the disputed amount if the chargeback expires.

In this case, the dispute is no longer actionable, and the dispute status changes to closedLost, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and the creation of a new dispute history event with disputeStage: chargeback and disputeStatus: closedLost.

If the acquirer does not wish to fight the chargeback, they can acknowledge and close it. This allows the acquirer operations team to separate the chargebacks they want to defend from those not worth their time.

Accept liability for the dispute using the disputeKey as a path parameter while it has disputeStage: chargeback and disputeStatus: received:

The disputeStatus changes to closedAccepted, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and the creation of a new dispute history event with disputeStage: chargeback and disputeStatus: closedAccepted

An acquirer may choose to defend against a Mastercard chargeback depending on its second presentment rights. The rules that govern chargebacks and second presentations can be found in the Mastercard Chargeback Guide, which can be downloaded from Mastercard Connect. A Mastercard chargeback response (or second presentment) requires an acquirer to provide evidence to the issuer to prove the chargeback was invalid. After it has been submitted to Mastercard, processing a chargeback response (second presentment) will lead to a funds flow (the amount withheld by the chargeback is returned to the acquirer).

1. Add Document

Add a document placeholder to the dispute to be defended (provide disputeKey as a path parameter). The documentKey returned in response to this call will be used in the next step to upload a document.

2. Upload Document

Upload the evidence to the placeholder on the dispute using the documentKey as a path parameter.

3. Defend Chargeback

Defend against the Mastercard chargeback using the disputeKey of the dispute to which the evidence was just uploaded as a path parameter and by providing the right disputeResponseReasonId and messageText (based on the Mastercard Chargeback Guide).

For the specific values for the disputeResponseReasonId and the messageText please refer to the Mastercard Chargeback Guide.

The disputeStatus changes to defenseInitiated, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and creates a new dispute history event with disputeStage: chargeback and disputeStatus: defenseInitiated. This dispute history event also reflects the properties of the chargeback defense.

4. Retrieve Chargeback Outcome

When Mastercard processes the response, the disputeStage changes to chargebackResponse, and the disputeSatus changes to awaitingResponse, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and the creation of a new dispute history event with disputeStage: chargeback and disputeStatus: awaitingResponse

Reconcile the disputed amount returned to the acquirer due to the second presentment using the GET/reports/reconciliationDetails endpoint, which will contain the additional fields in typeSpecific: "SecondPresentmentDMSSpecific."

An acquirer may choose to defend against a Visa category 12 (Processing Error) or 13 (Consumer) dispute, depending on its dispute response rights. The rules governing disputes and dispute responses can be found in the “Visa Product and Service Rules: Dispute Resolution” downloaded from Visa Online. From now on, we will use the terms chargeback and chargebackResponse because that’s the terminology used in the Silverflow API. A Visa Category 12 or 13 chargeback requires an acquirer to provide evidence to the issuer to prove the chargeback was invalid. After it has been submitted to Visa, processing a Visa category 12 or 13 chargeback response will lead to a funds flow (the amount withheld by the chargeback is returned to the acquirer).

1. Add Document

Add a document placeholder to the dispute to be defended (provide disputeKey as a path parameter). The documentKey returned in response to this call will be used in the next step to upload a document.

2. Upload Document

Upload the evidence to the placeholder on the dispute using the documentKey as a path parameter.

3. Defend Chargeback

Defend against the Visa category 12 or 13 chargebacks using the disputeKey of the dispute to which the evidence was just uploaded as a path parameter and by providing the right disputeResponseReasonId, disputeSubResponseReasonId, creditOrReversalDetail, and elaboration (based on the Visa dispute rules) in the request body.

The creditOrReversalDetail is mandatory for Visa disputes when the defense response reason is Credit or reversal processed and represents the credit or reversal details.

4. Retrieve Chargeback Outcome

The disputeStatus changes to defenseInitiated, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and creates a new dispute history event with disputeStage: chargeback and disputeStatus: defenseInitiated. This dispute history event also reflects the properties of the initiated chargeback defense.

When Visa processes the response, the disputeStage changes to chargebackResponse, and the disputeStatus changes to awaitingResponse, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and the creation of a new dispute history event with disputeStage chargeback and disputeStatus: awaitingResponse.

Reconcile the disputed amount returned to the acquirer due to the second presentment using the Get Reconciliation Details endpoint, containing the additional fields in typeSpecific: SecondPresentmentDMSSpecific.

An acquirer may choose to defend against a Visa category 10 (Fraud) or 11 (Authorization) chargeback, depending on its response rights. Visa eliminated the possibility of responding to a category 10 or 11 dispute with a dispute response, so if an acquirer wishes to defend, they immediately have to escalate to a pre-arbitration case filing. This is called the “Allocation Flow". A Visa Category 10 or 11 chargeback requires an acquirer to provide evidence to the issuer to prove the chargeback was invalid. After this evidence has been submitted to Visa, processing a pre-arbitration in response to a Visa category 10 or 11 chargeback will not lead to an immediate funds flow (as is the case with processing a chargeback response for category 12 and 13 chargebacks). The case filing needs to come to a conclusive end before any potential fund flows will be triggered, depending on the outcome of the dispute.

1. Add Document

Add a document placeholder to the dispute to be defended (provide disputeKey as a path parameter). The documentKey returned in response to this call will be used to upload a document in the next step.

2. Upload Document

Upload the evidence to the placeholder on the dispute using the documentKey as a path parameter.

3. Defend Chargeback

Defend against the Visa category 10 or 11 chargebacks using the disputeKey of the dispute to which the evidence was just uploaded as a path parameter and by providing the right disputeResponseReasonId, disputeSubResponseReasonId , creditOrReversalDetail, and elaboration based on the Visa dispute rules in the request body.

4. Retrieve Chargeback Outcome

The disputeStatus changes to defenseInitiated, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and creates a new dispute history event with disputeStage: chargeback and disputeStatus: defenseInitiated. This dispute history event also reflects the properties of the initiated chargeback defense.

When Visa processes the response, the disputeStage changes to preArbitration, and the disputeSatus changes to awaitingResponse, which triggers the emission of a notification (only if an event notification webhook for disputes exists) and the creation of a new dispute history event with disputeStage: preArbitration and disputeStatus: awaitingResponse.

Disputes that can’t be resolved with a chargeback or chargeback response can be escalated to pre-arbitration. The pre-arbitration stage gives the acquirer and the issuer one last chance to resolve the dispute before the card networks intervene with a ruling at the arbitration stage (which can be costly). The incoming pre-arbitration changes an existing dispute stage and status to:

This generates a new history event object with equivalent disputeStage and disputeStatus and event-specific eventDetails. At the pre-arbitration stage, fund flows are only triggered once the dispute has played out (disputeStatus: closedWon,closedLost, closedAccepted).

Note: Because of the Visa Allocation flow, Visa category 10 and 11 disputes cannot respond to a chargeback with a chargeback response. Therefore, the acquirer initiates pre-arbitration for those dispute categories, and the issuer must respond with a pre-arbitration response.

Acquirers can respond to incoming pre-arbitration case filings in three different ways:

When choosing to defend against an incoming pre-arbitration case filing, the acquirer rejects it. Note that this is not the same as escalating to an Arbitration case filing; it will now be up to the Issuer to determine whether they want to escalate to Arbitration.

All incoming pre-arbitrations have an expiry date (actionDueDate) by which a response must have been filed. If the pre-arbitration expires, the acquirer loses the right to defend, and the funds are returned to the Issuer.

The dispute is no longer actionable, and the dispute status changes to closedlost, which triggers the emission of a notification and the creation of a new dispute history event with disputeStage: preArbitration and disputeStatus: closedLost

The disputed amount is returned to the acquirer after the chargebackResponse is returned to the Issuer. The amount can be reconciled using the reconciliation details and will be visible under typeSpecific: "PreArbitrationDMSSpecific".

If the acquirer does not wish to fight pre-arbitration, they can acknowledge and close it.

The disputeStatus changes to closedAccepted, which triggers the emission of a notification and the creation of a new dispute history event with disputeStage: preArbitration and disputeStatus: closedAccepted

The disputed amount that was returned to the acquirer after the chargebackResponse is returned to the Issuer and the amount can be reconciled using the reconciliation details.

Depending on its response rights, an acquirer may choose to defend against an incoming Mastercard pre-arbitration case filing. By defending, the Acquirer rejects the incoming pre-arbitration and signals to the Issuer that they are unwilling to accept liability. The Acquirer can motivate this decision using additional evidence and a memo.

Responding to a Pre-Arbitration Case Filing for Mastercard and Visa Category 12 and 13 follows steps 1-4 as listed above in the section covering Defending a Chargeback. In terms of status change, this will be reflected as follows:

For Visa, category 10 and 11 disputes, the acquirer is the side that can file a pre-arbitration, and therefore, the pre-arbitration response is only received: