Skip to main content

Get information about a payment’s 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 getting information about the refunds for a payment:

  • 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/payments/{PAYMENT_ID}/refunds

You can use this endpoint to get a list of refunds for a payment.

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.

Path parameters for ‘Get information about a payment’s refunds’

Name Type Description
{PAYMENT_ID} (required) string The unique ID of the payment you want a list of refunds for.

GOV.UK Pay associates a unique paymentId with a payment when you create that payment.

Example request for ‘Get information about a payment’s refunds’

This example request gets information about refunds of the payment with the payment ID hu20sqlact5260q2nanm0q8u93:

curl "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93/refunds" -H "Authorization: Bearer api_test_123abc456def"

Example response for ‘Get information about a payment’s refunds’

After you send your request to get information about a payment’s refunds, you’ll receive a response similar to this example:

{
    "payment_id": "01k7da2d0021m0pcbjov354et8",
    "_links": {
        "self": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments/01k7da2d0021m0pcbjov354et8/refunds",
            "method": "GET"
        },
        "payment": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments/01k7da2d0021m0pcbjov354et8",
            "method": "GET"
        }
    },
    "_embedded": {
        "refunds": [
            {
                "refund_id": "fvtj4naca8nstj2u0roq3t4p6r",
                "created_date": "2022-02-17T12:42:55.510Z",
                "amount": 5000,
                "status": "success",
                "settlement_summary": {},
                "_links": {
                    "self": {
                        "href": "https://publicapi.payments.service.gov.uk/v1/payments/01k7da2d0021m0pcbjov354et8/refunds/fvtj4naca8nstj2u0roq3t4p6r",
                        "method": "GET"
                    },
                    "payment": {
                        "href": "https://publicapi.payments.service.gov.uk/v1/payments/01k7da2d0021m0pcbjov354et8",
                        "method": "GET"
                    }
                }
            },
            {
                "refund_id": "4jfabcee0ev36so050kooajabk",
                "created_date": "2022-03-22T12:44:15.227Z",
                "amount": 1000,
                "status": "success",
                "settlement_summary": {},
                "_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"
                    }
                }
            }
        ]
    }
}

In this example, the payment has been partially refunded twice for the amounts of £50 and £10.

Attributes you’ll get in a ‘Get information about a payment’s refunds’ response

Name Type Description
_links object Contains URLs and methods for actions related to this payment.
_links.self object Contains an API method and endpoint to repeat this request and get refund information about this payment.

A GET request (method) to this endpoint (href) returns refund information for this payment.

You can read more about refunding payments.
_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.

You can read more about getting information about a single payment
refunds object Contains a list of refunds for this payment.

Each refund is a separate object within refunds.
refund_id string The unique ID GOV.UK Pay automatically 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 and time you created this refund.

This value uses Coordinated Universal Time (UTC) and ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ.
amount number The amount refunded to the user in pence.
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.

A refund is settled when Stripe takes it from a payout to your bank account.

settlement_summary is only available if your payment service provider is Stripe.
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.