Table of contents
Close

This Documentation

This documentation is for developers, technical architects and service managers interested in using GOV.UK Pay.

If your problem or question is not addressed in this documentation, please contact us at govuk-pay-support@digital.cabinet-office.gov.uk, including any error messages you’re getting.

About GOV.UK Pay

GOV.UK Pay makes it easy for departments and agencies across government to take payments. It provides a standard set of GOV.UK branded pages which can be incorporated into a service to take payments, and an admin console which enables services to administer and process payments taken through GOV.UK Pay. Much of GOV.UK Pay’s functionality can be incorporated into existing case management tools via our API.

GOV.UK Pay is currently in beta development. The payment pages are responsive and work on both desktop and mobile.

The platform can connect your government service to different payment service providers (PSPs).

During beta, GOV.UK Pay will support credit and debit card payments only. Over time, further payment methods, such as direct debit or eWallet, will be added.

Your service only needs to integrate with GOV.UK Pay once to let your users make credit and debit card payments. When GOV.UK Pay is expanded to accept other payment methods, your service will not have to undertake any new integration. Using GOV.UK Pay will save your team time compared to implementing support for multiple PSPs and payment methods from scratch.

The platform currently supports one-off payments (like fees, fines or licence payments). In the future, it will also support recurring payments, for example, monthly tax payments.

The GOV.UK Pay platform does not currently support payments to cardholders, for example, payments of benefits, or grants. The platform only supports taking payments, or providing refunds.

There are five departments and agencies currently partnering with the platform:

  • Ministry of Justice
  • Home Office
  • Department for Business, Energy & Industrial Strategy
  • Office of the Public Guardian
  • HM Courts and Tribunals Service

To find out more about GOV.UK Pay, read our blogs and newsletters.

How much does it cost?

There is no charge to use GOV.UK Pay. You will still need to pay your PSP’s transaction fees.

Before you start

To start using the GOV.UK Pay platform, you’ll need:

  • a digital service that needs to process payments
  • a GOV.UK Pay account
  • a service team with the development skills to build the technical integration with GOV.UK Pay; refer to the Service Manual for more information

Check the Getting Started guide to ensure that your team is ready to start using the GOV.UK Pay platform.

Make sure you’re also familiar with the government guidance on deploying new software.

If you are new to the GOV.UK Pay API, we recommend you take a look at the quick start guide, which explains how to access the API and start exploring what it can do.

How long will it take?

The time taken to integrate will vary depending on team and capability; for example, it took a single developer five days to integrate a Home Office service with GOV.UK Pay.

Quick start guide

The GOV.UK Pay platform is based on REST principles with endpoints returning data in JSON format, and standard HTTP error response codes. The platform API allows you to:

  • initiate and complete payments
  • issue refunds
  • view the event history for individual payments
  • view transactions within a specified time period

    This section explains how to get started with our API Explorer and make a test API call.

Generate API Key for API Explorer

  1. Sign in to the GOV.UK Pay admin site with the sandbox account login details you received.

  2. Click on the API key section, then click Generate a new key.

Pay 9

Enter a description for your API key.

Describeapikey+image2

Your API key will be shown on the screen for you to copy.

Newkeygenerate+image+3

You must store your API keys away securely. Make sure you never share this key in publicly accessible documents or repositories, or with people who shouldn’t be using the GOV.UK Pay API directly. Read our security section for more information on how to keep your API key safe.

API Explorer setup

The quickest way to learn about the API is to use the API Explorer (link opens in new window) with the API key that you just created.

  1. Go to the API Explorer (link opens in new window) and click the blue “Add API Credentials” button.

    Pay add api key

  2. In the resulting pop-up, enter the following values:
    • For API Key, enter “[YOUR-API-KEY]” (do not include the quotation marks), replacing [YOUR-API-KEY] with the actual value of your sandbox API key, as shown in the screenshot below. You do not need to put the “Bearer: ” prefix which is required when calling the API from code; the API Explorer adds that automatically.
    • For Label, enter “Authorization” (do not include the quotation marks).

Make sure you are using an API key from your sandbox account on the admin site, not the live account.

Making a test API call

You will now make a test API call to GOV.UK Pay by creating a new payment. This is the call your service will make when initiating a payment using GOV.UK Pay.

  1. To test the API Explorer, select General from the API Explorer Resource dropdown menu. Select Create new payment (link opens in new window) from the API Explorer Action dropdown menu. Click on the Body tab lower down to see an example JSON body that you would send when creating a payment.
{
"amount": 12000,
"reference": "12345",
"description": "New passport application",
"return_url": "https://service-name.gov.uk/transactions/12345"
}

As well as details of the payment, you’ll notice that you need to send a return_url when creating a payment. The reason for this is that users go to GOV.UK Pay hosted pages to actually make their payment. The return_url is the URL of a page on your service that the user will be redirected to after they have completed their payment (or payment has failed).

Pay api explorer createpay

  1. Click the green Send Request button.

  2. If the API Explorer is set up correctly, you will receive a 201 Created response with a JSON body, confirming that the payment was created. Note that the JSON includes a next_url link. This URL is where your service should redirect the user for them to make their payment.

    Pay api explorer response

Follow end user payment journey

  1. Go to the next_url with your browser. You’ll see the payment screen. Refer to the Testing GOV.UK Pay section to find a mock credit card number that you can enter to simulate a payment in the sandbox environment. For the rest of the details, enter some test information, bearing in mind that:

    • the expiry date must be in the future and in the format MM/YYYY
    • the postcode must be valid
  2. Submit the payment.

View transaction at GOV.UK Pay Admin site

  1. Go to the service admin site. Select Transactions at left. You’ll see the payment you just made.

Transaction+list+image+4

Payment flow overview

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

