Skip to content
Developer portal

Retrieve a dispute

GET
/v1/disputes/{id}
curl --request GET \
  --url https://api.example.com/v1/disputes/example \
  --header 'Authorization: Bearer <token>'

Another merchant’s dispute, or one in the other mode, is not_found.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The object’s id.

Responses

Section titled “Responses”

200

Section titled “200”

The dispute.

Media typeapplication/json

A customer’s challenge to one of your card payments, as you see it. The payment itself never changes: it stays succeeded, and the dispute is its own object.

object
id
required
string
object
required
string
Allowed value: dispute
amount
required

The amount disputed, in the currency’s minor unit: all of the payment, or part of it. It is taken from the funds due to you when the dispute opens, and returned if you win.

integer
currency
required

A three-letter ISO 4217 code, in lower case.

string
/^[a-z]{3}$/
payment_intent
required

The payment intent disputed.

string
status
required

open when the chargeback arrives; under_review while the operations team work the case; then won, lost or accepted, each final. See Disputes.

string
Allowed values: open under_review won lost accepted
reason
required

What kind of dispute it is, from the network’s reason code. fraud: the cardholder says they did not make the payment. authorization: the payment was not properly authorized. processing_error: it was processed wrongly, such as charged twice, late or in the wrong amount. consumer_dispute: the customer says what they paid for was not received, not as described, or cancelled, or that a refund was not given. other: a code not in these.

string
Allowed values: fraud authorization processing_error consumer_dispute other
network_reason_code
required

The card network’s own reason code for the dispute, as it gave it.

string
case_reference
required

The card network’s reference for the case. Quote it when you talk to the operations team about the dispute.

string
chargeback_cost
required

What the card provider charges for the chargeback, in the dispute’s currency and minor unit, taken from the funds due to you with amount. 0 when it charges nothing.

integer
admin_fee
required

Your platform’s own fee for handling a chargeback, if it sets one for the payment method, taken with amount. Fixed when the dispute opens. 0 when there is none. It is not returned when you win.

integer
cost_returned
required

What a won dispute gave back of chargeback_cost, in the same minor unit: returned to you with amount. 0 until the dispute is won and the card provider returns its cost, and 0 for one that is lost or accepted.

integer
debited
required

What came off your balance for the chargeback: amount, chargeback_cost and admin_fee together. 0 when charged_to is platform. It stays the same once the dispute is decided: what a win returns is amount and cost_returned. In test mode nothing moves, but it says what would have.

integer
charged_to
required

Who bore the chargeback. you: it came off your balance, as debited says. platform: the platform you take payments under bore it, and nothing came off your balance.

string
Allowed values: you platform
evidence_due_date
required

The last day to respond with evidence, as a calendar date (YYYY-MM-DD) in your platform’s time zone. It may be moved while the dispute is worked. null until it is known.

string | null format: date
evidence_request
required

What the operations team asked you to send for the case, if they asked. null otherwise.

string | null
livemode
required
boolean
created
required

When the dispute opened, as a Unix timestamp.

integer
closed
required

When it was decided, as a Unix timestamp. null while it is open or under_review.

integer | null
Examples

Open, as the chargeback arrived

{
  "id": "dp_0199c3f2a1b47c1e9a20d4b8f35e",
  "object": "dispute",
  "amount": 10000,
  "currency": "php",
  "payment_intent": "pi_01j9x2p4d6f8h0k2m4n6q8s0t2",
  "status": "open",
  "reason": "fraud",
  "network_reason_code": "10.4",
  "case_reference": "CB-2026-0001842",
  "chargeback_cost": 50000,
  "admin_fee": 0,
  "cost_returned": 0,
  "debited": 60000,
  "charged_to": "you",
  "evidence_due_date": "2026-10-18",
  "evidence_request": null,
  "livemode": false,
  "created": 1791446400,
  "closed": null
}

Headers

Section titled “Headers”
X-Request-ID
string

This request’s id. Quote it when you contact support.

401

Section titled “401”

authentication_failure: access_token_required when no token was sent, invalid_access_token when it is not valid, has expired, or is a client secret. Sent with a WWW-Authenticate: Bearer header, which adds error="invalid_token" when a token was sent.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

403

Section titled “403”

authorization_failure with merchant_mismatch: a Merchant-Id header, query parameter or body field names a merchant or tenant other than the key’s.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

404

Section titled “404”

not_found: resource_missing for an id this key cannot see, route_missing for a path that does not exist.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}

503

Section titled “503”

dependency_failure with service_unavailable: something on our side, or a payment network behind it, did not answer. This call only reads, so nothing was changed; retry.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure
code
required

A stable name for this refusal. Branch on this, never on message.

string
message
required

For the developer reading a log. May be reworded.

string
param
required

The field or parameter at fault, when there is one.

string | null
request_id
required
string | null
Example
{
  "error": {
    "type": "validation_failure"
  }
}