List disputes
const url = 'https://api.example.com/v1/disputes?limit=10&payment_intent=pi_01j9x2p4d6f8h0k2m4n6q8s0t2&status=open';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.example.com/v1/disputes?limit=10&payment_intent=pi_01j9x2p4d6f8h0k2m4n6q8s0t2&status=open' \ --header 'Authorization: Bearer <token>'Your disputes in this key’s mode, oldest first. Filter by the payment disputed with
payment_intent, and by status. A status that is not one of the five is refused with
validation_failure and param status.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”How many objects to return, from 1 to 100.
A next_cursor from the previous page.
Only this payment intent’s disputes.
Only disputes in this status.
Responses
Section titled “Responses”A page of disputes.
object
Pass back as cursor for the next page. null on the last page.
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
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.
A three-letter ISO 4217 code, in lower case.
The payment intent disputed.
open when the chargeback arrives; under_review while the operations team work the
case; then won, lost or accepted, each final. See Disputes.
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.
The card network’s own reason code for the dispute, as it gave it.
The card network’s reference for the case. Quote it when you talk to the operations team about the dispute.
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.
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.
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.
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.
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.
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.
What the operations team asked you to send for the case, if they asked. null otherwise.
When the dispute opened, as a Unix timestamp.
When it was decided, as a Unix timestamp. null while it is open or under_review.
Example
{ "object": "list", "data": [ { "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 } ], "has_more": false, "next_cursor": null}Headers
Section titled “Headers”This request’s id. Quote it when you contact support.
validation_failure: invalid_parameter for a parameter missing or not valid, named in param; invalid_json for a body that is not JSON; unsupported_media_type for a body that is not sent as JSON; not_acceptable when the request will not accept JSON; method_not_allowed for an HTTP method the path does not take.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure", "code": "invalid_parameter", "message": "A whole number of minor units, from 1 to 999999999999999999.", "param": "amount", "request_id": "req_4f1c0b2e9a7d" }}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.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}authorization_failure with merchant_mismatch: a Merchant-Id header, query parameter or body field names a merchant or tenant other than the key’s.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}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.
object
object
A stable name for this refusal. Branch on this, never on message.
For the developer reading a log. May be reworded.
The field or parameter at fault, when there is one.
Example
{ "error": { "type": "validation_failure" }}