Skip to main content
POST
Report a card dispute, and optionally file it
Sandbox only. This endpoint is available in sandbox only while we finish development. It is not available in production yet, and its request and response shapes may change before release.

Authorizations

​
x-api-key
string
header
required

Headers

​
x-idempotency-key
string<uuid>
required

Unique key (UUID) to ensure request idempotency on POST, PUT and PATCH requests.

A key is scoped to your client, the HTTP method and the path, and is remembered for 24 hours after a successful (below 400) response. Repeating the same request (same JSON body, whatever the key order or whitespace) with the same key within that window returns the original response with X-Idempotent-Replayed: true instead of executing the request again. Using the same key on the same endpoint with a different body returns 422 with problem type idempotency-key-reused; the request is not executed. Error responses (4xx and 5xx) are not remembered, so a request refused for a fixable reason can be corrected and retried under the same key. Request bodies that are not JSON (for example file uploads) are not compared.

Body

application/json

The dispute report.

A report that a cardholder disputes a card transaction.

Recording it does not file a dispute with a card network, does not change the card transaction's status, and does not move money.

​
card_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
client_reference
string
required

Your own case identifier for this report, unique across your reports. Resubmitting one already on file is answered with 409 naming the report that exists, so a retry after a timeout cannot record one notice twice. An idempotency key cannot do this job: it expires, and a client retrying with a fresh key would otherwise file a second report.

Required string length: 1 - 255
Example:

"SUP-48213"

​
reason
enum<string>
required

Why the cardholder disputes the transaction. A closed set, so the portfolio can be counted by reason. Use other rather than a reason that is nearly right — a wrong reason is worse than an unclassified one.

Available options:
unauthorized,
not_received,
incorrect_amount,
duplicate,
cancelled_recurring,
other
Example:

"unauthorized"

​
consumer_notified_client_at
string<date-time>
required

When the cardholder told you. Dakota cannot observe this, so you assert it. Must not be later than client_forwarded_at, and must not be in the future.

Example:

"2026-09-18T14:02:11Z"

​
client_forwarded_at
string<date-time>
required

When you passed the report to Dakota. Must not be in the future.

Example:

"2026-09-18T16:40:00Z"

​
card_transaction_id
string

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
card_transaction_ids
string[]

Every Dakota card transaction this dispute covers. Required whenever filing_reason is sent, except for atm_deposit_missing — the one account-level reason, which disputes a credit that never arrived and must send an empty list.

One dispute is raised per transaction, so this is the fan-out. When you send it, card_transaction_id must also be set and must be one of these: it stays the single transaction this report is anchored to.

Maximum array length: 100

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:
​
filing_reason
enum<string>

The reason to file the dispute under, from the card network's own set. Send it to file the dispute; omit it to record the report without filing.

This is NOT the same field as reason. reason classifies the report for your own portfolio reporting and has six values; this selects which network rules the case is fought under. Some values are spelled the same in both sets and mean different things, so they are kept apart deliberately.

Omitting it stays valid on purpose: a report whose transaction is not yet identified cannot be filed, and refusing to record it would lose a notice whose response clock is already running.

Available options:
card_not_present,
card_lost,
card_stolen,
card_never_received,
counterfeit,
account_takeover,
product_not_received,
not_as_described,
credit_not_processed,
cancelled_recurring,
paid_by_other_means,
duplicate_charge,
late_presentment,
incorrect_transaction_code,
no_authorization,
declined,
incorrect_amount,
atm_cash_not_dispensed,
atm_deposit_wrong_amount,
atm_deposit_missing
Example:

"card_not_present"

​
description
string

The cardholder's own account of what happened, for the operator who files the dispute. Deliberately absent from the response: you sent it, and it is not echoed back.

Maximum string length: 4000
Example:

"Cardholder says they never authorized this charge and still holds the card."

​
disputed_amount
string

The disputed amount in MAJOR currency units, as a decimal string. Omit both this and disputed_currency when the whole transaction is disputed; send both for a partial dispute.

Example:

"42.50"

​
disputed_currency
string

ISO 4217 currency code for disputed_amount. Required with it, and refused without it.

Example:

"USD"

Response

The report was recorded. state is received when a card transaction was named and awaiting_transaction when it was not.

