Table of contents

Payment flow

This section outlines how your service will interact with GOV.UK Pay after integration.

This does not apply to users who use the payment links functionality.

Overview

When an end user needs to make a payment, your service makes an API call to create a new payment, then redirects the user to the payment pages hosted on GOV.UK Pay.

The end user enters their payment details (for example, credit/debit card details and billing address) on the GOV.UK Pay pages. GOV.UK Pay verifies the payment with the underlying Payment Service Provider(PSP).

After the transaction reaches a final state, the end user is then redirected back to your service.

A final state means that the payment:

  • succeeds
  • fails because it is declined
  • fails because the user chooses to cancel
  • fails due to a technical error
  • fails because it is cancelled by your service
  • fails because it times out - users have 90 minutes to complete a payment once it is created

When the user arrives back at your service, you can use the API to check the status of the transaction and show them an appropriate message.

Pay transaction states

Making a payment

This section contains an example of the payment flow, using an example.

The following image represents a page on a service where the end user needs to make a payment:

Flow service pay page

The payment pages are responsive and work on both desktop and mobile.

In your service, this page might be the end of a series of pages you host which allow the user to choose between a variety of possible payments.

This page should make it clear to the user that they are about to pay for your product or service with a clear call to action. For example, a button that says “Pay now” or “Continue to payment”. The user will then be taken to the GOV.UK Pay pages to complete their transaction.

The page should include clear information on what is being purchased. You do not need to tell the user that they are being handed over to GOV.UK Pay’s pages to make their payment.

When the user clicks Continue in the example page, the service makes a Create new payment call to the GOV.UK Pay API (link opens in new window). The body of the call contains information in JSON format.

For example:

{
  "amount": 14500,
  "reference" : "12345",
  "description": "Payment description",
  "return_url": "https://your.service.gov.uk/completed"
}
  • amount: the amount in pence - in this example, the payment is for £145.
  • reference: the reference number you wish to associate with this payment. The format is variable: if you have an existing format, you can keep using it with GOV.UK Pay (maximum 255 characters, and must not contain URLs)
  • description: a human-readable description of the payment. This will be shown to the end user on the payment pages and to your staff on the GOV.UK Pay admin site (maximum 255 characters, and must not contain URLs)
  • return_url: an HTTPS URL on your site that the user will be sent back to once they have completed their payment attempt on GOV.UK Pay (this should not be JSON-encoded as backslashes will not be accepted)

In the example, responses to the Create new payment API call would have headers of the form:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://publicapi.payments.service.gov.uk/v1/payments/icus7b4umg4b4g5fat4831es5f

And response bodies would be of the form:

{
  "payment_id": "icus7b4umg4b4g5fat4831es5f",
  "payment_provider": "acme",
  "amount": 14500,
  "state": {
    "status": "created",
    "finished": false
  },
  "description": "Payment description",
  "return_url": "https://your.service.gov.uk/completed",
  "reference": "12345",
  "created_date": "2016-06-24T11:46:11.414Z",
  "_links": {
    "self": {
      "href": "https://publicapi.payments.service.gov.uk/v1/payments/icus7b4umg4b4g5fat4831es5f",
      "method": "GET"
    },
    "next_url": {
      "href": "https://publicapi.payments.service.gov.uk/secure/bb0a272c-8eaf-468d-b3xf-ae5e000d2231",
      "method": "GET"
    },
 ...}  
}

The start of the response confirms the properties of the attempted payment.

The self URL (also provided in the Location header of the response) is a unique identifier for the payment. It can be used to retrieve its status details in future.

The next_url is the URL where your service should direct the end user next. It points to a payment page hosted by GOV.UK Pay where the user can enter their payment details. This is a one-time URL - after it’s been visited once, it will give an error message.

When your service redirects the user to next_url, they’ll see an Enter card details page similar to the following:

Flow payment details page

This page shows the description as well as the amount the end user has to pay, making it clear what they’re paying for.

The user enters their payment details and clicks Continue.

GOV.UK Pay will then attempt a payment authorisation through the Payment Service Provider (PSP). This checks with the card issuer whether there are sufficient funds available to make this payment and also carries out some anti-fraud checks.

Payment successful

If the details are valid and the payment is approved by the PSP, the user is then taken to a payment confirmation page, still hosted by GOV.UK Pay, where the user decides whether or not to complete their payment:

