> ## Documentation Index > Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt > Use this file to discover all available pages before exploring further. # Dispute Handling > The paths available today, and the information they require, when a cardholder disputes a settled transaction (goods not received, wrong amount, fraudulent use). ## 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: | Event | Who initiates it | How it shows up in DCS | Dispute process needed | | ------------------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------- | | **Refund / return** | The merchant refunds voluntarily | A transaction record with `direction=INCOMING` credits the money automatically, with no action from the partner | No | | **Reversal** | The merchant or the card network reverses the original authorization | The hold is released at the authorization stage plus an INCOMING record; handled automatically | No | | **Dispute / chargeback** | The cardholder disputes a settled transaction | Handled through operational and manual channels (no self-service API yet) | Yes | **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](./transactions/auth-and-settlement) (scenario 9, forced refund, partial reversals and so on) and [Transaction records](./transactions/transaction) (`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) ``` POST /open-api/card/v1/freeze ``` | Parameter | Type | Required | Description | | -------------- | ------- | -------- | -------------------------------------------------------------------------- | | `cardId` | String | Yes | Card ID, maximum length 50 | | `freeze` | Boolean | Yes | `true` freezes the card (contains the loss) / `false` unfreezes it | | `freezeReason` | String | Yes | Reason for the freeze, maximum length 20, such as `USER_FREEZE` / `NORMAL` | > 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](./cards/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](./cards/card-management). **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. | Time | Event | What you do | With what | | -------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | D0, late night | The user reports the fraud | Verify the record: find the settled `direction=OUTGOING` transaction, note its `transactionId` and the merchant details | Transaction records / daily transaction report | | D0, late night | Stop the bleeding | Freeze the affected card | `POST /open-api/card/v1/freeze`, `freeze=true`, `freezeReason=USER_FREEZE` | | D1 | Restore card access | Invalidate the old card and issue a replacement (a compromised card should never be unfrozen for reuse) | [Card management · replacement](./cards/card-management) | | D1 | Submit the dispute | Assemble the minimum evidence pack — `transactionId`, last four digits, merchant name, dispute category and description, supporting files — and submit through the agreed operational channel | Operations ticket / customer success channel | | After D1 | DCS takes over | DCS raises the chargeback with the card network and relays progress through the operational channel | — | | Weeks later (ruling) | You win the dispute | A `direction=INCOMING` credit carrying `category=CHARGEBACK` appears in one day's reconciliation file; that marks it as a dispute recovery, and the dispute transaction Id traces it back to the original transaction, this user and this dispute | Daily transaction report | 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 * Understand how refunds and reversals land in the money flow automatically: [Authorization and settlement scenarios](./transactions/auth-and-settlement) * Reconcile INCOMING recoveries entry by entry: [Transaction records](./transactions/transaction) * The freeze and replacement operations that contain a fraud loss: [Card management](./cards/card-management) * The webhook event types available today: [Webhook events and data structures](./webhooks/events-and-schema)