Skip to main content

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 "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:SSZ.
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.