Overview of payment flow

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 Pay pages. Pay handles all the details of verifying the payment with the underlying Payment Service Provider.

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 either because it is declined or the user chooses to cancel
  • fails due to a technical error
  • fails because it is cancelled by your service

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

Payment flow: making a payment

Let’s walk through an example of the payment flow in more detail.

Imagine that this is a page on your 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.

Note that this page might be the end point 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
  • 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

The user clicks Continue.

At this point, your service makes a Create new payment call to the Pay API (link opens in new window). The body of the call contains information in JSON format:

{
  "amount": 14500,
  "reference" : "12345"
  "description": "Payment description",
  "return_url": "https://your.service.gov.uk/completed",
}
  • amount: in pence; in this example, the payment is for £145
  • reference: This is the reference number you wish to associate with this payment. The format is up to you, so if you have an existing format, you can keep using it with Pay (maximum 255 characters; it 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; it must not contain URLs)
  • return_url: This is 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)

This is the header and the first part of the JSON body of the response to the Create new payment API call that your service will receive:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://publicapi.pymnt.uk/v1/payments/icus7b4umg4b4g5fat4831es5f
{
  "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.pymnt.uk/v1/payments/icus7b4umg4b4g5fat4831es5f",
      "method": "GET"
    },
    "next_url": {
      "href": "https://www-integration-2.pymnt.uk/secure/bb0a272c-8eaf-468d-b3xf-ae5e000d2231",
      "method": "GET"
    },
 ...}  
}

The beginning 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 you should now direct the end user. It points to a payment page hosted by GOV.UK Pay where the user can enter their payment details. Note that 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 see a page something like this:

Flow payment details page

The page shows the description you provided 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 Flow: 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, and will:

  • receive a confirmation email (if you have chosen to send these using GOV.UK Pay)
  • be re-directed 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. For further customisation, you can visit GOV.UK Notify to set up custom notifications. It is recommended to disable GOV.UK Pay notifications if you do this.

Confirmation page

The confirmation page is hosted by you and should:

  • confirm that the payment has been received successfully
  • contain a reference number (make them short and usable)
  • 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, including screenshots, prints, pdf receipts to download, and writing down the reference number and other relevant information. Teams building services should be aware of, and cater for, all these behaviours.

Read more about confirmation pages in the service manual.

Payment Flow: Payment fails

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

An example can be seen below:

Flow payment declined

Payment flow: Check the status of a payment

Regardless of the payment outcome, when a payment journey has reached a terminal state, GOV.UK Pay will return the user to the return_url you 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 as outlined above (hosted by your service)

See the Integration details section for 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. Here is the beginning 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.

Now that you understand the payment process, see the Integration details section for more about how you can integrate your service with GOV.UK Pay.

API reference

The GOV.UK Pay platform is based on REST principles with endpoints returning data in JSON format, and standard HTTP error response codes. The platform API allows you to:

  • initiate and complete payments
  • view the event history for individual payments
  • view transactions within a specified time period
  • provide full or partial refunds

API overview

The base URL for the API is https://publicapi.payments.service.gov.uk/

The same base URL is now used for testing and live. The API key you use determines if the actions are treated as sandbox test payments or processed as real payments.

For full details of each API action, see the API Browser:

You can also use our interactive API Explorer (link opens in new window) to try out API calls and view responses.

See the Quick Start Guide section for how to set up the API Explorer. Make sure you enter your sandbox API key to avoid generating real payments!

API authentication

GOV.UK Pay authenticates API calls with OAuth2 HTTP bearer tokens. These are easy to use and consist of one component: your API key. Bearer tokens are specified in RFC 6750.

When making an API call, you’ll need to add your API key to an “Authorization” HTTP header and prefix it with “Bearer ”. This is an example of how a header would look.

Authorization: Bearer 2o9bkusxaicha5c9gnsj790of7asggo1feraoufbai4a

Payment status lifecycle

This diagram gives an overview of the payment status lifecycle and the possible outcomes.

Pay transaction states

You can check the status of a given payment using the Find payment by ID API call (link opens in new window).

The response will include a status value as described in the table below, and a true/false finished value which indicates if the status can change.

status value Meaning finished value
created Payment created; user has not yet visited next_url false
started User has visited next_url and is entering payment details false
submitted User has submitted payment details but has not yet clicked Confirm false
success User successfully completed the payment true
failed User attempted to make a payment but the payment did not complete. Possible reasons: user cancelled; user entered payment details but never confirmed; payment declined due to insufficent funds; payment declined due to fraud or other checks true
cancelled Your service cancelled the payment using an API call or the self-service site. true
error Something went wrong with GOV.UK Pay or the underlying Payment Service Provider. true

HTTP status codes

You will encounter typical HTTP success and error response codes when using the Pay API. Generally any:

  • 100 code is informational
  • 200 code indicates you’ve been successful
  • 300 code indicates a redirection
  • 400 code indicates a client error (your error)
  • 500 code indicates a server error (something went wrong on the GOV.UK Pay end)

These are the known error codes you are likely to receive:

Common error code Meaning
200 Payment information request succeeded
201 Payment has been created
204 The server successfully processed the request, but is not returning any content
400 The server cannot process the request due to a client error, e.g. missing details in the request or a failed payment cancellation
401 Required authentication has failed or not been provided
404 The resource you want cannot be found
412 Precondition failed: e.g. mismatch in expected refund amount available
422 Unprocessable entity obtained on a request validation
Any 500 error Something is wrong with GOV.UK Pay - please contact us

API error codes

When an error occurs, you will receive these API codes in the body of the response.

This is the format of the general JSON error response body:

{
  "code": "PXXXX",
  "description": "Message explaining the error"
}

Note that the description provided is written to be informative to you, the developer, and is not intended for the end user.

Also note that extra keys, e.g field, may be provided on a per-error basis.

These error codes provide more information about why a request failed.

Request type Error code Meaning Cause
Create payment P0101 Missing mandatory attribute The request you sent is missing a required attribute
Create payment P0102 Invalid attribute value The value of an attribute you sent is invalid
Create payment P0197 Unable to parse JSON The JSON you sent in the request body is invalid
Create payment P0198 Downstream system error Internal error with GOV.UK Pay: contact us, quoting the error code
Create payment P0199 Account error There is a problem with your service account: contact us, quoting the error code
Find payment by ID P0200 paymentId not found No payment matched the paymentId you provided
Find payment by ID P0298 Downstream system error Internal error with GOV.UK Pay: contact us, quoting the error code
Return payment events by ID P0300 paymentId not found No payment matched the paymentId you provided
Return payment events by ID P0398 Downstream system error Internal error with GOV.UK Pay: contact us, quoting the error code
Search payments P0401 Invalid parameters The parameters you sent are invalid.
Search payments P0402 Page not found The requested page of search results does not exist
Search payments P0498 Downstream system error Internal error with GOV.UK Pay: contact us, quoting the error code
Cancel payment P0500 paymentId not found No payment matched the paymentId you provided
Cancel payment P0501 Cancellation failed Cancelling the payment failed; contact us, quoting the error code
Cancel payment P0598 Downstream system error Internal error with GOV.UK Pay; contact us, quoting the error code
Create refund P0600 paymentId not found No payment matched the paymentId you provided
Create refund P0601 Missing mandatory attribute The request you sent is missing a required attribute
Create refund P0602 Invalid attribute value The value of an attribute you sent is invalid
Create refund P0603 Refund not available The payment is not available for refund.
Create refund P0604 Refund amount available mismatch The refundamountavailable value you provided does not match the true amount available to refund.
Create refund P0697 Unable to parse JSON The JSON you sent in the request body is invalid
Create refund P0698 Downstream system error Internal error with GOV.UK Pay; contact us, quoting the error code
Get refund P0700 refundId not found No refund matched the refundId you provided
Get refund P0798 Downstream system error Internal error with GOV.UK Pay; contact us, quoting the error code
Get refunds P0800 refundId not found No refund match the refundId you provided
Get refunds P0898 Downstream system error Internal error with GOV.UK Pay; contact us, quoting the error code
General P0900 Too many requests Your service account is sending requests above the allowed rate; try the request again in a few seconds
General P0920 Request blocked by security rules Our firewall blocked your request. See Troubleshooting section for details.
General PO999 GOV.UK Pay is unavailable The GOV.UK Pay service is temporarily down.

Card types

These are the possible values of the card_brand parameter.

card_brand type label
visa DEBIT Visa
visa CREDIT Visa
master-card DEBIT Mastercard
master-card CREDIT Mastercard
american-express CREDIT American Express
diners-club CREDIT Diners Club
discover CREDIT Discover
jcb CREDIT Jcb
unionpay CREDIT Union Pay

API rate limits

There is a maximum rate limit for requests to the API from your service account. The limit is high and most services are unlikely ever to exceed it.

If you do exceed the limit (that is, send a large number of requests in a short amount of time), you will receive P0900 errors. If this happens, you can attempt any rate-limited requests again after a second has passed.

Please contact us if you want to discuss the rate limiting applied to your service account.

Integration details

This section gives more technical detail about how to integrate your service with GOV.UK Pay.

Creating a payment

When you make a payment, you will need to supply a reference. This is 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/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 uniquely identifies the payment. An authenticated GET request to the URL will return information about the payment and its status.

It is important that you do not expose the URL with the payment_id publically, 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. During the GOV.UK Pay beta, it is only returned in response to the initial POST call to create a payment, not on sub. It will only work once.

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 won’t 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 doesn’t 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 eventually expire incomplete payments, 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. This will soon be fixed as part of the beta.

Cancelling a payment

You can cancel a payment that is not yet in a final state by using the Cancel payment API call (link opens in new window).

Financial reporting integration

If you’re a beta partner, the GOV.UK Pay team will hold technical workshops with you to discuss how to integrate the reporting from GOV.UK Pay with your own financial systems.

With our API, you’ll be able to:

  • GET the status of an individual payment
  • cancel a payment that’s not yet captured
  • soon get the status of multiple payments based on certain criteria, e.g. date range (this feature is under development)
  • soon issue full and partial refunds (this feature is under development)

Refunding payments

GOV.UK Pay now supports refunding payments. You can choose to refund part of a payment, or the full amount.

After issuing a partial refund of a payment, you can issue further partial refunds, until the full amount of the original payment has been refunded.

Each payment has a refund status which can take one of the following values:

Payment refund status Meaning
pending The payment is potentially refundable, but is not ready to be refunded yet.
unavailable It is not possible to refund the payment: for example, the payment failed.
available It’s possible to initiate a refund. Note that this does not mean that the full original value of the payment is available to refund: there may have been previous partial refunds.
full The original value of the payment has been fully refunded, so it is not possible to refund any more.

In the sandbox, you will not see the pending status as there is no delay in processing a payment. In a live environment, successful payments will spend some time in pending state before a refund becomes possible.

This refund status is a property of a payment; each refund will also have its own status of submitted/success/error.

Payment refund status and partial refunds

You can find out the refund status of a payment with the API using the Find payment by ID or Search payments functions (links open in new window).

The response will contain a refund_summary section. Here is an example of that section of the response for a completed £50 payment with no previous refunds:

  "refund_summary": {
    "status": "available",
    "amount_available": 5000,
    "amount_submitted": 0
  },

In this example, the refund status of the payment is available, indicating that a refund can be initiated. The amount_available value is 5000: that is, £50 is available to be refunded.

The amount_submitted is 0, showing that there have been no previous refunds.

Partial refunds are possible, and you can make multiple partial refunds against the same payment. As you’d expect, the total of refunds against a payment can’t be greater than the original payment.

Here’s another example:

  "refund_summary": {
    "status": "available",
    "amount_available": 6000,
    "amount_submitted": 3000
  },

In this case, the original payment was for £90. The amount_available value shows that only £60 is available to be refunded, because £30 has already been refunded in one or more partial refunds (as shown by amount_submitted).

If you needed to know the details of the partial refunds (for example, whether there had been a single refund of £30 or multiple smaller refunds), you could use the API function to Get all refunds for a payment (link opens in new window).

Specifying the expected refund available

When you submit a refund request for a payment via the API, you can optionally specify a refund_amount_available value in the body of the request.

This is so you can provide the total amount of the original payment you expect to be available for refund at the time your refund request is made.

The purpose of this is to prevent accidentally processing a partial refund more than once, by rejecting requests where your refund_amount_available doesn’t match the real amount that’s available to be refunded.

For example, suppose a payment was made for £5, but later it turns out the user is due a £2 refund. Your system for processing refunds submits a request for a £2 refund to our API, but it accidentally gets sent twice. Without a refund_amount_available specified, GOV.UK PAY would have no way to tell the second request was a mistake, so it would process both requests, generating two refunds of £2 each.

Now imagine the same scenario, but if you had specified the refund_amount_available as £5. The first request still succeeds, leaving £3 available to be refunded. When the accidental duplicate request comes in, it has a refund_amount_available of £5, even though only £3 is available, so GOV.UK PAY can tell that it’s a stale request, and it is rejected.

We recommend that your service tracks the expected refund amount available and submits a refund_amount_available value whenever you request a refund via the API.

When a refund request is rejected due to a refund amount available mismatch, the error code returned is P0604, with an HTTP status of 412.

Refunding with the API

You can initiate a refund with the Submit a refund for a payment function (link opens in new window).

You need to specify the paymentId of the original payment, and provide the amount to refund (in pence).

You should check that the amount you attempt to refund does not exceed the amount_available value; otherwise you will receive a P0603 error like this:

{
"code": "P0603",
"description": "The payment is not available for refund. Payment refund status: amount_not_available"
}

Each refund has a unique refund_id.

You can use the Get all refunds for a payment function (link opens in new window) to get information all the refunds for a payment (including their refund_ids).

You can retrieve information about an individual refund using the Find payment refund by ID function (link opens in new window).

Handling refund errors

When you try to create a refund with the API, it may fail immediately - for example if you try to refund more than the amount available. In that case, the original Submit a refund for a payment request (link opens in new window) will return an error code and a description of what it means. (A refund attempt that fails like this with an error code is not assigned a refundId and is not available using Find payment refund by ID (link opens in new window)).

If accepted by GOV.UK Pay, a refund may still go on to fail at the PSP. This may happen if the card involved is cancelled or has expired, or if your account with the PSP does not have enough funds to cover the refund.

Each refund has a processing status indicated by a “status” value that is returned in response to a successful request to a /refunds/ endpoint.

This is a partial example of a response including the refund’s processing status:

{
"amount": 1500,
"created_date": "2016-10-17T16:53:03.213Z",
"refund_id": "j6se0f2o427g28g8yg3u3i",
"status": "submitted",
...

Initially, in a live environment, the status returned will be submitted. After the PSP has processed the refund, the status returned will be success or error. (In the sandbox environment, the status will always go straight to success).

Refund processing status Meaning
submitted The refund request is valid as far as GOV.UK Pay can tell and has been passed to the underlying payment processor.
success The refund has been successfully processed.
error It was not possible for the payment processor to make the refund.

To handle this, you must use Find payment refund by ID (link opens in new window) to check the processing status of the refund until it changes to either success or error.

It will typically take 30 minutes for the status to change. We suggest you check the status after 30 minutes, and do not repeat more than once every 5 minutes.

In the event of an error, GOV.UK Pay will not currently provide any more information. Please contact us if more information is required about why a refund failed.

Refunds from the admin site

As an alternative to refunding via the API, you can use the service admin site at https://selfservice.payments.service.gov.uk to view transactions and issue refunds.

Go to the Transactions section of the site to see a list of transactions.

Transactions section

In this list, click on the reference for an individual payment (in the Reference number column) to see details of that payment (including any previous refunds).

In the details view, you can use the red Refund payment button at the upper right to carry out a full or partial payment.

Refund payment button

Refund notifications

End users are automatically notified by email about successful payments (according to the settings you have entered in the self-service admin site), but not when a payment has either failed or is refunded (either manually or via the API). You should arrange to notify end users about payment failures and / or refunds as appropriate for your service.

Refund Destination

Refunds are sent back to the source account of the original payment. It is not possible to refund a payment to another card or bank account. If the original card expired or was canceled, the bank will attempt to credit the customer’s new card with the refund. If this attempt fails, or the customer does not have a new card, the refund will have to be made using another channel (eg bank transfer or cheque).

Testing GOV.UK Pay

You will receive a sandbox account for testing in addition to your live credentials.

When testing, you’ll need to ensure:

  • you’ve tested with mock card numbers (see below) to simulate both successful and unsuccessful transactions - never use real card numbers for testing purposes, as this breaks PCI rules
  • you test with your sandbox account, not your live account
  • REST calls succeed with 200 API codes
  • you’ve tested the user journey from your service to the payments platform using end-to-end/smoke tests

Integration testing

To check your integration with GOV.UK Pay is working as expected, you’ll need to run a series of tests.

We recommend that you build tests to include both the GOV.UK Pay API and its front end user journey. We are constantly iterating our interface, so you shouldn’t rely on any specific page layout, but you can build tests that address form elements (such as buttons) using their IDs. Alternatively, you can build stubs that will emulate GOV.UK Pay functionality.

Our APIs will evolve over time. We will always let you know in advance if we intend to make any breaking, or backwards-incompatible API changes so you can ensure your service works with the new version. Please see our section on versioning for more information.

There is guidance in the GOV.UK Service Manual on smoke testing. At the Government Digital Service, we tend to use Cucumber for testing (regardless of the core code language), as you can easily describe the behaviour you expect at the appropriate level.

If you experience any problems when testing, please email us at govuk-pay-support@digital.cabinet-office.gov.uk.

Mock card numbers for testing purposes

When you’re testing your integration, you must not use real card numbers. Use the below test numbers.

When you’re using these card numbers, you can enter any valid value for the other details (name, expiry date, card security code etc). For example, it doesn’t matter what expiry date you enter, but it must be in the future.

Testing action Card numbers to use Card type Debit/Credit
Simulate a successful transaction 4444333322221111 Visa Credit
4242424242424242 Visa Credit
4000056655665556 Visa Debit
5105105105105100 Mastercard Debit
5200828282828210 Mastercard Debit
371449635398431 American Express Credit
3566002020360505 JCB Credit
6011000990139424 Discover Credit
36148900647913 Diners Club Credit
Simulate card type not accepted 6759649826438453 Maestro Debit
Simulate a declined card 4000000000000002 Visa N/A
Simulate an invalid CVC security code 4000000000000127 Visa N/A
Simulate an expired card 4000000000000069 Visa N/A
Simulate a general processing error 4000000000000119 Visa N/A

For Worldpay accounts

Please refer to Worldpay test card numbers

For Barclays ePDQ accounts

Please go to ePDQ Get Started and click on What credit cards can I use for testing?

Performance testing

If you’d like to carry out any kind of performance testing, including in a rate-limiting environment, please contact us at govuk-pay-support@digital.cabinet-office.gov.uk.

Switching to live

Once you have finished testing with your sandbox account, here are the steps you will need to take to switch over from testing to live.

Set up GOV.UK Pay account

Request a live account

Request a live account by emailing GOV.UK Pay at govuk-pay-support@digital.cabinet-office.gov.uk. Once you have a live account, it will appear in the “My Services” section and be clearly labelled as a “Live” account, e.g. “worldpay live”, “smartpay live” or “ePDQ live”.

Complete merchant details

Payment card schemes require the details of the merchant taking payment to be shown on payment pages where the user enters card details. This information is displayed in the payment page footer. Note that:

  • the merchant must be the entity that has a contract with the PSP
  • merchant details are not specific to test or live accounts, meaning that if you complete the details for your test account then they will be transferred to your live account automatically

To complete your merchant details:

  1. Go to the GOV.UK Pay admin site.
  2. Sign in to your GOV.UK Pay account.
  3. Go to Settings > Merchant Details.
  4. Complete the Merchant name and Merchant address fields on this page.
  5. Click Save to see the following message: “Merchant Details updated”.

Set up live account credentials

To set up your live account credentials:

  1. Go to the GOV.UK Pay admin site.
  2. Sign in to your GOV.UK Pay account.
  3. Go to My Services and click on the live service you want to set up.
  4. Go to Settings > Account Credentials > Edit credentials.
  5. Complete the fields on this page; these will vary depending on which live service you use.

ePDQ

Complete the fields on this page: - PSP ID - enter your PSP ID for ePDQ - Username - enter the API user’s username - Password - enter the API user’s password - SHA-IN passphrase - this passphrase is created on the Data and origin verification page - SHA-OUT passphrase - this passphrase is created on the All transaction submission modes page - click Save credentials to go back to the Account Credentials page

Worldpay

  • Merchant ID - enter your merchant ID for Worldpay
  • Username - enter the XML username
  • Password - enter the XML password
  • click Save credentials to go back to the Account Credentials page

Generate API Key

Refer to the documentation for instructions on how to generate an API key for use with your live code.

GOV.UK currently supports Worldpay and Barclays ePDQ live gateways. Setup instructions are explained in the Worldpay and ePDQ sections.

The API endpoint for live is now the same as for testing: https://publicapi.payments.service.gov.uk/

Worldpay setup

You must change some settings in your Worldpay account to get it ready for live use.

  1. Log in to Worldpay and in your Worldpay profile, set Capture delay to “Off”.

    Pay worldpay autocaptureoff
  2. Still in Worldpay, go to Profile > Merchant Channel and set the endpoint for HTTP notifications from Worldpay to GOV.UK Pay to https://notifications.payments.service.gov.uk/v1/api/notifications/worldpay

    Use the same URL for Test and Live channels within Worldpay. The completed settings should look like this:

    Worldpay settings1

Worldpay setup for 3D Secure

If you want to use 3D Secure authentication for your payments, ask your Worldpay account manager to configure your merchant code (you cannot do this yourself by logging in to Worldpay). Ask them to enable 3D Secure for all payments. Once this is done, you can sign in to the GOV.UK Pay self-service admin site and turn on 3D Secure.

ePDQ setup

To set up ePDQ to work with GOV.UK Pay, you must log into the ePDQ admin site and:

  1. Add payment methods to your account.
  2. Set up account security parameters.
  3. Set up notification settings.
  4. Set up an API user.

Add payment methods to your account

Epq 2

  1. Log into the ePDQ admin site. On the homepage, go to Configuration > Payment methods and select Choose new payment methods

  2. Click Add next to the relevant payment method.

  3. On the Contract data tab:

    • Specify whether you have signed a contract for distance selling with an acquiring bank
    • Complete the Affiliation number (UID/Merch ID/VP number) field
    • Click Submit
  4. Go to the PM Activation tab:

    • Select Yes for Activation
    • Click Submit
  5. Add all relevant payment methods to your account.

Set up account security parameters

Set up hashing method

Epq 3

Go to Configuration > Technical information

If you cannot access this page, ask an admin user to grant you access to it; they can do this at Configuration > Users

  1. On the Technical Information page, click the Global security parameters tab.
  2. For the Hash algorithm, choose SHA-512.
  3. For the Character encoding, choose UTF-8 and click Save.

Set up checks for e-Commerce & Alias Gateway

Epq 4

  1. On the Technical information page, click the Data and origin verification tab.
  2. Scroll to the Checks for e-Commerce & Alias Gateway section.
  3. Leave the URL of the merchant page containing the payment form that will call the page: orderstandard.asp field blank.
  4. Enter a strong SHA-IN passphrase (plain text, not a hash); this will be used when setting up the GOV.UK Pay account credentials.
  5. Scroll down to the Checks for Barclaycard Direct Link section.
  6. Leave the IP address blank.
  7. Enter the same SHA-IN passphrase as the Checks for e-Commerce & Alias Gateway section and click Save.

Strong is defined as a passphrase with at least 16 characters, containing at least 4 different characters, at least one letter (a-z) and at least one number (0-9) or symbol (&, @, #, !, etc.). The following symbols cannot be used: ^, {, }, [, ], “, ‘, |, <, >

Set up notification settings

Set up Direct HTTP server to server requests

Epq 5

  1. On the Technical information page, click Transaction feedback.
  2. Scroll to the e-Commerce → Direct HTTP server-to-server request section.
  3. Leave Timing of the request on the default No request setting.
  4. Leave the following two fields blank:
    • If the payment’s status is “accepted”, “on hold” or “uncertain”
    • If the payment’s status is “cancelled by the client” or “too many rejections by the acquirer”
  5. Set the Request method to POST.
  6. Scroll to the e-Commerce → Dynamic e-Commerce parameters section.
  7. Check if PAYIDSUB is included in the Selected box:
    • If it is not included, find it in the Available box and click “>” to add it to the Selected box.

Set up security for request parameters

Epq 6

  1. Scroll to the All transaction submission modes > Security for request parameters section.
  2. Enter a strong SHA-OUT passphrase (plain text, not a hash); this will be used when setting up the GOV.UK Pay account credentials.
  3. Leave the Basic Authentication Credentials blank.
  4. Set Timing of the request to For each offline status change (payment, cancellation, etc.)
  5. Enter https://notifications.payments.service.gov.uk/v1/api/notifications/epdq into the URL on which the merchant wishes to receive a deferred HTTP request, should the status of a transaction change offline field.
  6. Click Save.

Set up an API user

To set up an API user:

  1. Activate your account
  2. Add a user manager
  3. Create an API user

Activate your account

Account activation is completed during ePDQ account creation.

Add a user manager

Epq 7

  1. Go to Configuration → Account.
  2. On the Your options tab, under the Available options sub-tab, you will see a list of IDs with Activate buttons. Activate one of the User Manager options.

  3. Click accept on the General Conditions screen.

  4. Log out by clicking the Logout option in the top right hand corner of the screen, and then log back in again.

  5. You can now go to Configuration => Users to create an API user.

Create an API user

Epq 8

  1. On the Users page, click New User.
  2. Complete the UserID and User’s name fields.
  3. Complete the email address field with the email of the person who should receive notifications about this account.
  4. Select Admin in the Profile field.
  5. Check the Special user for API (no access to admin.) option.
  6. Enter your own password.
  7. Click Create.
  8. You will then create a password for the API user:
    • Enter your own password.
    • Enter a password for the API user.
    • Confirm the password for the API user.
    • Click Submit.
  9. You will see a message that your password has been successfully updated. Click Back to List.

You have now successfully set up your ePDQ account to work with GOV.UK Pay.

Emergency contact details

Your service manager should have been given details of emergency contact methods to reach our support team in case of an urgent problem (for example, if you suspect that fraudulent transactions are being made on your account).

Before you enter live, you should make sure that the right people on your team know how to report an emergency.

Integrating with existing reporting systems

If you’re a beta partner, the GOV.UK Pay team will hold technical workshops with you to discuss how to integrate the reporting from GOV.UK Pay with your own financial systems.

Troubleshooting

This section explains how to troubleshoot common problems.

Code P0920 errors

Problem: Some calls you make to the API receive a 400 Bad Request response, with this error in the response body:

{
  "code": "P0920",
  "description": "Request blocked by security rules. Please consult API documentation for more information."
}

Fix: This response means that your API call was blocked by our firewalls. Check that the API call you sent was correctly formed.

Possible reasons why your call may be rejected include:

  • sending a POST call with an empty body where content in the body is expected
  • the use of invalid characters such as <, >, |, " or backslashes
  • the return_url you provide is not https://
  • there are URLs inside the reference or description you provide

The code examples in the documentation don’t work

Problem: The “Example Request” code snippets in the API documentation always cause the request to fail with a “401 unauthorized” error.

Fix: Remember that you must send the API key with “Bearer ” in front of it (not including the quotation marks.) This is not made clear in the code examples due to a technical limitation.

If the code example includes a line like this:

request["authorization"] = 'YOUR API KEY HERE'

remember that you must actually use “Bearer ” as the value.

Architecture

Card payment process

Card+payment+process

Partner architecture

Partner architecture v2

Versioning

The current version of the GOV.UK Pay API is 1.0.

When we add new properties to the JSON responses, the Pay API version number will not change. You should develop your service to ignore properties it does not understand.

New, dated versions of the public API will be released if JSON values are removed in a backwards incompatible manner. All these versions of the Pay API will be documented in our Revision History table below.

Our version number will be updated in the URL when there is a release. All releases will be marked with full version numbers.

Updating to the latest Pay API

We’ll send you an email to let you know about any new versions of our API.

If you want to update to our latest API, make sure you test your code before committing to the change.

We’ll support each version of the early beta Pay API for at least 1 month after we issue an upgrade notice. As the API matures, we may increase this support period to 3 or 6 months.

Soon, we hope to let you check which version of our API you’re currently running by checking your dashboard.

Revision history

Version Date Author Comments
1.0

Security

Reporting vulnerabilities

If you believe GOV.UK Pay security has been breached, contact us immediately at govuk-pay-support@digital.cabinet-office.gov.uk. If you are a live user and the suspected breach is severe, consider using the urgent contact details provided to your service manager.

Please don’t disclose the suspected breach publically until it has been fixed.

Securing your developer keys

The GOV.UK Pay platform will let you create as many API keys as you want.

We suggest letting all your developers experiment with their own test keys in the Sandbox environment, but keys for real integrations should only be shared with the minimum number of people necessary. This is because these keys can be used to create and manipulate payments. Do not commit these keys to public source code repositories.

Revoke your key immediately using the self-service site if you believe it has been accidentally shared or compromised.

If you believe your key has been used to make fraudulent payments, contact the GOV.UK support team using the urgent contact methods provided to your service manager.

To further secure your live developer keys:

  • don’t embed your developer keys in any of your code - this only increases the risk that they will be discovered (instead store your keys inside your configuration files)
  • don’t store your API keys in your application source tree (even when you’re not making your source code publically available)
  • revoke your developer keys when they’re no longer required (this limits the number of entry points into your account)
  • have a leavers’ process, so that a developer’s API key is revoked when they leave

Securing your integration with GOV.UK Pay

Make sure you’ve fully tested your integration with GOV.UK Pay. When doing so, take care not to use any real card numbers. Read our testing section for more details.

Securing user information

GOV.UK Pay doesn’t store full card numbers or CVV data for security reasons. This means you won’t be able to search for transactions using card numbers. You’ll only be able to look up certain transactions using the:

  • payment ID
  • reference metadata put into the system when creating the payment ID

Payment Card Industry (PCI) compliance

Anyone involved with the processing, transmission, or storage of cardholder data must comply with the Payment Card Industry Data Security Standards (PCI DSS) [external link]. GOV.UK Pay is certified as fully compliant as a Level 1 Service Provider with PCI DSS version 3.2.

All GOV.UK Pay partners must validate their PCI DSS compliance annually. A typical approach is to break down reporting by Merchant ID (MID) and independently report your PCI DSS status for each MID to your acquiring bank. This approach must be agreed with your acquiring bank, but is usually accepted. A MID is normally allocated by your acquiring bank for each separate payment channel you have in place, so it is important that you use unique MIDs, as agreed with your acquiring bank.

Your requirements depend on the number of transactions that you process as a merchant per scheme (Visa, MasterCard) per year. For example, if you process 4 million transactions with Visa and 3 million with MasterCard, the “Fewer than 6 million transactions per year” category still applies despite the fact that the total number of transactions is larger than 6 million. Your merchant level should be confirmed with your acquiring bank.

Process fewer than 6 million transactions per year

If you process fewer than 6 million transactions per scheme per year, you can self-assess by completing the PCI DSS Self-Assessment Questionnaire (SAQ); this is a self-assessment tool to assess security for cardholder data.

When using the GOV.UK Pay service you should be able to complete the SAQ A questionnaire which can be found in the PCI documents library [external link]; see the criteria in the table below:

SAQ A eligibility criteria Notes
Your merchant accepts only card-not-present (e-commerce or mail/telephone-order) transactions. This applies where your MID is exclusive to transactions processed via GOV.UK Pay.
All processing of cardholder data is entirely outsourced to PCI DSS validated third-party service providers. GOV.UK Pay is PCI DSS certified.
Your company does not electronically store, process, or transmit any cardholder data on your systems or premises, but relies entirely on a third party(s) to handle all these functions. This applies where your MID is exclusive to transactions processed via GOV.UK Pay.
Your company has confirmed that all third party(s) handling storage, processing, and/or transmission of cardholder data are PCI DSS compliant. GOV.UK Pay is PCI DSS compliant.
Any cardholder data your company retains is on paper (for example, printed reports or receipts), and these documents are not received electronically. You may need to dispose of any earlier receipts containing cardholder data.
Chargebacks received from your bank may fall into this category.
All elements of the payment page(s) delivered to the consumer’s browser originate only and directly from a PCI DSS validated third-party service provider(s). The payment page will be delivered to the end user directly from a PCI DSS validated service provider, GOV.UK Pay.

Process more than 6 million transactions per year

If you process more than 6 million transactions per scheme per year, you will need to undertake a formal on-site security assessment by a PCI DSS Qualified Security Assessor (QSA). It may be possible to be assessed against only the SAQ A requirements but this should be discussed with your own PCI DSS compliance team and your acquiring bank. More information on this can be found at the PCI Security Standards Council website [external link].

Your service manager may also be asked to supply extra evidence on your internal security protocols, and you may have to undertake security awareness training to ensure you are qualified to handle credit card data.

HTTPS

GOV.UK Pay follows government HTTPS security guidelines. The Hypertext Transfer Protocol Secure (HTTPS), which involves the Transport Layer Security (TLS) protocol is used by the platform to authenticate servers / clients and to provide secure connections.

Your government service will only be able to integrate with the GOV.UK Pay if it also uses HTTPS.

Contribute

GOV.UK Pay’s main application code is public and freely available under an MIT Licence and the GOV.UK Pay team codes in the open in our GitHub account.

We are experimenting with taking in Open Source contributions from our live partner services and we hope to widen this further after learning more about integrating outside contributions into our workflow.

If you’d like to speak to us about writing a developer library for GOV.UK Pay, we’d love to hear from you: please email us

Key Open Source components

Component Description Use
pay-adminusers GOV.UK Pay identity and service management component. Used by pay-selfservice to allow users to authenticate and configure GOV.UK Pay.
pay-cardid GOV.UK Pay card type identification Service. Used by pay-frontend to validate card details and autocomplete card brand.
pay-connector GOV.UK Pay payments connector. Used by other services to configure payment gateways and handle transactions.
pay-frontend GOV.UK Pay frontend payments application. Used to collect payment details from our users.
pay-publicapi GOV.UK Pay public API endpoint. Used by partner services to manage payments, generate reporting and configure their accounts.
pay-publicauth GOV.UK Pay API authentication service. Used by pay-publicapi to validate API tokens and by pay-selfservice to manage API tokens.
pay-selfservice GOV.UK Pay self service application. Used by authenticated users of our partner services to administer their accounts.

Support, contact and more information

Support hours and service

In hours:

  • On site support: Mon-Fri 9.30am-5.30pm
  • Full support of GOV.UK Pay for all ticket priorities
  • 2 dedicated support people, with additional cover from the whole team as required

Out of hours:

  • On call support: Mon-Fri 5.30pm-9.30am Sat-Sun 24x7
  • P1 priority only
  • 2 dedicated on call support people, with escalation as necessary

Asking for support

You can ask for support via email. The severity of the incident affects who you should ask for support:

  • For all non-P1 support queries, get in touch by emailing govuk-pay-support@digital.cabinet-office.gov.uk. This will raise a support ticket.

  • In emergencies, Service teams can raise a P1 incident by emailing us. This will raise a high priority ticket and could alert the team in the middle of the night, so please only use it for P1 incidents. Please do not share this address with people outside your team.

Incident severity is defined below:

Classification AKA Example Initial response time Update Time
P1 Critical Incident complete outage; substantial degradation of service; significant security issue; significant availability issue 30 minutes (at any time) 1hr
P2 Major Incident elevated error rate; mostly up; noticeably degraded service; upstream vulnerabilities; complete component failure 60 minutes (in waking hours) 2hrs
P3 Significant Users experiencing intermittent or degraded service due to platform issue 1 business day or next working day 2 business days
P4 Minor Component failure that is not immediately service impacting 2 business days weekly

Please always raise support tickets using the email addresses supplied above rather than relying on a personal email address. This ensures your issue will be dealt with as soon as possible.

Support requests are raised both automatically and manually. Our automated monitoring and system alerts feed into our helpdesk ticketing system.

Communication

The Pay support team will contact you via two methods:

  1. If you have raised a support request, we will communicate with you individually using our Deskpro ticketing system via govuk-pay-support@digital.cabinet-office.gov.uk. This will ensure that you are not relying on a single individual for comms.

  2. We will provide general incident updates to all GOV.UK Pay users through an email mailing list. All users of GOV.UK Pay will be subscribed to this list. You can choose to unsubscribe, but should ensure that anyone who needs to know about incident or maintenance alerts is subscribed. If you would like someone subscribed to this list please email govuk-pay-support@digital.cabinet-office.gov.uk.

Who deals with support issues

At all times, we have a dedicated Support Lead and Secondary (rotated weekly) who draw on additional support as required from other members of the team.

Additionally, a manager will act as the Support escalation route.

For an incident, an Incident Lead and an Incident Comms person will be assigned.

How do we respond

In general, our priority is to ensure high availability of the service.

However, in the event of a critical P1 incident we may need to isolate the issue and take GOV.UK Pay offline in order to minimise any security breach until we can investigate fully.

For general or non urgent support queries our service levels are:

First reply service level First resolution service level
80% within two working days 80% within 5 working days

Resolution and Closure

For all incidents:

  • Resolution occurs when the Incident Lead, in consultation with the initiator, confirms that the matter reported is no longer impacting the service.
  • Any follow up work will be tracked as part of business as usual.
  • An incident post mortem will be held for all P1 incidents, and for any others where one is needed. The outputs will be made available to our beta partners.

Feedback on support matters

If we are not responding to your requests for support in the way that you would expect or your problem is not addressed in this documentation, please email us, including any error messages you’re getting.

Newsletter and blogs

GOV.UK Pay publishes a newsletter every few weeks. This will help you stay updated with any new features we release.

We’ll also blog about our progress using the Government as a Platform blog or the GDS blog.

Posts we’ve published are:

Press coverage

More coverage of the platform can be found in press reports. Published articles include:

Case Studies

We’re looking forward to producing these. Please bear with us.

If you are a beta partner and think your service could to be featured in our case study section, please contact us.

Glossary of terms

This section defines commonly used terms in GOV.UK Pay.

Term Definition
Service admin site the site where your staff users can sign in to view transaction history and settings for your integration with GOV.UK Pay
Payment pages the pages on GOV.UK Pay which users follow to make a payment
End user a user who is paying through GOV.UK Pay
Staff user a user from a team delivering a government service which uses GOV.UK Pay to process payments; if you’re reading this, someone like you
Platform administrator this is a member of the GOV.UK Pay team responsible for controlling access to the platform, ensuring effective support is provided to partner services, and improving the platform on the basis of user feedback
Platform developer a member of the GOV.UK dev team

Platform accounts

Account type Account definition
Staff account an account for a staff user that grants appropriate access rights and permissions to administer payments for their service through GOV.UK Pay. Initially, all staff accounts will have the same permissions. But in future they will be distinguished by different permissions relating to the different user groups outlined: Service Admin, Accountant, Refund Manager, Developer
Service account an account for a partner service with GOV.UK Pay. It is this account that staff users will be accessing. The Service Account will associate all relevant information and preferences with a particular service (e.g. transaction history, selected providers, accepted payment methods, etc).
Provider account an account that a partner service has with a payment provider for payment processing. Each service may have separate provider accounts with multiple providers