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.

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.

Creating a payment

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

POST /v1/payments

For example:

{
  "amount": 14500,
  "reference" : "12345",
  "description": "Pay your council tax",
  "return_url": "https://your.service.gov.uk/completed"
}

amount

amount is the amount in pence. In the example, the payment is for £145.

The amount must be a number data type rather than a string.

The minimum amount is one pence. The maximum amount is 10,000,000 pence (£100,000). Contact us if you need to take payments above the maximum amount.

reference

reference is the reference number you wish to associate with this payment.

The reference number does not need to be unique, and must not:

  • be longer than 255 characters
  • contain URLs

The format is variable. If you have an existing format, you can keep using it if your values are no longer than 255 characters.

description

description is a human-readable description of the payment. This is shown to the end user on the payment pages and to your staff on the GOV.UK Pay admin tool.

The description must be no longer than 255 characters, and must not contain URLs.

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.

The URL should not be JSON-encoded, because backslashes are invalid characters in the API.

If you’re making a test payment using a test account, you can use HTTP for return URLs instead of HTTPS.

Refer to the GOV.UK Pay API browser or the Swagger file for more information.

Receiving the API response

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: https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}

The response will also include the next_url to which you should direct the user to complete their payment.


Warning Don’t expose the `next_url` to anyone other than the paying user. Anyone in possession of the `next_url` could hijack the user’s payment.

Track the progress of a payment

You can track the progress of a payment using the Find payment by ID call.

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 encrypted cookie containing the payment ID 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.

Warning Make sure the way you match returning users to payments is tamper-proof. For example, don’t store the payment ID in an unencrypted cookie or rely on a `return_url` parameter that isn’t secret (like the payment ID or reference).

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.

See the GOV.UK Pay API browser for more details.

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": "https://publicapi.payments.service.gov.uk/v1/payments/{paymentId}/cancel",
      "method": "POST"