> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Disputes

> Report a cardholder's dispute to Dakota

<Warning>
  **Cards is available in sandbox only while we finish development.** Dakota enables Cards per
  account. The Cards endpoints are in the [API reference](/api-reference/introduction), marked
  **Sandbox only**. Endpoints, fields, and flows can still change before release.
</Warning>

When a cardholder disputes a purchase, they tell you. You report it to Dakota with [`POST /card_dispute_reports`](/api-reference/cards/report-a-card-dispute), and Dakota files the dispute with the card network.

```json theme={null}
POST /card_dispute_reports
X-Idempotency-Key: 6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f

{
  "card_id": "2tQRvvnYkN6edEJUTmF1LzTj2ug",
  "card_transaction_id": "2tQRvH4jK8mNpQ2rS6tUvW9xYzC",
  "client_reference": "SUP-48213",
  "reason": "unauthorized",
  "description": "Cardholder never authorized this charge and still holds the card.",
  "consumer_notified_client_at": "2026-09-18T14:02:11Z",
  "client_forwarded_at": "2026-09-18T16:40:00Z"
}
```

| Field | Notes |
| - | - |
| `card_id` | Required. |
| `card_transaction_id` | Send it if you know it. Do not wait for it: the report is recorded either way. |
| `client_reference` | Required. Your case ID, unique across your reports. A duplicate returns `409` naming the existing report, so retrying after a timeout is safe. |
| `reason` | Required. `unauthorized`, `not_received`, `incorrect_amount`, `duplicate`, `cancelled_recurring`, or `other`. |
| `description` | The cardholder's account of what happened. |
| `disputed_amount`, `disputed_currency` | For a partial dispute, send both, in major units. Omit both to dispute the whole purchase. |
| `consumer_notified_client_at` | Required. When the cardholder told you. |
| `client_forwarded_at` | Required. When you reported it to Dakota. Not earlier than `consumer_notified_client_at`, and neither can be in the future. |

Networks set deadlines on disputes, so report them promptly. Reporting a dispute does not change the card or the transaction: it does not reverse the charge or credit the wallet.

The response is the report, with `state` `received` when you named the transaction, or `awaiting_transaction` when you did not.

<Note>
  **Not built yet:** reading a report back, dispute webhooks, evidence upload, dispute outcomes, and credits to the wallet. Today, the create response is your only view of the report.
</Note>