Table of contents

Making payments

When you make a payment, you will need to supply a reference. If possible, this should be a unique identifier for the payment. If your organisation already has an existing identifier for payments, you can use it here.

You will also need to supply a return_url, a URL hosted by your service for the user to return to after they have completed payment on GOV.UK Pay. See the section below on Choosing the return URL for more information.

You will need to store the URL from the Location header or in the self section of _links in the JSON body (the same URL is shown in both places). This URL contains the GOV.UK Pay payment_id which identifies the payment. An authenticated GET request to the URL will return information about the payment and its status.

You can read more about this in the Reporting section of the documentation.

An example URL:{paymentId}

It is important that you do not expose the URL with the payment_id publicly, for example as a URL parameter or in an insecure cookie. You should store it as a secure cookie or in a database.

You will receive the next_url to which you should direct the user to complete their payment.

Tracking the progress of a payment

You can track the progress of a payment while the user is on GOV.UK Pay using the Find payment by ID call (link opens in new window).

NOTE: The status of the payment will go through several phases until it either succeeds or fails. See the API reference section for more details.

Choosing the return URL and matching user to payment

For security reasons, GOV.UK Pay does not add the payment ID or outcome to your return_url as parameters.

To match up a returning user with their payment, there are two recommended methods:

  • use a secure cookie containing the Payment ID from GOV.UK Pay, issued by your service when the payment is created (before sending the user to next_url). Users will not be able to decrypt a secure cookie, so a fraudster could not alter the payment ID and intercept other users’ payments.

  • create a secure random ID (such as a UUID) and include this as part of the return_url, using a different return_url for each payment. Since a securely generated UUID is not guessable, fraudsters will not be able to intercept users’ payments.

Note: If you create an ID yourself, you’ll likely need to store this in a datastore mapped to the payment ID just after you create a payment.

Accepting returning users

A user directed to the return URL could have:

  • paid successfully
  • not paid because their card was rejected or they clicked cancel
  • not paid because your service (via the API) or service manager (via the self-service dashboard) cancelled the payment in progress
  • not paid because of a technical error

Your service should use the API to check the payment status when the user reaches the return URL, and provide an appropriate response based on the final status of the payment attempt.

When a user does not complete their payment journey

The user may close their browser or lose internet connection in the middle of the payment flow on GOV.UK Pay. These users will not be redirected back to your service.

You can still check on the status of these payments by making a GET request using the Location Header or Self Link, the same way you would if they were redirected, but just after a set time (eg, an hour).

Note: GOV.UK Pay will expire incomplete payments after 90 minutes, but you should expect an occasional success or failure if the user experienced problems right at the moment of the redirect.

If a user does not have enough funds in their account to make a payment, the current GOV.UK Pay frontend will not let them try again with separate card details. They will have to return to the service to retry the payment.

Cancel a payment that’s in progress

Users can click a link on the payment page to cancel a payment that’s in progress. Alternatively, a service can make the following API call for a given paymentId:

POST /v1/payments/paymentId/cancel

A 204 response indicates success. Any other response indicates an error.

To test this with our API Explorer:

  • 1. Sign in to the API Explorer (link opens in new window).
  • 2. Under Resource, select {Payment Id}. Under Action, select Search payments (link opens in new window).

Find out if you can cancel a payment

Use a GET request against a single payment to find out if you can cancel it:

GET /v1/payments/paymentId

If the JSON response body contains a "cancel" field in the _links object that is not null, you can cancel the payment. For example:

    "cancel": {
    "href": "{paymentId}/cancel",
      "method": "POST"