For archived content, access the previous documentation here or the previous API reference here.

List all disputes

Prev Next
Get
/v1/disputes

Retrieve a paginated list of disputes associated with the Business ID.

Security
HTTP
Type basic
Query parameters
limit
integer

Number of disputes to return per page. Defaults to 10, maximum 100.

Maximum100.0
Default10
cursor
string

Dispute ID from pagination.next_cursor for fetching the next page.

status
string

Filter disputes by lifecycle status. Use ACTION_REQUIRED to find disputes requiring your response.

Valid values[ "ACTION_REQUIRED", "UNDER_REVIEW", "WON", "LOST" ]
payment_id
string

Filter disputes by a specific Payment ID.

channel_code
string

Filter disputes by payment channel (e.g., CARDS, QRIS).

card_brands
string

Filter card disputes by card network (e.g., VISA, MASTERCARD). Only applicable when channel_code is CARDS.

currency
string

Filter disputes by currency using ISO-4217 currency code (e.g., IDR, PHP, USD).

created_after
string (date-time)

Return only disputes created after this timestamp (ISO 8601 format).

created_before
string (date-time)

Return only disputes created before this timestamp (ISO 8601 format).

due_date_after
string (date-time)

Return only disputes with a response deadline after this timestamp (ISO 8601 format).

due_date_before
string (date-time)

Return only disputes with a response deadline before this timestamp. Use this to surface disputes expiring soon.

search
string

Full-text search across dispute ID, payment ID, and reference ID.

Responses
200

A list of disputes.

Expand All
object

Paginated list of disputes.

data
Array of object (Merchant_Dispute_API_DisputeListItem)

Disputes for the current page.

object

Minimal dispute representation for list responses.

id
string

Xendit-generated unique dispute identifier.

Examplemi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7
status
string

Current lifecycle state. ACTION_REQUIRED means a response is needed before due_date.

Valid values[ "ACTION_REQUIRED", "UNDER_REVIEW", "WON", "LOST" ]
ExampleACTION_REQUIRED
status_reason
string | null

Reason for the terminal outcome. Only populated when status is WON or LOST.

Valid values[ "EXCEEDED_DEADLINE", "ACCEPTED", "CHALLENGED", "WITHDRAWN", "ARBITRATION", "NEED_MORE_INFORMATION" ]
ExampleEXCEEDED_DEADLINE
channel_code
string

Payment channel through which the original transaction was made (e.g., CARDS, QRIS).

ExampleCARDS
card_brands
string | null

Card network associated with the dispute. Only present when channel_code is CARDS.

ExampleVISA
currency
string

Currency of the disputed amount, in ISO-4217 format.

ExampleUSD
amount
object (Merchant_Dispute_API_DisputeAmount)
initial
string

The amount when the dispute was first raised.

Example1000.00
terminal
string | null

The final resolved amount. May differ from initial for partial disputes. Null while unresolved.

Example1000.00
due_date
string (date-time)

Deadline by which you must respond to avoid an automatic LOST outcome.

Example2026-09-10T04:11:54.917Z
note
string | null

Optional message from Xendit providing guidance on the dispute.

Example
category
string

Slug identifier of the dispute category. The full category object with allowed evidence types is available in GET /v1/disputes/.

Examplefraudulent
payment_id
string | null

Xendit payment identifier for the original disputed transaction.

Examplepy-59a3cf39-2a7d-4733-a3e3-8177c78090f7
reference_id
string | null

Your reference ID for the original transaction.

Exampledispute-test-1788408708890
created_at
string (date-time)

Timestamp when the dispute was created, in ISO 8601 format.

Example2026-09-03T04:11:58.756Z
updated_at
string (date-time)

Timestamp of the most recent update, in ISO 8601 format.

Example2026-09-03T04:14:53.499Z
pagination
object (Merchant_Dispute_API_Pagination)
next_cursor
string | null

The ID of the last dispute in the current page. Pass as the cursor query parameter to fetch the next page. Null when there are no more results.

Examplemi-dspt-f44d259f-fd9d-4de9-80de-1eef3f1506b7
has_more
boolean

Whether there are more results beyond this page.

Exampletrue
403

Access not allowed for this business.

{
  "error_code": "RESTRICTED_ACCESS",
  "message": "Access to this resource is restricted."
}
object
error_code
string
ExampleILLEGAL_STATE
message
string
ExampleThe requested action is not allowed in the current dispute state.