Search disputes

GET/v1/disputes

You can use this endpoint to search disputes. A dispute is when a paying user challenges a completed payment through their bank.

Requires a bearer token.

In this mock: Disputes come from card schemes, so the mock serves four fixed sample disputes (needs_response, under_review, won, lost). The error codes P1401 and P1402 are assumed.

Query parameters

Name	Type	Description
from_date	string	Returns disputes raised on or after the from_date. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - YYYY-MM-DDThh:mm:ssZ.
to_date	string	Returns disputes raised before the to_date. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - YYYY-MM-DDThh:mm:ssZ.
from_settled_date	string	Returns disputes settled on or after the from_settled_date. Date must be in ISO 8601 format to date-level accuracy - YYYY-MM-DD. Disputes are settled when your payment service provider takes the disputed amount from a payout to your bank account.
to_settled_date	string	Returns disputes settled before the to_settled_date. Date must be in ISO 8601 format to date-level accuracy - YYYY-MM-DD. Disputes are settled when your payment service provider takes the disputed amount from a payout to your bank account.
status	string	Returns disputes with a matching status. status reflects what stage of the dispute process a dispute is at. You can read more about the meanings of the different status values One of: needs_response, under_review, lost, won
page	string	Returns a specific page of results. Defaults to 1.
display_size	string	The number of disputes returned per results page. Defaults to 500. Maximum value is 500.

Example request

curl -X GET "https://publicapi.payments.platform-engineering.com/v1/disputes" \
  -H "Authorization: Bearer $TOKEN"

Responses

200: OK - your request was successful.

Name	Type	Description
count	integer	Number of disputes on the current page of search results.
links	object	Links to navigate through pages of your search.
links.first_page	object	A link related to a payment
links.first_page.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
links.first_page.method	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated href.
links.last_page	object	A link related to a payment
links.last_page.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
links.last_page.method	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated href.
links.next_page	object	A link related to a payment
links.next_page.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
links.next_page.method	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated href.
links.prev_page	object	A link related to a payment
links.prev_page.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
links.prev_page.method	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated href.
links.self	object	A link related to a payment
links.self.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
links.self.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[]	array of objects	Contains disputes matching your search criteria.
results[]._links	object	links for search dispute resource
results[]._links.payment	object	A link related to a payment
results[]._links.payment.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
results[]._links.payment.method	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated href.
results[].amount	integer	The disputed amount in pence.
results[].created_date	string	The date and time the user's bank told GOV.UK Pay about this dispute.
results[].dispute_id	string	The unique ID GOV.UK Pay automatically associated with this dispute when the paying user disputed the payment.
results[].evidence_due_date	string	The deadline for submitting your supporting evidence. This value uses Coordinated Universal Time (UTC) and ISO 8601 format
results[].fee	integer	The payment service provider’s dispute fee, in pence.
results[].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.
results[].payment_id	string	The unique ID GOV.UK Pay automatically associated with this payment when you created it.
results[].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'
results[].settlement_summary	object	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.
results[].settlement_summary.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.
results[].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.

{
  "count": 20,
  "links": {
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "page": 1,
  "results": [
    {
      "_links": {
        "payment": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "amount": 1200,
      "created_date": "2022-07-28T16:43:00.000Z",
      "dispute_id": "hu20sqlact5260q2nanm0q8u93",
      "evidence_due_date": "2022-07-28T16:43:00.000Z",
      "fee": 1200,
      "net_amount": -2400,
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "reason": "fraudulent",
      "settlement_summary": {
        "settled_date": "2022-07-28"
      },
      "status": "under_review"
    }
  ],
  "total": 100
}

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

Name	Type	Description
code	string	An API error codethat explains why the payment failed.<br><br>code only appears if the payment failed.
description	string	Additional details about the error.
field	string	The parameter in your request that's causing the error.
header	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}

429: Too many requests

Name	Type	Description
code	string	A GOV.UK Pay API error code. You can find out more about this code in our documentation.
description	string	Additional details about the error

{
  "code": "P0900",
  "description": "Too many requests"
}

500: Downstream system error

Name	Type	Description
code	string	An API error codethat explains why the payment failed.<br><br>code only appears if the payment failed.
description	string	Additional details about the error.
field	string	The parameter in your request that's causing the error.
header	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}