Skip to main content
POST
Create a dispute

Authorizations

Authorization
string
header
required

Secret API key, e.g. sk_live_... or sk_test_....

Headers

Idempotency-Key
string

Unique key that makes the request safe to retry. Keys expire after 24 hours.

Maximum string length: 255

Body

application/json
transaction_id
string
required
Example:

"txn_01JZ8P7H2R"

reason
enum<string>
required
Available options:
fraud,
duplicate,
incorrect_amount,
goods_not_received,
goods_not_as_described,
other
amount
integer<int64>

Defaults to the full transaction amount.

Required range: x >= 1
evidence
object

Free-form supporting details, e.g. a description or file IDs.

Response

Created.

id
string
required
read-only

Unique identifier, prefixed with dsp_.

Example:

"dsp_01JZ9C2K4M"

object
enum<string>
required
read-only

Object type.

Available options:
dispute
transaction_id
string
required
Example:

"txn_01JZ8P7H2R"

amount
integer<int64>
required

Disputed amount. In the smallest currency unit (e.g. cents).

Required range: x >= 0
Example:

1299

currency
string
required

Three-letter ISO 4217 currency code.

Pattern: ^[A-Z]{3}$
Example:

"EUR"

reason
enum<string>
required
Available options:
fraud,
duplicate,
incorrect_amount,
goods_not_received,
goods_not_as_described,
other
status
enum<string>
required
Available options:
open,
under_review,
won,
lost,
withdrawn
created_at
string<date-time>
required
read-only

Time the dispute was opened.

evidence
object
resolved_at
string<date-time> | null
read-only

Time the dispute was resolved.