Skip to main content

​
Dispute

When a cardholder disputes a settled transaction, because the goods never arrived, the amount does not match what they paid, or the purchase was never theirs to begin with, you need a clear path to take the dispute to the card network, recover the money and keep the user informed. DCS is a licensed issuer; the final ruling on a dispute rests with the card network (Visa/Mastercard) under its own rules, and DCS handles intake, evidence and recovery between the network and the partner.
Scope of this page: disputes are handled entirely through operational and manual channels for now (there is no self-service dispute API yet). This page covers the paths available today, namely raising an operations ticket, containing fraud losses by freezing and replacing the card, and the automatic recovery of a merchant refund, and it spells out what information you need to provide through which channel.

​
First, tell three things apart: refund, reversal and dispute

The three are easily lumped together, but they are entirely different events in the money flow and follow different paths: The deciding question: you only enter the dispute process when the merchant will not refund, or when the cardholder never made the transaction (fraud). If the merchant has already refunded, the money returns to your balance account automatically as an INCOMING record, so do not raise a dispute on top of it: recovering twice, once from the merchant and once through a dispute, is flagged as abnormal by the card network.
For how refunds and reversals land in the transaction records and in authorization and settlement, see Authorization and settlement scenarios (scenario 9, forced refund, partial reversals and so on) and Transaction records (direction=INCOMING).

​
Available today: the operational path for fraud and disputes

When a cardholder raises a dispute with you, work through the operational channels in the order below.

​
The user reports fraud (an unauthorized transaction)

Who does what
  • You: (1) freeze the affected card immediately to contain the loss; (2) reissue a new card if needed; (3) gather the evidence (transaction ID, last four digits of the card number, merchant details, a description of the dispute) and submit a dispute intake request to DCS through the operational channel.
  • DCS: takes the case, raises the dispute (chargeback) with the card network, follows the ruling and reports the recovery and progress back to you.
Step 1: freeze the card immediately (the only self-service action available to you today for containing the loss)
Freezing and unfreezing are the same freeze endpoint, told apart by the freeze boolean; there is no separate unfreeze or unblock endpoint. For card operations in general, see Card management.
Step 2: reissue a new card (in a fraud case the original card should be invalidated and replaced, so the cardholder is not left exposed on a compromised card). For card replacement, see Card management: replacing a card. Step 3: submit the dispute intake request, through the operational channel agreed with DCS (customer success or an operations ticket). The minimum information required: the transaction ID (transactionId), the last four digits of the card number, the merchant details, the dispute category with a written description, and any supporting evidence files. Once DCS takes the case it raises the dispute with the card network and follows the outcome.

​
The merchant owes a refund but has not paid it, or the refund is overdue

First confirm whether the merchant has actually issued a refund (has the INCOMING record been credited?). If the merchant refuses to refund, or the refund never materialises, then submit a dispute along the operational path above.

​
How the money from a dispute reaches you

Once the card network rules in favour of the partner (the cardholder), the recovery is credited to your balance account:
  • It appears in the reconciliation file as a direction=INCOMING entry carrying category: CHARGEBACK, which marks it as a dispute transaction and lets you identify it programmatically; it is delivered through the daily reconciliation files.
  • The recovery is credited as a direction=INCOMING entry to the partner’s balance account; using the dispute transaction Id you can trace it back to the original transaction and attribute the credit to the specific end user and dispute.
Reconciliation tip: category: CHARGEBACK is what tells a dispute recovery apart from an ordinary merchant refund. Still record the corresponding transaction ID while you follow the dispute through the operational channel, as an auxiliary cross-check.

​
A walkthrough of one fraud case

Here is the handling path above on a real timeline. The case: late at night, a cardholder reports an 89.99 USD purchase in your app that they never made; the transaction has already settled. Two lessons:
  • The D0 freeze defines the loss boundary: the ruling takes weeks, but further spending on the compromised card is blocked from the moment you freeze it — this is the only minute-critical step in the whole flow, and the only one you can complete through a self-service API today.
  • Claim the recovery by category: CHARGEBACK: the dispute credit carries the category: CHARGEBACK marker in the reconciliation file, so you can identify it programmatically and trace it back to the original transaction by the dispute transaction Id. The transactionId and expected amount you record on D1 serve as an auxiliary cross-check.

​
Practical reminders when submitting a dispute

To improve your odds of a case being accepted and won, keep the following in mind:
  • A dispute can normally only be raised on a transaction that is settled and has a non-zero amount; pending transactions and zero-amount (verification) transactions cannot be disputed.
  • Card network disputes have a deadline (usually 120 days from the transaction date), and the closer you get to it the more likely the case is thrown out, so submit early.
  • Only one dispute at a time should be open on a given transaction, so do not submit twice.
  • If the merchant refunds directly while the dispute is running, the money returns to your balance account automatically as an INCOMING record, and there is no need to pursue the dispute any further.

​
Next steps