> ## Documentation Index > Fetch the complete documentation index at: https://docs.paynext.com/llms.txt > Use this file to discover all available pages before exploring further. # Find disputes > List your organization's disputes, newest first by default. The list can take up to about a minute to reflect a new or updated dispute; fetch a dispute by ID for its current state. List items never include `details`. Pagination is capped at 10000 results: `page * limit` must not exceed 10000, otherwise the request returns 400, and `meta.pages` never exceeds `10000 / limit`. A missing or non-numeric `page` or `limit` uses its default. A `page` below 1 is treated as 1, a `limit` above 100 as 100, and a `limit` below 1 as 10. ## OpenAPI ````yaml /api-reference/openapi3-v2.0.0.json get /disputes openapi: 3.0.1 info: contact: {} description: Billing API title: Billing v2.0.0 version: '3.0' servers: - url: https://sandbox-api.paynext.com/ security: [] paths: /disputes: get: tags: - Disputes summary: Find disputes description: >- List your organization's disputes, newest first by default. The list can take up to about a minute to reflect a new or updated dispute; fetch a dispute by ID for its current state. List items never include `details`. Pagination is capped at 10000 results: `page * limit` must not exceed 10000, otherwise the request returns 400, and `meta.pages` never exceeds `10000 / limit`. A missing or non-numeric `page` or `limit` uses its default. A `page` below 1 is treated as 1, a `limit` above 100 as 100, and a `limit` below 1 as 10. operationId: findDisputes parameters: - description: Specifies the version of the API to use in: header name: X-API-Version schema: enum: - 2.0.0 type: string default: 2.0.0 required: true - description: Page number, starting at 1 in: query name: page schema: default: 1 type: integer - description: Number of items per page (maximum 100) in: query name: limit schema: default: 100 maximum: 100 type: integer - description: Field to sort by in: query name: sort schema: default: disputed_at enum: - disputed_at - created_at - updated_at - respond_by - resolved_at type: string - description: Sort order. Must be lowercase. in: query name: order schema: default: desc enum: - asc - desc type: string - description: Filter by dispute status. Case-insensitive. in: query name: status schema: enum: - NEEDS_RESPONSE - EVIDENCE_SUBMITTED - UNDER_REVIEW - WON - LOST - ACCEPTED - PREVENTED type: string example: NEEDS_RESPONSE - description: Filter by dispute stage. Case-insensitive. in: query name: stage schema: enum: - RETRIEVAL - DISPUTE type: string example: DISPUTE - description: Filter by the disputed payment's ID, as `pay_` or a bare UUID in: query name: payment_id schema: type: string example: pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789 responses: '200': content: application/json: schema: $ref: '#/components/schemas/main_module_public_api.disputesResDTO' examples: disputes: summary: Disputes, newest first value: data: - id: dsp_7c1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b payment_id: pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789 external_id: dp_1Nx2yZAbCdEfGh stage: DISPUTE status: NEEDS_RESPONSE reason: FRAUDULENT disputed_at: '2025-06-20T10:15:00Z' respond_by: '2025-07-04T23:59:59Z' created_at: '2025-06-20T10:20:00Z' updated_at: '2025-06-20T10:20:00Z' - id: dsp_2f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f payment_id: pay_5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a external_id: PP-D-27803 stage: DISPUTE status: WON reason: PRODUCT_NOT_RECEIVED disputed_at: '2025-05-02T08:00:00Z' respond_by: '2025-05-12T08:00:00Z' resolved_at: '2025-06-01T12:00:00Z' created_at: '2025-05-02T08:03:00Z' updated_at: '2025-06-01T12:00:05Z' meta: page: 1 pages: 1 limit: 100 total: 2 snapshot_at: '' empty: summary: No matching disputes value: data: [] meta: page: 1 pages: 0 limit: 100 total: 0 snapshot_at: '' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/pkg_server.HttpResErrorDTO' examples: invalid_status: summary: Unknown status value value: error: message: invalid status "OPEN" invalid_sort: summary: Unknown sort field value: error: message: >- invalid sort "amount": must be one of disputed_at, created_at, updated_at, respond_by, resolved_at invalid_order: summary: Order not lowercase value: error: message: 'invalid order "DESC": must be asc or desc' invalid_payment_id: summary: Malformed payment ID value: error: message: >- invalid payment_id "pay_123": must be pay_ or a uuid page_out_of_range: summary: page * limit above 10000 value: error: message: 'page out of range: page * limit must not exceed 10000' description: >- Bad Request. An invalid `sort`, `order`, `status`, `stage`, or `payment_id` value, or `page * limit` above 10000. '401': content: application/problem+json: schema: $ref: '#/components/schemas/gateway.ProblemDetailsDTO' example: type: https://httpproblems.com/http-status/401 title: Unauthorized status: 401 detail: No Authorization Header instance: /disputes trace: timestamp: '2025-06-20T10:30:00.000Z' requestId: 5304266b-61cf-4f8c-b40f-cfaaa43b5fb9 buildId: 98195131-5332-4763-803d-c12fbd354c95 rayId: a43617e52a87c50d-GRU description: >- Unauthorized. The `Authorization` header is missing, or the API key is invalid. The body is a Problem Details object with `detail` set to `No Authorization Header` or `Authorization Failed`. '403': content: application/json: schema: $ref: '#/components/schemas/pkg_server.HttpResErrorDTO' example: error: message: Forbidden description: >- Forbidden. Returned when the API key is not granted Disputes read access. The body is `{"error": {"message": "Forbidden"}}`. '500': content: application/json: schema: $ref: '#/components/schemas/pkg_server.HttpResErrorDTO' example: error: message: failed to retrieve disputes description: Internal Server Error security: - Auth: [] components: schemas: main_module_public_api.disputesResDTO: properties: data: items: $ref: '#/components/schemas/core_model.DisputeResDTO' type: array meta: $ref: '#/components/schemas/pkg_server.MetaResDTO' type: object pkg_server.HttpResErrorDTO: properties: error: allOf: - $ref: '#/components/schemas/pkg_server.HttpErrorDTO' description: Description of the error type: object type: object gateway.ProblemDetailsDTO: description: >- Problem Details (RFC 9457) body returned when the request has no valid API key. properties: detail: description: >- `No Authorization Header` when the header is missing, `Authorization Failed` when the API key is invalid. example: No Authorization Header type: string instance: description: The request path. example: /disputes type: string status: description: The HTTP status code. example: 401 type: integer title: description: Short summary of the problem. example: Unauthorized type: string trace: description: Request identifiers to share with PayNext support. properties: buildId: type: string rayId: type: string requestId: type: string timestamp: type: string type: object type: description: URI identifying the problem type. example: https://httpproblems.com/http-status/401 type: string type: object core_model.DisputeResDTO: properties: created_at: description: When the dispute was first recorded in PayNext. example: '2026-08-01T10:20:00Z' type: string details: additionalProperties: true description: >- Processor-specific reference values for the dispute. Which keys appear depends on the processor, and a key with no value is `null`. Returned by `GET /disputes/{id}` only; list items never include it. Omitted when the processor supplied no details. example: network_reason_code: '10.4' processor_reason_code: fraudulent properties: is_visa_rdr: description: >- Braintree only. `true` when the dispute was resolved automatically through Visa Rapid Dispute Resolution (RDR), otherwise `false`. type: boolean network_reason_code: description: >- The card network's reason code, for example `10.4` (Visa) or `4837` (Mastercard). nullable: true type: string paypal_dispute_channel: description: PayPal only. PayPal's own dispute channel value. nullable: true type: string paypal_dispute_life_cycle_stage: description: >- PayPal only. PayPal's own life-cycle stage, for example `PRE_ARBITRATION`. nullable: true type: string paypal_outcome_code: description: PayPal only. PayPal's own outcome code. nullable: true type: string paypal_status: description: PayPal only. PayPal's own dispute status. nullable: true type: string processor_reason_code: description: >- The processor's own reason value. `reason` holds the normalized category. nullable: true type: string type: object disputed_at: description: When the dispute was raised. example: '2026-08-01T10:15:00Z' type: string external_id: description: The dispute identifier assigned by the processor. example: dp_1Nx2yZAbCdEfGh type: string id: description: Unique identifier of the dispute. example: dsp_7c1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b type: string payment_id: description: ID of the disputed payment. example: pay_e8a1b2c3-d4f5-6789-abcd-ef0123456789 type: string reason: description: Reason category for the dispute, normalized across processors. enum: - FRAUDULENT - UNRECOGNIZED - PRODUCT_NOT_RECEIVED - PRODUCT_UNACCEPTABLE - SUBSCRIPTION_CANCELED - CREDIT_NOT_PROCESSED - DUPLICATE - GENERAL_NONCOMPLIANT example: FRAUDULENT type: string resolved_at: description: >- When the dispute first reached a final status (WON, LOST, ACCEPTED, or PREVENTED). Omitted while the dispute is open. example: '2026-09-10T08:00:00Z' type: string respond_by: description: >- Deadline for your response. Omitted when the processor did not supply one. example: '2026-08-15T23:59:59Z' type: string stage: description: Where the dispute sits in the network's process. enum: - RETRIEVAL - DISPUTE example: DISPUTE type: string status: description: >- The dispute's current status. WON, LOST, ACCEPTED, and PREVENTED are final. A missed response deadline reports as LOST. enum: - NEEDS_RESPONSE - EVIDENCE_SUBMITTED - UNDER_REVIEW - WON - LOST - ACCEPTED - PREVENTED example: NEEDS_RESPONSE type: string updated_at: description: When the dispute was last updated in PayNext. example: '2026-08-02T09:00:00Z' type: string required: - created_at - disputed_at - external_id - id - payment_id - reason - stage - status - updated_at type: object pkg_server.MetaResDTO: properties: limit: description: Number of items per page example: 100 type: integer page: description: Current page number example: 1 type: integer pages: description: Total number of pages example: 1 type: integer snapshot_at: description: Timestamp of the data snapshot example: '2026-01-01T00:00:00Z' type: string total: description: Total number of items example: 1 type: integer type: object pkg_server.HttpErrorDTO: properties: message: description: Description of the error example: some error message type: string type: object securitySchemes: Auth: bearerFormat: JWT description: >- Authentication header of the form `api key`, where `api key` is your organization api key. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.