Table of contents

Making payments

When a user makes a payment, your service should 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 as this reference.

The call to create a payment with the GOV.UK Pay API is:

POST /v1/payments

You can test this with our API explorer [external link].

The response to the ‘Create new payment’ API call will include the URL for the payment. You can get this from either:

  • the Location response header
  • the self section of _links in the JSON body

The URL contains the GOV.UK Pay paymentId, which is automatically generated and identifies the payment. A GET request to this URL will return information about the payment and its status.

Your service will need to store the paymentId (or the full URL) for each new payment you create. This is so you can check the status of these payments later.

You can read more in the “Reporting” and “Payment flow” sections of this documentation.

An example URL:{paymentId}

Your service will also need to supply a return_url. This is a URL that your service hosts for the user to return to, after their payment journey on GOV.UK Pay ends.

Warning You must not expose the URL with the `paymentId` or the `next_url` publicly, for example as a URL parameter or in an unencrypted cookie. You should store these values in encrypted cookies or in a database.

Track the progress of a payment

You can track the progress of a payment using the Find payment by ID call [external link]

The status of the payment will pass through several states until it either succeeds or fails. See the “API reference” section of this documentation for more details.

Choose the return URL and match users to payments

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

You can match users with payments with an encrypted cookie, or by creating a secure random ID:

You can use an encryped cookie containing the paymentId from GOV.UK Pay. Your service should issue this when a payment is created, before sending the user to next_url. Users will not be able to decrypt an encrypted cookie, so a malicious user could not alter the payment ID and intercept other users’ payments.

Create a secure random ID

You can create a secure random ID, such as a UUID, and include this as part of the return_url. You should use a different return_url for each payment. Malicious users will be unable to guess securely generated UUIDs,

If you use this method, you should store your IDs safely. For example, in a datastore mapped to the payment ID just after a payment is created.

Accepting returning users

A user directed to the return_url could have:

  • paid successfully

  • not paid because their card was rejected or they selected cancel

  • not paid because your service (via the API) 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

Users may close their browser or lose internet connectivity in the middle of their payment journey on GOV.UK Pay. In this event, users will not be redirected back to your service.

You can still check the status of these payments, but you should be aware GOV.UK Pay will allow a user 90 minutes to complete their payment before it expires. You can only be certain of the payment’s status after this time.

If a payment fails, GOV.UK Pay will not allow the user to attempt the payment again with alternative card details. In this situation the user would need to return to the service to retry the payment. Your service should account for this.

Cancel a payment that’s in progress

Users can select 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 the GOV.UK Pay API Explorer [external links]:

  1. Sign in to the API Explorer (link opens in new window).

  2. Under Resource, select {Payment Id}. Under Action, select Search payments.

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’s not null, you can cancel the payment. For example:

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