Skip to main content

API reference

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

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

The API is based on REST principles. It returns data in JSON format, and uses standard HTTP error response codes.

You can get started with the API quickly. Make sure you enter an API key from a test account to avoid generating real payments.

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

OpenAPI file

For more detailed information on each API action, you can look at our OpenAPI file.

You can also generate a client library from our OpenAPI file using Swagger Editor. This may be an easier way for you to integrate your service with GOV.UK Pay than writing a client library from scratch.

Allowing traffic to our API

If you’re connecting to the GOV.UK Pay API from a secure network, we recommend using a web proxy like Squid to allow traffic to our base URL.

Do not add an allow list of IP addresses to your firewall, because GOV.UK Pay’s IP addresses will change regularly. Read more about why GOV.UK does not support allow lists of IP addresses.

Authentication

GOV.UK Pay authenticates API calls with OAuth2 HTTP bearer tokens. These are easy to use and contain only your API key.

When you make an API call, you need to use an “Authorization” HTTP header to provide your API key, with a “Bearer” prefix. For example:

Authorization: Bearer {YOUR_API_KEY}

Payment status lifecycle

You can get information about a payment using the API and see the payment’s state in the API response.

For example:

{
  "amount": 2000,
  "state": {
      "status": "failed",
      "finished": true,
      "message": "Payment expired",
      "code": "P0020"
  }
  ...
}

You can also use the GOV.UK Pay admin tool.

  1. Sign in to the GOV.UK Pay admin tool.
  2. Select an account.
  3. Select Transactions.
  4. Use the Payment status dropdown to find payments with error statuses. For example, “Declined”.

 code

If something went wrong, code is an API error code.

 message

If something went wrong, message is a description of what went wrong.

status and finished

status Meaning finished
created Payment created using the API. Your user has not yet visited next_url. false
started Your user has visited next_url and is entering payment details. false
submitted Your user has submitted payment details, and gone through authentication if required.
The PSP has authorised the payment, but the user has not yet selected Confirm.
false
capturable The payment is a delayed capture, and your user has submitted payment details and selected Confirm. false
success Your user successfully completed the payment by selecting Confirm.
The user is redirected to an appropriate payment confirmation page.
true
failed Your user attempted to make a payment but the payment did not complete.
GOV.UK Pay shows an appropriate screen for the failure.
Check the payment status error code for more information.
true
cancelled Your service cancelled the payment using an API call or the GOV.UK Pay admin tool. true
error Something went wrong with GOV.UK Pay or the underlying payment service provider. Payment fails safely with no money taken.

The user will see a screen stating “We’re experiencing technical problems. No money has been taken from your account. Cancel and go back to try the payment again.”
true

Error codes

HTTP status codes

GOV.UK Pay uses standard HTTP response code conventions:

  • 100 codes are informational
  • 200 codes indicate success
  • 300 codes indicate a redirection
  • 400 codes indicate a client-side error
  • 500 codes indicate a server-side error

Common status codes are:

Common status 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, eg missing details in the request or a failed payment cancellation.
401 Required authentication has failed or has not been provided.
404 The resource you have requested cannot be found.
412 Precondition failed, eg mismatch in expected refund amount available.
422 Unprocessable entity obtained on a request validation.
429 Too many requests. Request rate is above the rate limit.
Any 500 error Something is wrong with GOV.UK Pay. Contact us.

API error codes

Example error response:

{
  "field": "amount",
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000"
}

These error descriptions are intended for developers, not your users.

Errors caused by an API call

 
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 P0196 MOTO payments not allowed Contact us about setting up your service for Mail Order / Telephone Order (MOTO) payments.
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 P0502 Payment cannot be cancelled You can only cancel a payment if the payment has a cancel field.
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 matched 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. Find out how to fix a P0920 error.
General P0940 PSP account error Your payment service provider account is not fully configured. Use GOV.UK Pay documentation to configure your PSP or contact support.
General P0999 GOV.UK Pay is unavailable The GOV.UK Pay service is temporarily down.
Delayed capture P1000 No match for paymentId No payment matched the paymentId you provided.
Delayed capture P1001 Capturing failed Capturing the payment failed. Contact us, quoting the error code.
Delayed capture P1003 Payment cannot be captured You can only capture a payment if the payment has a status of capturable.
Delayed capture P1098 GOV.UK Pay error Something is wrong with GOV.UK Pay. Contact us, quoting the error code.
 

Fix a P0920 API error

If you receive a P0920 API error code, our firewall blocked your request.

To fix a P0920 API error, make sure your API request:

  • has a Content-Type: application/json header
  • uses application/json in the Accept header if you’re using an Accept header
  • uses https in the return_url, not http
  • does not use invalid characters like <, >, |, " or \
  • does not have an empty request body if you’re making a POST request

Errors caused by payment statuses

Error code Meaning Cause
P0010 Payment method rejected Payment rejected due to payment method selected, or payment information entered. For example, failed fraud check, a 3D Secure authentication failure, or your user has insufficient funds in account.
P0020 Payment expired Payment was not confirmed and completed within 90 minutes of being created. If the payment was already authorised, GOV.UK Pay will send a cancellation to the payment provider.
P0030 Payment cancelled by your user Your user selected Cancel payment during the payment journey. If the payment was already authorised, GOV.UK Pay will send a cancellation to the payment provider.
P0040 Payment was cancelled by your service Your service cancelled the payment.
P0050 Payment provider returned an error Multiple possible causes, for example a configuration problem with the payment provider, or incorrect credentials. Contact us, quoting the error code.

Rate limits

Per second, you can make:

GET requests are also rate-limited, but at a very high level. In the future, we will publish an official rate limit for GET requests.

If you exceed the rate limit, this will return HTTP status code “429” (Too many requests) and error code P0900. After a second, you’ll be able to retry your attempt in a reasonable way. For example, using exponential backoff.

Contact us if you would like to discuss rate limiting applied to your service account, or give us feedback.