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/or status change, a unique dispute history event with a unique eventHistoryKey is created that 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 of the card networks. To enable this, clients must create an event notification webhook:

Silverflow currently supports the following pre-dispute solutions:

Issuers may choose to start a Mastercard dispute with a collaboration request instead of a chargeback. Resolving disputes 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 collaboration request was received. No further action is required from the client and a [TBD] will be received by the client in the reconciliation details. If the collaboration request is rejected, a message is sent to the issuer to notify them that the client doesn’t have the intention 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. By enrolling a MID and associating it with RDR rules (example: apply RDR for any incoming dispute with category code 10.4 and dispute amount smaller than [x]) a merchant can effectively reduce its dispute rates. We do not facilitate onboarding of merchant MID’s with Verifi. However, any incoming disputes that have been automatically settled for the merchant through RDR are recognised 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 with getting details from the Get Reconciliation Details endpoint with type typeSpecific: FirstChargebackDMSSpecific.

This works similar to what is described above. 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 specific field for the dispute history event ( eventDetails.issuerQuestionnaire, eventDetails.elaboration). The possible 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 with 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 nomenclature) with the card networks. This is the case for all chargeback defences with the exception of 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 have been filed. If the chargeback expires, the acquirer loses the right to defend and recuperate the disputed amount.

In this case the the dispute is no longer actionable and the dispute status changes to closedLost which trigger 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 choose to acknowledge the chargeback and close it. This allows the acquirer operations team to separate the chargebacks they wants to defend from the chargebacks that are 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 trigger 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 presentments can be found in the Mastercard Chargeback Guide that 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, the processing of a chargeback response (second presentment) will lead to a funds flow (the amount that was withheld by the chargeback is returned to the acquirer).

1. Add Document

Add a document placeholder to the dispute that is to be defended (provide disputeKey as path parameter). The documentKey that is returned in the 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 trigger 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 : defenseInitiated. This dispute history event also reflect the properties of the chargeback defense.

4. Retrieve Chargeback Outcome

When the response is processed by Mastercard, the disputeStage changes to chargebackResponse and the disputeSatus changes to awaitingResponse which trigger 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 dispute amount that is 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 that govern disputes and dispute responses can be found in the “Visa Product and Service Rules : Dispute Resolution” that can be downloaded from Visa Online. We will use the terms chargeback and chargebackResponse from this point onwards because that’s the terminology on 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, the processing of a Visa category 12 or 13 chargeback response will lead to a funds flow (the amount that was withheld by the chargeback is returned to the acquirer).

1. Add Document

Add a document placeholder to the dispute that is to be defended (provide disputeKey as path parameter). The documentKey that is returned in the 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 chargeback 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 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 the creation of 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 the response is processed by Visa, the disputeStage changes to chargebackResponse and the disputeStatus changes to awaitingResponse which trigger 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 dispute amount that is returned to the acquirer due to the second presentment using the Get Reconciliation Details endpoint which will contain 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 to respond 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, the processing of 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 the processing of 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 that is to be defended (provide disputeKey as path parameter). The documentKey that is returned in the 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 10 or 11 chargeback 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 trigger 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 : defenseInitiated. This dispute history event also reflects the properties of the initiated chargeback defense.

When the response is processed by Visa, the disputeStage changes to preArbitration and the disputeSatus changes to awaitingResponse which trigger 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 disputes stage and status to:

This generates a new history event object with equivalent disputeStage and disputeStatus with 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 do not have the possibility to respond to a chargeback with a chargeback response. Therefore, the acquirer is the party that 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 is not the same thing 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 trigger the emission of a notification and the creation of a new dispute history event with disputeStage : preArbitration and disputeStatus : closedLost

The disputed amount that was 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 the pre-arbitration they can choose to acknowledge the pre-arbitration and close it.

The disputeStatus changes to closedAccepted which trigger 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.

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

Responding to a Pre-Arbitration Case Filing for both Mastercard and Visa Category 12 and 13 follows the same 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: