GOV.UK Pay API

This version is deprecated, we recommend you don't use it in production. View the latest docs

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 a web-based 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 platform can connect your government service to different payment service providers (PSPs). (During beta, the platform will be connected to a single PSP.)

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.

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

There are 4 departments and agencies currently partnering with the platform.

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

Before you start

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

  • a new or existing digital service that needs to take payments
  • people with the development skills to build the technical integration with GOV.UK Pay
  • your own payment service provided (PSP) contracts for gateway and merchant acquirer services (there are existing cross-government contracts offering competitive transaction costs that may be available to you - please email us at govuk-pay-support@digital.cabinet-office.gov.uk if you’d like to discuss contractual questions)
  • points of contact to communicate with the GOV.UK Pay team - this is likely to be your service’s product owner or service manager, as well as a technical lead

Make sure you’re also familiar with the government best practice 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.

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.

Account setup

If your department or agency is not yet a beta partner, please contact us at govuk-pay-support@digital.cabinet-office.gov.uk to discuss using GOV.UK Pay

If your department or agency is participating in the beta, it will have a GOV.UK Pay service account (in some cases, it may have several service accounts, one for each service that is going to integrate with Pay).

To use the GOV.UK Pay API, you will need your own individual staff account. A staff account is linked to a service account and can be used to create API keys for that service, as well as access the transaction history and service settings.

  1. Have your service manager email govuk-pay-support@digital.cabinet-office.gov.uk to get your staff account credentials. You'll receive access to a sandbox account which allows you to familiarise yourself and your developers with the platform before processing real payments. The GOV.UK Pay team will set up your service and provide you with login details for your account.

  2. Sign in to the self-service admin console with the sandbox account login details you received.

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



Enter a description for your API key.



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

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 with the API key that you just created.

  1. Go to the API Explorer and click the blue “Add API Credentials” button.



    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 self-service site, not the production account.

Making a test API call

  1. To test the API Explorer, select Create new payment 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).

  2. Click the green Send Request button.

  3. 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.

  4. 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
    • the postcode must be valid
  5. Submit the payment.

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

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 transaction:

  • succeeds
  • fails (for example because the payment details are wrong)
  • cannot be completed because of a technical error
  • was 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.

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.

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.

The user clicks Continue.

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

{ 
  "amount": 14500,
  "description": "Payment description",
  "return_url": "https://your.service.gov.uk/completed",
  "reference" : "12345"
}
  • amount: in pence; in this example, the payment is for £145
  • 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 self-service 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. It must begin with https:// and not http:// or the request will not be accepted. It should not be JSON-encoded as backslashes will not be accepted.
  • 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)

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:

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.

If the details are valid and the payment is approved, the user is then taken to a payment confirmation page, still hosted by GOV.UK Pay:

After confirming, the user is directed to the return_url you provided in the initial request.

If the payment cannot be approved, the user is shown an error page with a message describing the reason, for example:

The link to try the payment again sends the user to the return_url you provided in the initial request.

Payment flow: after payment

After the user attempts payment, GOV.UK Pay returns them to the return_url you provided in the initial request, whatever the status of the payment.

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

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, 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.

As usual, 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.

In this example, the payment was successful, and the payment journey is finished.

It is up to your page at the return_url to show an appropriate message based on the state of the payment. For example, for a completed payment, you would likely want to confirm that the payment has been received and explain what will happen next. For a failed payment, you should make clear that payment failed and offer the user a chance to try again.

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 production. 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 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.

You can check the status of a given payment using the Find payment by ID API call.

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 didn't complete the payment, due to invalid or expired payment details, fraud block, etc. 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 refund_amount_available 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.

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

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.

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.

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.

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.

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 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.

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 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).

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 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 admin console 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.

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 notifications

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

Testing GOV.UK Pay

You will receive a sandbox account for testing in addition to your production 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 production 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 Dedit
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

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 production

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

  1. Go to the self-service admin site and log in with production credentials, not your sandbox credentials. Contact us if you need production credentials.
  2. While logged in with your production credentials, generate an API key for use with your production code.
  3. Set up the Worldpay account as explained in the section below.

The API endpoint for production 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 production use.

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

  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 Production channels within Worldpay. The completed settings should look like this:

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.

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 production, 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 http://; it must be https://
  • there are URLs inside the reference or description you provide

All my payment requests suddenly get a 404 error

Problem: Payments were working, but are now failing with 404 errors instead of specific error code. How do I troubleshoot this?

Fix: Certain invalid requests can be rejected by our firewalls with a 404 rather than a specific error. We are working to provide more informative errors.

Double-check that your call to v1/payments is valid. In particular, check that the return_url you are providing is valid and starts with https://, not http://.

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

Partner architecture

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 production 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

A major benefit of integrating with GOV.UK Pay is that you’ll have immediate access to a fully secure and PCI accredited platform.

The Payment Card Industry Security Standards Council is an open global forum, launched in 2006, that develops, maintains and manages the PCI Security Standards. These cover everything from the point of entry of card data into a system, to how the data is processed, through to secure payment applications.

Compliance with PCI Security Standards is governed by the payment brands and their partners. Although the GOV.UK Pay team has completed the majority of work to ensure compliance with the PCI standard, your service may be asked by your payment provider to supply extra evidence on your internal security protocols. You will have to complete a self-assessment questionnaire called the PCI DSS SAQ that will include a series of yes or no questions about your security practises. Your service manager may also be asked to undertake security awareness training to ensure they 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 and clients/secure connections.

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

Contribute

Currently GOV.UK Pay is not open source, but we’re planning to change that very soon. At the moment, we can invite developers from other service teams to collaborate with us.

We hope to soon invite everyone to be involved in our project, allowing you all to raise pull requests on Github and contribute to our code. Please stay tuned.

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

Support, contact and more information

If your problem 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.

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

Term Definition
Admin console the site where your staff can sign in to view transaction history and settings for your integration with GOV.UK Pay, and carry out tasks like issuing refunds
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