Search refunds

GET/v1/refunds

You can use this endpoint to search refunds you’ve previously created. The refunds are sorted by date, with the most recently created refunds appearing first.

Requires a bearer token.

In this mock: Refunds across all payments, newest first.

Query parameters

Name	Type	Description
`from_date`	string	Returns refunds created on or after the `from_date`. Date and time must use Coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
`to_date`	string	Returns refunds created before the `to_date`. Date and time must use Coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.
`from_settled_date`	string	Returns refunds settled on or after the `from_settled_date` value. You can only use `from_settled_date` if your payment service provider is Stripe. Date must use ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Refunds are settled when Stripe takes the refund from your account balance.
`to_settled_date`	string	Returns refunds settled before the `to_settled_date` value. You can only use `to_settled_date` if your payment service provider is Stripe. Date must use ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Refunds are settled when Stripe takes the refund from your account balance.
`page`	string	Returns a specific page of results. Defaults to `1`.
`display_size`	string	The number of refunds returned per results page. Defaults to `500`. Maximum value is `500`.

Example request

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

Responses

200: OK - your request was successful.

Name	Type	Description
`_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`.
`count`	integer	Number of refunds on the current page of search results.
`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 the refunds matching your search criteria.
`results[]._links`	object	links for search refunds 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[]._links.self`	object	A link related to a payment
`results[]._links.self.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`results[]._links.self.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`results[].amount`	integer	The amount refunded to the user in pence.
`results[].created_date`	string	The date and time you created this refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`.
`results[].payment_id`	string	The unique ID GOV.UK Pay automatically associated with this payment when you created it.
`results[].refund_id`	string	The unique ID GOV.UK Pay automatically associated with this refund when you created it.
`results[].settlement_summary`	object	A structure representing information about a settlement for refunds
`results[].settlement_summary.settled_date`	string	The date Stripe took the refund from a payout to your bank account. `settled_date` only appears if Stripe has taken the refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DD`.
`results[].status`	string	The status of the refund. One of: submitted, success, error
`total`	integer	Number of refunds matching your search criteria.

{
  "_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"
    }
  },
  "count": 20,
  "page": 1,
  "results": [
    {
      "_links": {
        "payment": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        },
        "self": {
          "href": "https://an.example.link/from/payment/platform",
          "method": "GET"
        }
      },
      "amount": 120,
      "created_date": "2017-01-10T16:52:07.855Z",
      "payment_id": "hu20sqlact5260q2nanm0q8u93",
      "refund_id": "act4c33g40j3edfmi8jknab84x",
      "settlement_summary": {
        "settled_date": "2016-01-21"
      },
      "status": "success"
    }
  ],
  "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. 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"
}

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"
}