Search refunds API reference

This page is part of GOV.UK Pay’s API reference and is an index of the following you’ll use when searching refunds:

• parameters
• example requests
• example responses
• attributes you’ll get in your response

You can also read more about the GOV.UK Pay refund process in our task-based guidance.

The URL for this endpoint is:

GET https://publicapi.payments.service.gov.uk/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.

The data from this endpoint is eventually consistent, meaning it is updated on a delay. You can read more about data consistency in our API.

Query parameters for ‘Search refunds’

Name	Type	Description
from_date	date (ISO 8601)	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	date (ISO 8601)	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	date (ISO 8601)	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	date (ISO 8601)	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	number	Returns a specific page of results. Defaults to 1. You can read more about search pagination.
display_size	number	The number of refunds returned per results page. Defaults to 500. Maximum value is 500. You can read more about search pagination.

Example request for ‘Search refunds’

This example request is a refund search filtered by the date that refunds were created, with a limit of 5 refunds per page of results:

curl -X GET "https://publicapi.payments.service.gov.uk/v1/refunds?from_date=2021-04-01T08:00:00Z&display_size=5" -H 'Authorization: Bearer api_test_123abc456def'

Example response for ‘Search refunds’

After you send your request to search refunds, you’ll receive a response similar to this example:

{
    "total": 142,
    "count": 5,
    "page": 1,
    "results": [
        {
            "refund_id": "4jfabcee0ev36so050kooajabk",
            "created_date": "2022-03-22T12:44:15.227Z",
            "payment_id": "01k7da2d0021m0pcbjov354et8",
            "amount": 1000,
            "_links": {
                "self": {
                    "href": "https://publicapi.payments.service.gov.uk/v1/payments/01k7da2d0021m0pcbjov354et8/refunds/4jfabcee0ev36so050kooajabk",
                    "method": "GET"
                },
                "payment": {
                    "href": "https://publicapi.payments.service.gov.uk/v1/payments/01k7da2d0021m0pcbjov354et8",
                    "method": "GET"
                }
            },
            "status": "success",
            "settlement_summary": {}
        },
        {
            "refund_id": "c8pmgvrklqip57k8665vjamb60",
            "created_date": "2021-04-07T09:55:20.758Z",
            ...
        }
    ],
    "_links": {
        "self": {
            "href": "https://publicapi.payments.service.gov.uk/v1/refunds?from_date=2021-04-01T08%3A00%3A00Z&display_size=5&page=1"
        },
        "first_page": {
            "href": "https://publicapi.payments.service.gov.uk/v1/refunds?from_date=2021-04-01T08%3A00%3A00Z&display_size=5&page=1"
        },
        "last_page": {
            "href": "https://publicapi.payments.service.gov.uk/v1/refunds?from_date=2021-04-01T08%3A00%3A00Z&display_size=5&page=29"
        },
        "prev_page": {},
        "next_page": {
            "href": "https://publicapi.payments.service.gov.uk/v1/refunds?from_date=2021-04-01T08%3A00%3A00Z&display_size=5&page=2"
        }
    }
}

Attributes you’ll get in a ‘Search refunds’ response

Name	Type	Description
total	number	Number of refunds matching your search criteria.
count	number	Number of refunds on the current page of search results.
page	number	The page of results you’re viewing. To view other pages, make this request again using the page parameter. You can read more about search pagination.
results	object	Contains the refunds matching your search criteria.
refund_id	string	The unique ID GOV.UK Pay associated with this refund when you created it. If one payment has multiple refunds, each refund has a different refund_id.
created_date	date (ISO 8601)	The date the refund was created. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - YYYY-MM-DDThh:mm:ss.sssZ.
payment_id	string	The unique ID GOV.UK Pay associated with this payment when you created it.
amount	number	The amount refunded to the user in pence.
results._links	object	Contains URLs and methods for actions related to this payment.
results._links.self	object	Contains an API method and URL to get information about this refund. A GET request (method) to this URL (href) returns information about this refund.
results._links.payment	object	Contains an API method and URL to get information about this payment. A GET request (method) to this URL (href) returns information about this payment.
status	string	The status of this refund. Possible values are: submitted success error You can read more about the meanings of refund status values.
settlement_summary	object	Contains information about when this refund was settled if your payment service provider is Stripe. A refund is settled when Stripe takes it from a payout to your bank account.
settlement_summary.settled_date	date (ISO 8601)	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.
_links	object	Contains links you can use to move between the pages of this search.
_links.self	object	Use this URL (href) to run the same search again.
_links.first_page	object	Use this URL (href) to get the first page of results.
_links.last_page	object	Use this URL (href) to get the last page of results.
_links.next_page	object	Use this URL (href) to get the next page of results.
_links.prev_page	object	Use this URL (href) to get the previous page of results.