Refund a payment API reference

This page is part of GOV.UK Pay’s API reference and is an index of the following you’ll use when refunding 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:

POST https://publicapi.payments.service.gov.uk/v1/payments/{PAYMENT_ID}/refunds

You can use this endpoint to refund a payment.

The payment must be refundable for this request to work.

The data from this endpoint is strongly consistent, meaning it is updated immediately after you make any changes. You can read more about data consistency in our API.

Path parameters for ‘Refund a payment’

Name	Type	Description
{PAYMENT_ID} (required)	string	The ID of the payment you’re refunding. GOV.UK Pay associates a unique paymentId with a payment when you create that payment.

JSON body parameters for ‘Refund a payment’

Name	Type	Description
amount	number	The amount you want to refund to your user in pence.
refund_amount_available	number	The amount available to refund before submitting this request. refund_amount_available must match the amount_available you receive when you check if you can refund a payment. Use GET /v1/payments/{PAYMENT_ID} to check if you can refund this payment.

Example request for ‘Refund a payment’

This example request refunds £50 of an available £500 for the payment with the payment reference hu20sqlact5260q2nanm0q8u93:

curl -X POST "https://publicapi.payments.service.gov.uk/v1/payments/01k7da2d0021m0pcbjov354et8/refunds" \
-H 'Authorization: Bearer api_test_123abc456def' \
-H 'Content-Type: application/json' \
-d '{
          "amount": 5000,
          "refund_amount_available" : 50000
}'

Example response for ‘Refund a payment’

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

{
    "refund_id": "4jfabcee0ev36so050kooajabk",
    "created_date": "2022-03-22T12:44:15.226Z",
    "amount": 1000,
    "status": "success",
    "_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"
        }
    }
}

Attributes you’ll get in a ‘Refund a payment’ response

Name	Type	Description
refund_id	string	The unique ID GOV.UK Pay associated with this refund when you created it. If you refund part of this payment again, each refund will have 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 Read more about the meanings of refund status values.
_links	object	Contains URLs and methods for actions related to this payment.
_links.self	object	Contains an API method and URL to get information about the refund you’ve just created. A GET request (method) to this URL (href) returns information about this refund.
_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.