Transaction Issues and Disputes - DCS Technical Documentation

📄 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.

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):

{
  "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):

{
  "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; if the user needs a replacement card, contact DCS for assistance.

Decision flow for handling unauthorized use

Fraud and dispute handling decision flow

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?

Freeze the card concerned immediately to contain the loss: POST /card/v2/block with block=true.
Arrange a replacement card for the user where needed (contact DCS for assistance).
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 and 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
Reconciling recovered funds against the user’s independent balance: How-To Guide › User Balance
The freeze and card replacement operations needed to contain losses: How-To Guide › Managing Cards · Overview
Common questions on identity verification and compliance: FAQ › Verification and Compliance
Escalation and support paths: FAQ › Escalations and Support Paths

​📄 Guide

​First, separate three things: refunds, reversals, and disputes

​Refunds and reversals: credited automatically to the user’s independent balance

​Loss containment for unauthorized use: freeze the card (/card/v2/block)

​Decision flow for handling unauthorized use

​How dispute proceeds get back to the user

​FAQ

​A user reports an unauthorized transaction. What should I do?

​After the merchant refunds, when and where does the money arrive?

​A transaction was declined at the terminal but the account was still debited. What should I do?

​Are refunds (REFUND) and reversals (REVERSAL) endpoints I can call?

​Which transactions can be disputed?

​The merchant has already refunded. Should I still raise a dispute?

​Who handles disputes, and where do I follow up on the outcome?

​Confirm with DCS during integration

​Next steps