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 -X GET "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:ss.sssZ.
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.