Take a payment

This section tells you how to take a payment using the GOV.UK Pay API.

You can also take payments using our no-code solution, payment links.

When your 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 your user to return to, after their payment journey on GOV.UK Pay ends.

Creating a payment

To create a payment with the GOV.UK Pay API, use this endpoint:

POST /v1/payments

You must send the following parameters in your request body when creating a payment:

the amount the user will pay, in pence (amount)
a reference to help you identify the payment (reference)
a human-readable description of the purpose of the payment (description)
a URL to redirect your user to after they complete their payment (return_url)

This example request creates a £145 council tax payment:

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

Depending on your integration, you can also:

Your user has 90 minutes to complete their payment once you have created it.

You can see definitions, values, and the limits of every parameter for this endpoint in our API reference.

Avoid redundant entry

Web Content Accessibility Guidelines (WCAG) 2.2 specifies that ‘services should avoid asking users for the same information twice in the same session’.

Consider prefilling some payment fields if your service already collects any details the user will need to enter when they pay. To do this, include the prefilled_cardholder_details object when you create the payment. You can read more about how to prefill payment fields.

amount

The amount parameter sets the payment amount in pence. amount must be a number.

The minimum amount is one pence plus your payment service provider’s (PSP’s) transaction fee. To see your PSP’s transaction fee, check your contract by either:

signing into the GOV.UK Pay admin tool if you use Stripe
contacting Government Banking if you are using Worldpay
asking your PSP

The maximum amount is either:

10,000,000 pence (£100,000)
500,000 pence (£5,000) if you use Government Banking

Receiving the API response

If your request to create a payment succeeds, you’ll receive a response that looks like this:

{
  "created_date": "2020-03-03T16:17:19.554Z",
  "state": {
    "status": "created",
    "finished": false,
  },
  "_links": {
    "self": {
      "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93",
      "method": "GET"
   },
    "next_url": {
      "href": "https://www.payments.service.gov.uk/secure/bb0a272c-8eaf-468d-b3xf-ae5e000d2231",
      "method": "GET"
    },
    ...
  },
  "amount": 14500,
  "reference" : "12345",
  "description": "Pay your council tax",
  "return_url": "https://your.service.gov.uk/completed",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "provider_id": "10987654321",
  ...
}

This response includes:

the details you sent in your request (amount, description, reference, return_url)
the unique ID GOV.UK Pay assigned to this payment (payment_id)
the unique ID your PSP assigned to this payment (provider_id)
the date and time you created the payment (created_date)
the URL the paying user will visit to make this payment (_links.next_url)
the URL and method you can use to check the status of this payment (_links.self)
other URLs and API methods for further actions for this payment (_links)

You can see full definitions and values for every response attribute in our API reference.

Read more about reporting and reconciliation and payment flow.

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

Track the progress of a payment

You can track the progress of a payment by getting information about it from the reporting API or by receiving automatic updates through a webhook.

The status of the payment will pass through several states until it either succeeds or fails. Read more about the payment status lifecycle in our API reference.

Choose the return URL and match your users to payments

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

You must use HTTPS for your return_url, but you can use HTTP with test accounts.

You can match your 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 you create a payment, before sending your user to next_url. Your 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 you create a payment.

Warning Make sure the way you match your 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 your users when they return

If your user is directed to the return_url, they 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 a GET /v1/payments/{PAYMENT_ID} request to check the payment’s status when your user reaches the return_url. You should provide an appropriate response based on the state the payment attempt.

Do not use other API requests to check the payment’s status. Other requests, such as search payments, do not update immediately and so may not be up to date.

When your user does not complete their payment journey

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

You can still check the status of these payments, but you should be aware that the payment will expire 90 minutes after it was created. You can only be certain of the payment’s status after this time.

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

Resume an incomplete payment

You can send paying users back to GOV.UK Pay if they return to your service before they’ve finished their payment.

Get information about the payment to check the payment’s status. The payment is incomplete if the status is one of the following:

created
started
submitted

Resume the payment by redirecting the paying user to the next_url in the API response.

Do not reuse the next_url you received in the API response when you first created the payment. Each next_url has a unique token so you can only use that next_url once.

GOV.UK Pay will take your user to a screen that’s appropriate for the status of the payment and lets the paying user finish their payment. For example, if the status of the payment is submitted, we’ll show the Confirm your payment page.

You cannot resume a payment if the status is failed, cancelled, or error. Create a new payment instead.

Cancel a payment that’s in progress

Your user can select a link on the payment page to cancel a payment that’s in progress. Alternatively, you can make the following API request:

POST /v1/payments/{PAYMENT_ID}/cancel

Replace {PAYMENT_ID} with the ID of the payment you are cancelling.

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

You can see parameters, example requests, and example responses for this endpoint in our API reference.

Check if you can cancel a payment

Get information about a specific payment to check if you can cancel that payment:

GET /v1/payments/{PAYMENT_ID}

Replace {PAYMENT_ID} with the ID of the payment you are checking.

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/hu20sqlact5260q2nanm0q8u93/cancel",
  "method": "POST"
}