Refund a payment

Warning If you are a member of the public requesting a refund, please contact the department you made the payment to. This page is for civil servants that take payments with GOV.UK Pay.

You can refund all or part of a payment using the GOV.UK Pay API or by signing into the GOV.UK Pay admin tool. This page focuses on refunding payments using our API.

Your user will receive the refund in the same account they originally paid from. You cannot refund a payment to another card or bank account.

Check if you can refund a payment

Before refunding a payment, check if you can make a refund by using the API to get information about the payment (GET /v1/payments/{PAYMENT_ID}).

The API response includes a refund_summary object containing details about:

whether you can refund the payment (status)
how much you can refund to the user, in pence (amount_available)
how much you’ve already refunded to the user, in pence (amount_submitted)

This is an example of a refund_summary object for a completed £50 payment with no previous refunds:

"refund_summary": {
  "status": "available",
  "amount_available": 5000,
  "amount_submitted": 0
}

This is an example of a refund_summary object for a completed £90 payment where £30 has already been refunded:

"refund_summary": {
  "status": "available",
  "amount_available": 6000,
  "amount_submitted": 3000
}

If status is available, you can refund the payment.

You can see definitions, values, and the limits of every parameter and response attribute for this endpoint in our API reference.

status

Status	Meaning
pending	You cannot refund the payment yet because your user has not completed the payment.
unavailable	You cannot refund the payment. There are two possible reasons for this: the payment failed the payment was processed by a PSP that we no longer support, such as ePDQ or Smartpay
available	You can refund the payment. Check how much you can refund in `amount_available`.
full	You cannot refund the payment because you’ve already refunded the full amount.

Creating a refund

POST /v1/payments/{PAYMENT_ID}/refunds

Replace {PAYMENT_ID} with the ID of the payment you are refunding.

In the body of your request, you must send:

amount - the amount you want to refund your user, in pence
refund_amount_available - the amount_available value you received when you checked if you could refund the payment

GOV.UK Pay will reject your refund request if refund_amount_available does not match the amount_available from GET /v1/payments/{PAYMENT_ID}.

This example requests refunds £20 of an available £50:

{
  "amount": 2000,
  "refund_amount_available": 5000
}

You can see definitions and possible values of these parameters in our API reference.

Response

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

{
  "amount": 2000,
  "created_date": "2019-09-19T16:53:03.213Z",
  "refund_id": "j6se0f2o427g28g8yg3u3i",
  "status": "submitted",
  ...
}

The response includes:

the amount refunded to the user in pence (amount)
when you created the refund (created_date)
the unique ID GOV.UK Pay associated with this refund (refund_id)
the status of the refund (status)

You can see full definitions of these response attributes in our API reference.

If GOV.UK Pay could not successfully create the refund, the JSON response will contain an API error code and a description of the error.

Checking the status of a refund

GET /v1/payments/{PAYMENT_ID}/refunds/{REFUND_ID}

Replace:

{PAYMENT_ID} with the ID of the payment you’re checking
{REFUND_ID} with the ID of the refund you’re checking

Example response:

{
  "amount": 2000,
  "created_date": "2019-09-19T16:53:03.213Z",
  "refund_id": "j6se0f2o427g28g8yg3u3i",
  "status": "success",
  "settlement_summary": {
    "settled_date": "2019-09-21"
  }
}

This response contains:

the amount refunded to the user (amount)
when you created the refund (created_date)
the unique ID GOV.UK Pay associated with this refund (refund_id)
the status of the refund (status)
when your payment service provider (PSP) refunded the payment, if your PSP is Stripe (settlement_summary)

You can see definitions and possible values of these attributes in our API reference.

status

The status attribute shows where the refund is in its lifecycle.

status	Meaning
submitted	We’ve submitted your refund request to your PSP. Refunds do not have a `submitted` status if you’re using your test (‘sandbox’) account.
success	Your PSP has successfully processed the refund.
error	Your PSP could not process the refund, usually because your user’s payment card is cancelled or expired, or you do not have enough money in your account to refund your user.

Where your PSP takes the refund amount from

If your user’s payment did not reach your bank account yet, your PSP will:

cancel the payment, if your PSP is Stripe
take the refund amount after the payment has reached your bank account, if your PSP is Worldpay

If the payment has reached your bank account, your PSP will take the refund amount from:

the next payment or payments you receive from any of your users, if your PSP is Stripe
your bank account, if your PSP is Worldpay

If your PSP is Stripe, you can see when Stripe took the refund by making an API request to check the status of a refund (GET /v1/payments/{PAYMENT_ID}/refunds/{REFUND_ID}) and looking at the settlement_summary object:

"settlement_summary": {
  ...
  "settled_date": "2019-09-21",
}

settled_date will be either:

the date Stripe took the refund from the payments that Stripe sent to your bank account
missing if Stripe has not yet taken the refund

Send email notifications about refunds

You can use the GOV.UK Pay admin tool to turn on sending refund email notifications to your users. To turn on refund email notifications, select your service in the GOV.UK admin tool, select Settings, and set Refund emails to On.

Get all refunds for a single payment

GET /v1/payments/{PAYMENT_ID}/refunds

Replace {PAYMENT_ID} with the ID of the payment you are getting the refunds for.

Example response:

{
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  ...
  "_embedded": {
    "refunds": [
      {
        "refund_id": "act4c33g40j3edfmi8jknab84x",
        "created_date": "2019-09-19T16:52:07.855Z",
        "amount": 120,
        "status": "success"
        "settlement_summary": {
          "settled_date": "2019-09-21"
        }
      },
      {
        "refund_id": "9rwjbdcpjd54ol1btog2a8zowh",
        "created_date": "2019-09-20T20:46:01.121Z",
        "amount": 60,
        "status": "success"
        "settlement_summary": {
          "settled_date": "2019-09-21"
        }
      }
    ]
  }
}

You can see definitions and possible values of every parameter and attribute for this endpoint in our API reference.

Searching refunds

GET /v1/refunds?{QUERY_PARAMETERS}

You can see a full index of the search parameters for this endpoint in our API reference.

This example search request would return refunds made between 1:30pm on 20 September 2019 and 3:00pm on 22 September 2019:

GET /v1/refunds?from_date=2019-09-20T13:30:00Z&to_date=2019-09-22T15:00:00Z

Example response:

{
  "total": 100,
  "count": 20,
  "page": 2,
  "results": [
    {
      "refund_id": "act4c33g40j3edfmi8jknab84x",
      "created_date": "2017-01-10T16:52:07.855Z",
      "amount": 120,
      "status": "success",
      "settlement_summary": {
        "settled_date": "2017-01-11"
      }
      "_links": {
        "payment": {
            "href": "https://publicapi.payments.service.gov.uk/v1/payments/5chu1yzxglqajfv97ous23s22i",
            "method": "GET"
        }
      ...
      }
    },
    {
      "refund_id": "efj6834secviyyxe8vs861pg3j",
      ...
    }
  ],
  "_links": {
    "prev_page": {
      "href": "https://publicapi.payments.service.gov.uk/v1/refunds?display_size=20&page=1",
      "method": "GET"
    },
    "next_page": {
      "href": "https://publicapi.payments.service.gov.uk/v1/refunds?display_size=20&page=3",
      "method": "GET"
    }
    ...
  }
  ...
}

You can see definitions and possible values of every attribute for this endpoint in our API reference.