Flow payment confirm page

If the user decides to complete the payment, they click confirm. They will then:

  • receive a confirmation email (if you have chosen to send these using GOV.UK Pay)
  • be redirected to your return_url page which will then send the user to your payment confirmation page

Confirmation email

The user will receive a payment confirmation email containing:

  • a payment reference number
  • the date of payment
  • who the payment was to
  • the total payment amount

You can add a custom paragraph to a payment confirmation email at the email notifications page on the GOV.UK Pay admin site.

You can further customise using GOV.UK Notify to set up custom notifications. If you do this, the recommendation is to disable GOV.UK Pay notifications.

Confirmation page

The confirmation page is hosted by your service and should:

  • confirm that the payment has been received successfully
  • contain a reference number (which should be short)
  • have a clear payment summary, showing the amount and description
  • clearly state what is going to happen next (this will be different for each service)
  • if applicable, let the user know they will receive a receipt email (services can either use GOV.UK Notify to send email payment receipts or ask GOV.UK Pay to do that for them)

Users have different ways of recording this confirmation information. This can include screenshots, prints, PDF receipts to download, and writing down the reference number and other relevant information. Teams building services should be aware of all these behaviours, and plan accordingly.

Read more about confirmation pages in the GOV.UK Design System.

Payment failure

The payment can fail at any point in the process due to:

  • the payment being declined or the user choosing to cancel
  • a technical error
  • the payment being cancelled by your service

If the payment fails, the user will see a GOV.UK Pay error page. This includes a link to return to your service that states Go back to try the payment again. When a user returns to your service after a failed payment you should show them a page that offers useful next steps. This page should:

  • confirm that the payment failed
  • offer the user a chance to try the payment again either by initiating a new payment with GOV.UK Pay or using another method supported by your service
  • advise the user of an alternative course of action

The following image is an example failure page:

Flow payment declined

Check the status of a payment

Regardless of the payment outcome, when a payment journey has reached a final state, GOV.UK Pay will return the user to the return_url provided in the initial request.

The return_url should specify a page on your service. When the user visits the return_url, your service should:

  • match the returning user with their payment (with a secure cookie, or a secure random ID string included in the return_url)
  • check the status of the payment using an API call
  • display an appropriate final page (hosted by your service)

The “Making payments” section contains more details about how to match the user to the payment.

To check the status of the payment, you must make a Find payment by ID API call (link opens in new window), using the payment_id of the payment as the parameter.

The URL to do this is the same as the self URL provided in the response when the payment was first created.

The response body contains information about the payment encoded in JSON format. The following is the start of a typical response:

{
  "payment_id": "i3us7bqumg4b4g5fae48h1es5f",
  "payment_provider": "acme",
  "amount": 14500,
  "state": {
    "status": "success",
    "finished": true
  },
...
}

The state array within the JSON lets you know the outcome of the payment:

  • The status value describes a stage of the payment journey.
  • The finished value indicates if the payment journey is complete or not - that is, if the status of this payment can change.

See the “Making payments” section for more information about how you can integrate your service with GOV.UK Pay.

Resume a payment

If your user starts a payment but does not complete it, they can resume that incomplete payment. An example of this could be if they click the browser’s back button during a payment, and then go forward by clicking the links on your website.

If your service uses the resume payment feature, you will:

  • minimise the number of expired payments
  • not unnecessarily create new payments

Payment expires

Payments that are not confirmed and completed after 90 minutes will expire automatically.

If the payment was authorised but incomplete, GOV.UK Pay will send a cancellation to the payment provider. This will raise a P0020 API error.

Incomplete payments

An incomplete payment will have a status of created, started or submitted. These payment types have a next_URL. The next_URL is where you should direct the user next in the payment process. You will receive a next_URL every time you query the status of a payment using the API.

Resuming a payment

When a user resumes a payment, the next_URL will take them to a screen that is appropriate for their payment’s current status. For example, a payment with a started status will resume at the card details input page. The next_URL is a one-time URL. If a payment has already resumed using a next_URL, that URL will not be usable again.

A payment cannot resume if it has a status of success, failed, cancelled or error. If your service tries to resume a payment of this type, the user will be sent to your service’s return_url. The return_url is the URL of a page on your service that we send the user to after they have completed their payment attempt.