Table of contents

Refunding payments

GOV.UK Pay supports refunding payments. You can choose to refund part of a payment, or the full amount.

After issuing a partial refund of a payment, you can issue further partial refunds, until the full amount of the original payment has been refunded.

Each payment has a refund status which can take one of the following values:

 
Payment refund status Meaning
pending The payment is potentially refundable, but is not ready to be refunded yet.
unavailable It is not possible to refund the payment: for example, the payment failed.
available It’s possible to initiate a refund. Note that this does not mean that the full original value of the payment is available to refund: there may have been previous partial refunds.
full The original value of the payment has been fully refunded, so it is not possible to refund any more.
 

For test accounts, you will not see the pending state because there is no delay in processing a payment when testing. For live accounts, successful payments spend some time in pending state before a refund becomes possible.

Each refund will have one of the following states:

"submitted" "success" "error"

Payment refund status and partial refunds

You can find out the refund status of a payment with the API using the Find payment by ID or Search payments functions (links open in new window).

The JSON response body will contain a refund_summary object. For example, for a completed £50 payment with no previous refunds:

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

The amount_available value includes any corporate card surcharges.

The amount_submitted is 0, showing that there have been no previous refunds.

Partial refunds are possible, and you can make multiple partial refunds against the same payment. The total refunds for a single payment cannot be greater than the original payment.

You can use the Get all refunds for a payment (link opens in new window) API call to get information about partial refunds.

As another example, this is the JSON response body for a completed £90 payment with a previous refund of £30:

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

Specifying the expected refund available

When you submit a refund request for a payment via the API, you can optionally specify a refund_amount_available value in the body of the request. This is so you can provide the total amount of the original payment you expect to be available for refund at the time your refund request is made.

The purpose of this is to prevent accidentally processing a partial refund more than once, by rejecting requests where your refund_amount_available does not match the real amount that’s available to be refunded.

For example, a payment is made for £5, but later the user requires a £2 refund. Your system for processing refunds submits a request for a £2 refund to the GOV.UK Pay API, but it accidentally gets sent twice. Without a refund_amount_available specified, GOV.UK Pay would have no way to tell the second request was a mistake. It would process both requests, generating two refunds of £2 each.

In the same scenario, if you had specified the refund_amount_available as £5. The first request still succeeds, leaving £3 available to be refunded. When the accidental duplicate request comes in, it has a refund_amount_available of £5, even though only £3 is available, so GOV.UK Pay can tell that it’s a stale request, and it is rejected.

We recommend that your service tracks the expected refund amount available and submits a refund_amount_available value whenever you request a refund via the API.

When a refund request is rejected due to a refund amount available mismatch, the error code returned is P0604, with an HTTP status of 412.

You must include any corporate card surcharges in the refund_amount_available value.

Refunding with the API

You can start a refund with the Submit a refund for a payment function (link opens in new window).

You need to specify the paymentId of the original payment, and provide the amount to refund (in pence).

You should check that the amount you attempt to refund does not exceed the amount_available value; otherwise you will receive a P0603 error like this:

{
"code": "P0603",
"description": "The payment is not available for refund. Payment refund status: amount_not_available"
}

Each refund has a unique refund_id.

You can use the Get all refunds for a payment function (link opens in new window) to get information all the refunds for a payment (including their refund_ids).

You can retrieve information about an individual refund using the Find payment refund by ID function (link opens in new window).

A 204 response from the API indicates that a refund was successful. Any other response indicates an error.

Handling refund errors

When you try to create a refund with the API, it may fail immediately - for example if you try to refund more than the amount available. In that case, the original Submit a refund for a payment request (link opens in new window) will return an error code and a description of what it means. (A refund attempt that fails like this with an error code is not assigned a refundId and is not available using Find payment refund by ID (link opens in new window)).

If accepted by GOV.UK Pay, a refund may still go on to fail at the PSP. This may happen if the card involved is cancelled or has expired, or if your account with the PSP does not have enough funds to cover the refund.

Each refund has a processing status indicated by a “status” value that is returned in response to a successful request to a /refunds/ endpoint.

For example, the response body for a refund would include:

{
"amount": 1500,
"created_date": "2016-10-17T16:53:03.213Z",
"refund_id": "j6se0f2o427g28g8yg3u3i",
"status": "submitted",
...

Initially, in a live environment, the status returned will be submitted. After the PSP has processed the refund, the status returned will be success or error. (In the test environment, the status will always go straight to success).

 
Refund processing status Meaning
submitted The refund request is valid as far as GOV.UK Pay can tell and has been passed to the underlying payment processor.
success The refund has been successfully processed.
error It was not possible for the payment processor to make the refund.
 

To manage this, you must use Find payment refund by ID (link opens in new window) to check the processing status of the refund until it changes to either success or error.

It will typically take 30 minutes for the status to change. You should not check the status more than once every 5 minutes.

In the event of an error, GOV.UK Pay will not currently provide any more information. Please contact us if more information is required about why a refund failed.

Refunding from the GOV.UK Pay admin site

You can use the GOV.UK Pay admin site to view transactions and issue refunds.

Go to the Transactions section of your accoun page to see a list of transactions. For example:

Transaction+list+image+4

In this list, you can select an individual payment to see details of that payment, including any previous refunds.

For a successful payment with no previous refunds, you can use the red Refund payment button to carry out a full or partial payment.

Refund payment button

Refund notifications

End users are automatically notified by email about successful payments. This depends on settings you have entered in the self-service admin site. Users are not notified when a payment has either failed or is refunded - either manually or via the API. You should arrange to notify end users about payment failures and refunds as appropriate for your service.

Refund destination

Refunds are sent back to the source account of the original payment. It is not possible to refund a payment to another card or bank account. If the original card expired or was canceled, the bank will attempt to credit the customer’s new card with the refund. If this attempt fails, or the customer does not have a new card, the refund will have to be made using another channel (eg bank transfer or cheque).

Search refunds with the API

You can use the GOV.UK Pay API to:

  • get information about a single refund
  • generate a list of refunds matching search criteria

Get information about a single refund

GET /v1/refunds/paymentId

The JSON response body to this API call contains a "refunds" object. If the refund exists, the "status" field will contain one of:

  • "submitted"
  • "success"
  • "error"

Generate a list of refunds (search refunds)

GET /v1/refunds

An example search request:

GET /v1/refunds?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z

Filter by date

You can use the following query parameters to filter refunds by date:

  • from_date - the start date for payments to be searched, inclusive
  • to_date - the end date for payments to be searched, exclusive

These take inputs based on a subset of ISO 8601 (link opens in new window). For example, a valid input would be 2015-08-13T12:35:00Z.

Pagination

You can use the following query parameters for pagination:

  • display-size - default, and maximum, is 500
  • page - default is 1

These must be a positive integer. For example, for the following search:

GET /v1/refunds?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z

If there were 1543 refunds in the response, you could paginate this as follows:

GET /v1/refunds?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z&display-size=500&page=2

This would return refunds 501-1000.