Dakota's record that a cardholder disputed a card transaction, and of what Dakota did about it.

It carries neither description nor the identity of the operator who filed: the first is the cardholder's own words, which you supplied and which are not echoed back, and the second is internal.

​
id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
card_id
string
required

KSUID is a 27-character globally unique ID that combines a timestamp with a random component. Used for all entity identifiers in the Dakota platform.

Required string length: 27
Pattern: ^[0-9A-Za-z]{27}$
Example:

"1NFHrqBHb3cTfLVkFSGmHZqdDPi"

​
filing_state
enum<string>
required

How far the dispute's filing has got. Always present.

not_filed means Dakota has not filed this dispute — either you sent no filing_reason, or the filing was attempted and did not succeed. In the second case the report is still on file and its response clock is running, so a not_filed report that names a filing_reason needs following up.

The rest report what the provider holds: pending is a dispute raised whose required information is still outstanding, filed is submitted, and refused, withdrawn and abandoned are the ways it ends without being submitted.

Available options:
not_filed,
pending,
filed,
refused,
withdrawn,
abandoned
Example:

"pending"

​
client_reference
string
required

Your own case identifier, as you sent it.

Example:

"SUP-48213"

​
state
enum<string>
required

How far the report has travelled. received is a report Dakota can act on; awaiting_transaction is one whose card transaction is not yet known; filed_at_vendor means an operator filed it by hand; linked means it is tied to the resulting dispute; ambiguous means several live reports share the disputed transaction and a person must choose; rejected is how a report ends without a link. linked and rejected are terminal.

Available options:
received,
awaiting_transaction,
filed_at_vendor,
linked,
ambiguous,
rejected
Example:

"received"

​
reason
enum<string>
required

Why the cardholder disputes the transaction, as you sent it.

Available options:
unauthorized,
not_received,
incorrect_amount,
duplicate,
cancelled_recurring,
other
Example:

"unauthorized"

​
consumer_notified_client_at
string<date-time>
required

When the cardholder told you, as you asserted it.

Example:

"2026-09-18T14:02:11Z"

​
client_forwarded_at
string<date-time>
required

When you passed the report to Dakota, as you asserted it.

Example:

"2026-09-18T16:40:00Z"

​
created_at
integer
required

Unix timestamp (seconds) when Dakota recorded the report. Server-observed, unlike the two instants you assert.

Example:

1758211200

​
updated_at
integer
required

Unix timestamp (seconds) of the last change.

Example:

1758297600

​
card_transaction_id
string | null

The disputed card transaction, once it is known. Null while it is not.

Example:

"2B5J8KZ9N7M1K3P6Q8R4T7V9"

​
filing_reason
enum<string> | null

The reason the dispute was filed under, as you sent it. Null on a report that was recorded without being filed.

Available options:
card_not_present,
card_lost,
card_stolen,
card_never_received,
counterfeit,
account_takeover,
product_not_received,
not_as_described,
credit_not_processed,
cancelled_recurring,
paid_by_other_means,
duplicate_charge,
late_presentment,
incorrect_transaction_code,
no_authorization,
declined,
incorrect_amount,
atm_cash_not_dispensed,
atm_deposit_wrong_amount,
atm_deposit_missing
Example:

"card_not_present"

​
provider_filing_accepted_at
string<date-time> | null

When Dakota recorded that the dispute was accepted for filing. Null until that happens, and it is not restated afterwards.

Example:

"2026-09-18T16:41:02Z"

​
disputed_amount
string | null

The disputed amount in major currency units. Null when the whole transaction is disputed.

Example:

"42.5"

​
disputed_currency
string | null

ISO 4217 currency code for disputed_amount.

Example:

"USD"

​
dakota_filed_with_vendor_at
string<date-time> | null

When a Dakota operator filed the dispute by hand. Null until that happens, and write-once thereafter. The gap between consumer_notified_client_at and this instant is Dakota's own exposure window.

Example:

"2026-09-19T09:15:00Z"

​
vendor_dispute_reference
string | null

The reference the filing produced, once the report is linked.

Example:

"dsp_9f2c41"

​
rejection_reason
string | null

Why the report ended without a link. Set only when state is rejected.

Example:

"Cardholder withdrew the report."