Table of contents

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.

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

You can also use the interactive API explorer [external link] to try API calls and view responses.

See the Quick start guide section to read how to set up the API explorer. Make sure you enter your test API key to avoid generating real payments.

Authentication

GOV.UK Pay authenticates API calls with OAuth2 HTTP bearer tokens [external link]. 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-HERE>

Payment status lifecycle

The following diagram gives an overview of the payment status lifecycle and the possible outcomes, excluding for delayed capture payments:

Payment states

You can check the status of a payment using the Find payment by ID API call [external link].

A successful response includes status and finished values:

status Meaning finished
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 selected Confirm. Or, user has selected Confirm and the payment is a delayed capture. false
success User successfully completed the payment. true
failed User attempted to make a payment but the payment did not complete. 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. Please contact us. true
 

HTTP status codes

The 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. Please contact us.
 

API error codes

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 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. Please contact us, quoting the error code.
Create payment P0199 Account error There is a problem with your service account. Please 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. Please 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. Please 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. Please 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. Please contact us, quoting the error code.
Cancel payment P0598 Downstream system error Internal error with GOV.UK Pay. Please 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. Please 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. Please 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. Please contact us, quoting the error code.
General P0900 Too many requests Your service account is sending requests above the allowed rate. Please try the request again in a few seconds.
General P0920 Request blocked by security rules Our firewall blocked your request. See the “Troubleshooting” section for details.
General P0999 GOV.UK Pay is unavailable The GOV.UK Pay service is temporarily down.
 

The general format of JSON error response bodies is:

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

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

Some errors may contain additional fields , such as field.

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 the 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 user 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. Please contact us, quoting the error code.
 

You can see which payments have status-related error codes using the GOV.UK Pay admin tool or directly using the API.

Use the admin tool

  1. Sign in to the GOV.UK Pay admin site (link opens in new window).
  2. Select Transactions.
  3. Select a payment with a "failed", "cancelled" or "error" status.

Use the API

You can use the API to examine the state object in a payment’s API response.

For example:

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

Card types

 
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
 

Rate limits

POST requests to the GOV.UK Pay API are rate-limited to 15 requests per second, for each government service.

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.

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