---
title: "Search disputes"
method: GET
path: "/v1/disputes"
tags: ["Disputes"]
---

# Search disputes

`GET /v1/disputes`

## Request

- Base URL: `https://publicapi.payments.service.gov.uk`
- URL: `https://publicapi.payments.service.gov.uk/v1/disputes`
- Auth: HTTP bearer

You can use this endpoint to search disputes. A dispute is when [a paying user challenges a completed payment through their bank](https://docs.payments.service.gov.uk/disputes/).

## Query parameters

- `from_date` string
- `to_date` string
- `from_settled_date` string
- `to_settled_date` string
- `status` 'needs_response' | 'under_review' | 'lost' | 'won'
- `page` string
- `display_size` string

## Response `200`

OK - your request was successful.

- DisputesSearchResults
  - `count` integer: Number of disputes on the current page of search results.
  - `links` SearchNavigationLinks: Links to navigate through pages of your search.
    - `first_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `last_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `next_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `prev_page` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `self` Link: A link related to a payment
      - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
      - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
  - `page` integer: The page of results you’re viewing. To view other pages, make this request again using the 'page' parameter.
  - `results` DisputeDetailForSearch[]: Contains disputes matching your search criteria.
    - `_links` DisputeLinksForSearch: links for search dispute resource
      - `payment` Link: A link related to a payment
        - `href` string: A URL that lets you perform additional actions to this payment when combined with the associated `method`.
        - `method` string: An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
    - `amount` integer: The disputed amount in pence.
    - `created_date` string: The date and time the user's bank told GOV.UK Pay about this dispute.
    - `dispute_id` string: The unique ID GOV.UK Pay automatically associated with this dispute when the paying user disputed the payment.
    - `evidence_due_date` string: The deadline for submitting your supporting evidence. This value uses Coordinated Universal Time (UTC) and ISO 8601 format
    - `fee` integer: The payment service provider’s dispute fee, in pence.
    - `net_amount` integer: The amount, in pence, your payment service provider will take for a lost dispute. 'net_amount' is deducted from your payout after you lose the dispute. For example, a 'net_amount' of '-1500' means your PSP will take £15.00 from your next payout into your bank account. 'net_amount' is always a negative value. 'net_amount' only appears if you lose the dispute.
    - `payment_id` string: The unique ID GOV.UK Pay automatically associated with this payment when you created it.
    - `reason` string: The reason the paying user gave for disputing this payment. Possible values are: 'credit_not_processed', 'duplicate', 'fraudulent', 'general', 'product_not_received', 'product_unacceptable', 'unrecognised', 'subscription_cancelled', >'other'
    - `settlement_summary` SettlementSummary: Contains information about when a lost dispute was settled. A dispute is settled when your payment service provider takes it from a payout to your bank account. 'settlement_summary' only appears if you lost the dispute.
      - `settled_date` string: The date your payment service provider took the disputed payment and dispute fee from a payout to your bank account. This value appears in ISO 8601 format - `YYYY-MM-DD`. `settled_date` only appears if you lost the dispute.
    - `status` string: The current status of the dispute. Possible values are: 'needs_response', 'won', 'lost', 'under_review'
  - `total` integer: Number of total disputes matching your search criteria.

## Other responses

- `401`: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)
- `422`: Invalid parameters: from_date, to_date, from_settled_date, to_settled_date, status, display_size. See Public API documentation for the correct data formats
- `429`: Too many requests
- `500`: Downstream system error

---

[API](https://skmtc.dev/government-digital-service/apis/pay-api.md) - [All operations](https://skmtc.dev/government-digital-service/apis/pay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/government-digital-service/apis/pay-api/revisions/9d66a9f54ae4?raw)