> ## 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.
# Transaction Issues and Disputes
> Explains how to handle a disputed transaction in the DeCard-Managed model: how to tell a refund or reversal (credited automatically by the system) apart from a dispute or chargeback (handled through the operations channel), how to contain losses from unauthorized use by freezing the card, and how dispute proceeds get back to the user's independent balance.
## 📄 Guide
When a cardholder challenges a transaction, whether the goods never arrived, the amount does not match, or the transaction was never initiated by them at all, you need a clear handling path: contain the loss first, then work out whether this is a refund or reversal that will be credited automatically, or a chargeback that has to go through the dispute process. DCS is a card issuer regulated by the Monetary Authority of Singapore (MAS); the final ruling on a dispute is made by the card network (Visa/Mastercard) under its own rules, and DCS sits between the card network and the integrator to take in the case, present the evidence, and pass the recovered funds back.
**Current capability (read this first)**: the DeCard-Managed model currently has **no self-service dispute or chargeback API**, and no refund or reversal endpoint that an integrator can call. Disputes are submitted and followed up through the **operations channel**, and a self-service dispute API is still on the roadmap. This page describes the paths that genuinely exist today: automatic crediting of refunds and reversals, loss containment by freezing the card, and dispute submission through operations.
***
## First, separate three things: refunds, reversals, and disputes
These three are often lumped together, but in the DeCard-Managed funds chain they are entirely different events with different handling paths. Note that **refunds and reversals are read-only transaction classifications** credited automatically by the system; they are **not** refund or reversal endpoints that an integrator can call:
| Event | Who initiates it | How it appears in the DeCard-Managed model | Dispute process needed |
| :-------------------------- | :------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------- |
| **Refund / return** | The merchant refunds voluntarily | Card transaction `authType=REFUND` (for QR payments, `transType=REFUND`/`REFUND_PART`); appears as a credit on the user's independent balance (`free` increases) and is handled automatically by the system | No |
| **Reversal / cancellation** | The merchant or the card network reverses the original authorization | Card transaction `authType=REVERSAL` (for QR, `transType=REVERSAL`); the hold is released at the authorization stage and the balance is credited, handled automatically by the system | No |
| **Dispute / chargeback** | The cardholder challenges the transaction | No self-service API exists; currently submitted through the **operations channel** | Yes |
> The `EXPEND` (purchase), `REFUND` (return), and `REVERSAL` (purchase reversal) values above are **read-only classification enums** of the `authType` field on the card transaction endpoint (on the QR payment side, the corresponding `transType` values are `PAY` / `REFUND` / `REFUND_PART` / `REVERSAL`). They describe what kind of record the system wrote down; there is **no** endpoint that lets an integrator "initiate a refund" or "initiate a reversal".
**The key test**: the dispute process starts only when the merchant **will not refund**, or when the transaction **was not initiated by the cardholder at all** (unauthorized use). If the merchant has already refunded, the money is credited automatically to that user's independent balance, so **do not raise a dispute on top of it**. A merchant refund plus a dispute recovery for the same transaction is treated by the card network as an anomaly.
***
## Refunds and reversals: credited automatically to the user's independent balance
In the DeCard-Managed model, user assets are recorded on a **user-level independent balance**. When a merchant refund or a transaction reversal occurs:
* The funds are posted as a **credit** to that end user's independent balance: the available balance `free` (conceptual alias availableBalance) increases; if a hold is released, the frozen balance `freeze` (frozenBalance) decreases accordingly.
* This happens **automatically, with no refund or reversal call from you and no second allocation step**. That is exactly the core difference from the Partner-Managed model: the money lands directly on the user, instead of landing first in the integrator's aggregate balance account and then being matched to a user by the integrator.
* In the user's card transaction detail the entry carries the debit/credit indicator `debitCreditIndicator=C` (Credit, a reverse transaction such as a return or a repayment); a normal purchase carries `D` (Debit).
> The interface definition is authoritative for balance field naming: the query endpoint returns `free` / `freeze` / `total`, while `availableBalance` / `frozenBalance` are conceptual aliases only. The balance query returns an **array**, so iterate over it by `asset`. See [User Balance](../how-to-use/managing-transactions/user-balance).
***
## Loss containment for unauthorized use: freeze the card (`/card/v2/block`)
When a user reports an unauthorized transaction, the first step is to **freeze the card concerned immediately** to stop further losses. This is the containment action an integrator can perform on its own today.
> **Who does what**
>
> * **The integrator**: (1) freeze the card concerned immediately; (2) guide the user to have a replacement card issued where needed (card replacement in the DeCard-Managed model goes through the hosted guidance page, see below); (3) gather the evidence and submit a dispute request to DCS through the operations channel.
> * **DCS**: takes in the case, raises the chargeback with the card network, tracks the ruling, and reports the recovered funds and progress back to the integrator.
**Freezing a card** uses the endpoint `POST /card/v2/block` (freeze and unfreeze are distinguished by the `block` boolean; **there is no separate unfreeze/unblock endpoint**, and paths in this model carry **no** `/open-api/` prefix):
Request (masked placeholders; never write real PII):
```json theme={null}
{
"externalUserId": "user_xxxxxxxx",
"block": true,
"cardId": "card_xxxxxxxx",
"smsCode": "",
"emailCode": ""
}
```
| Parameter | Type | Required | Description |
| :--------------- | :------ | :---------- | :--------------------------------------------------------------------------- |
| `externalUserId` | String | Yes | Channel user ID |
| `block` | Boolean | Yes | `true` = freeze (contain the loss) / `false` = unfreeze |
| `cardId` | String | Yes | Card ID |
| `smsCode` | String | Conditional | SMS verification code: required to unfreeze, not required to freeze |
| `emailCode` | String | Conditional | Email verification code; can be used instead of the SMS code when unfreezing |
Successful response (standard envelope `{code, message, messageDetail, data}`, success code `code = SYS_SUCCESS`):
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": "",
"messageDetail": null,
"data": false
}
```
**Error handling**: containment is a race against time, so build a fallback for a failed freeze call.
* Missing `smsCode`/`emailCode` when unfreezing: supply the verification code and retry (freezing itself needs no verification code and can be called immediately).
* If the call returns anything other than `SYS_SUCCESS`: trust `message` and `messageDetail`, and **do not** treat HTTP 200 alone as success. If the retry also fails, escalate to the operations channel for a manual freeze right away rather than leaving exposure on a compromised card.
For the full description of freeze and unfreeze and of card detail and status queries, see [Managing Cards · Overview](../how-to-use/managing-cards/overview); if the user needs a replacement card, contact DCS for assistance.
***
## Decision flow for handling unauthorized use
> On-chain and off-chain boundary: in the diagram above, the card network ruling and chargeback are an **off-chain** card network process, and crediting the funds to the user's independent balance is a bookkeeping action on the DeCard-Managed ledger (off-chain). This model involves no on-chain collateral or signatures, so nothing in this flow touches the chain.
***
## How dispute proceeds get back to the user
Once the card network rules in the cardholder's favour, the recovered funds are **credited directly to that end user's independent balance account** (`free` increases), in exactly the same form as a merchant refund, with no second allocation step from the integrator:
* In the user's card transaction detail it appears as a credit entry with the debit/credit indicator `debitCreditIndicator=C` (Credit).
* Because the DeCard-Managed model holds user assets in custody and records them on a user-level independent balance, the recovered funds land in that user's balance account. **This differs from the Partner-Managed model, where the funds land first in the integrator's balance account and the integrator then matches them to the end user.**
> **Reconciliation tip**: record the corresponding transaction ID when you follow up a dispute through the operations channel, so that you can match the incoming credit to the specific dispute later.
***
## FAQ
### A user reports an unauthorized transaction. What should I do?
1. Freeze the card concerned immediately to contain the loss: `POST /card/v2/block` with `block=true`.
2. Arrange a replacement card for the user where needed (contact DCS for assistance).
3. First retrieve the full detail of the transaction (transaction ID, amount, currency, merchant name, timestamp) through `GET /card/v2/statements/detail` or `GET /card/v1/fiat/transactions`, package it together with the card's last four digits as evidence, and submit the dispute to DCS through the operations channel. DCS then raises the dispute with the card network.
There is currently **no self-service dispute API** in this model, so dispute submission goes through the operations channel.
### After the merchant refunds, when and where does the money arrive?
A merchant refund appears in the user's card transactions as a credit with `authType=REFUND` (for QR payments, `transType=REFUND` or `REFUND_PART`), and the system **credits it automatically to that end user's independent balance** (`free` increases). You do not call any endpoint and you do not allocate the money a second time. The arrival time depends on how quickly the merchant and the card network process it; if a refund stays outstanding for an unusually long time, ask the operations channel to investigate.
### A transaction was declined at the terminal but the account was still debited. What should I do?
First confirm with the merchant whether the transaction was declined in their system. If the authorization is never finally posted (settled), the hold is normally released back to the user's available balance automatically, showing up as a `REVERSAL` and a released hold, with no further action needed. See [Settlement](../how-to-use/managing-transactions/settlement) and [User Balance](../how-to-use/managing-transactions/user-balance).
### Are refunds (`REFUND`) and reversals (`REVERSAL`) endpoints I can call?
No. `EXPEND` / `REFUND` / `REVERSAL` (and the QR values `PAY` / `REFUND` / `REFUND_PART` / `REVERSAL`) are all **read-only transaction classification enums** that label what kind of record the system wrote down. There is no endpoint for an integrator to "initiate a refund or reversal"; these actions are initiated by the merchant or the card network and credited automatically by the system.
### Which transactions can be disputed?
As a rule, only **settled** transactions with a **non-zero amount** can be disputed; pending transactions and zero-amount (verification) transactions cannot. Card network disputes have a deadline, usually **120 days** from the transaction date, and the closer you get to it the higher the risk of rejection, so submit through the operations channel as early as possible. Only one dispute may be open on a given transaction at a time, so do not submit the same case twice.
### The merchant has already refunded. Should I still raise a dispute?
No. The merchant refund is credited back to the user's independent balance automatically, and raising a dispute on top of it produces a double recovery that the card network may treat as an anomaly. Confirm first whether the credit has landed, and use the dispute process only when the merchant **refuses to refund or has not refunded for an unusually long time**.
### Who handles disputes, and where do I follow up on the outcome?
DCS takes in the case and raises it with the card network, and the outcome and progress are reported back to you through the operations channel (customer success or an operations ticket). When you submit, provide at minimum: the transaction ID, the card's last four digits (masked, for example `****1234`), the merchant details, the dispute category with a written description, and any supporting evidence files.
***
## Confirm with DCS during integration
Align the following points with DCS when you integrate:
* The roadmap for a self-service dispute and chargeback API, plus the exact format and turnaround for dispute submission through the operations channel.
* Whether webhook events are available to subscribe to at each stage of a dispute.
* Customer-facing commitments such as dispute fees and refund arrival deadlines.
## Next steps
* How the release of holds and the crediting of refunds and reversals play out in settlement: [Basic Concepts › Transaction Lifecycle › Settlement](../how-to-use/managing-transactions/settlement)
* Reconciling recovered funds against the user's independent balance: [How-To Guide › User Balance](../how-to-use/managing-transactions/user-balance)
* The freeze and card replacement operations needed to contain losses: [How-To Guide › Managing Cards · Overview](../how-to-use/managing-cards/overview)
* Common questions on identity verification and compliance: [FAQ › Verification and Compliance](./verification-and-compliance)
* Escalation and support paths: [FAQ › Escalations and Support Paths](./escalations-and-support-paths)