Table of contents

Refunding payments

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

Each payment has a refund status:

 
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 start a refund. Alone, this does not mean that the full original value of the payment is available to refund. For example, 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.

Refunds can have 3 states:

"submitted" "success" "error"

Payment refund status

You can find out the refund status of a payment with the GOV.UK Pay 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

GOV.UK Pay supports partial refunds, 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
  },

Find out the expected refund available

Your service should track the expected refund amount available. When you submit a refund request via the API, you can optionally include a refund_amount_available value in the request body. 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 for refund.

For example, a user makes a payment of £5, and 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 the request accidentally gets sent twice. Without finding out refund_amount_available, 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.

As another example, you may have specified the refund_amount_available as £5. The first refund request for £2 still succeeds, leaving £3 available for refund. When the accidental second request arrives, the payment has a refund_amount_available of £5 even though only £3 is available. GOV.UK Pay determines that it’s a stale request, and rejects the refund request.

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

Refund amount available mismatch

Refund requests rejected due to a “refund amount available mismatch” will return an error code P0604 with a 412 HTTP status.

Refunding with the GOV.UK Pay 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 such as:

{
"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_id values).

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.

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 a refund is accepted by GOV.UK Pay, it 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 process the refund.

Each successful request to a /refunds/ endpoint has a "status" value.

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",
...

In a live environment, the status returned will initially be submitted. After the PSP has processed the refund, the status returned will be success or error. In a test environment, the status will always go directly to success.

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

To manage refunds in live environments, 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 you need more information required about why a refund failed.

Refunding from the GOV.UK Pay admin tool

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

Go to the Transactions section to see a list of transactions. For example, in the following image::

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 make a full or partial payment.

Refund payment button

Refund email notifications

You can use the GOV.UK Pay admin tool to send email notifications to users.

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. It is the responsibility of the service to provide an alternative refund method.

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.