API reference

GOV.UK Pay is a payment platform for government. If you work in the public sector, read more about using GOV.UK Pay to take payments.

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

We use the same base URL for test and live accounts. You can create a test account from the GOV.UK Pay homepage and use it to test our API and your integration with it. You receive your live account when you make your service live for your users.

The API key you use determines which GOV.UK Pay service you use, and whether actions are treated as test payments, or processed as real payments. You can create test and live API keys through the GOV.UK Pay admin tool.

Warning If you’re testing our API, make sure you enter an API key from a test account to avoid creating real payments.

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

You can get started with the GOV.UK Pay API quickly.

This page has information about:

Endpoints

Payments

Endpoint	URL	Data consistency
Create a payment	`POST /v1/payments`	Strongly consistent
Get information about a single payment	`GET /v1/payments/{PAYMENT_ID}`	Strongly consistent
Get a payment’s events	`GET /v1/payments/{PAYMENT_ID}/events`	Strongly consistent
Cancel a payment	`POST /v1/payments/{PAYMENT_ID}/cancel`	Strongly consistent
Take (‘capture’) a delayed payment	`POST /v1/payments/{PAYMENT_ID}/capture`	Strongly consistent
Search payments	`GET /v1/payments`	Eventually consistent

Refunds

Endpoint	URL	Data consistency
Refund a payment	`POST /v1/payments/{PAYMENT_ID}/refunds`	Strongly consistent
Get the status of a refund	`GET /v1/payments/{PAYMENT_ID}/refunds/{REFUND_ID}`	Strongly consistent
Get information about a payment’s refunds	`GET /v1/payments/{PAYMENT_ID}/refunds`	Eventually consistent
Search refunds	`GET /v1/refunds`	Eventually consistent

Agreements for recurring payments

Endpoint	URL	Data consistency
Create an agreement for recurring payments	`POST /v1/agreements`	Strongly consistent
Search agreements for recurring payments	`GET /v1/agreements`	Eventually consistent
Get information about a single agreement for recurring payments	`GET /v1/agreements/{AGREEMENT_ID}`	Strongly consistent
Cancel an agreement for recurring payments	`POST /v1/agreements/{AGREEMENT_ID}/cancel`	Strongly consistent

Disputes

Endpoint	URL	Data consistency
Search disputes	`GET /v1/disputes`	Strongly consistent

Authorising payments

Endpoint	URL	Data consistency
Send card details to authorise a MOTO payment	`POST /v1/auth`	Strongly consistent

Data consistency

GOV.UK Pay API endpoints have different levels of data consistency. Endpoints are either:

eventually consistent or
strongly consistent

Data from eventually consistent endpoints is updated on a delay. You should not rely on eventually consistent endpoints for operations that require real-time data accuracy, such as checking the outcome of a payment at the end of a user journey.

Data from strongly consistent endpoints is updated immediately. If you perform a read operation on a strongly consistent endpoint immediately after a write operation, the data accurately reflects the outcome of the write operation. For example, if you check the status of a payment (GET /v1/payments/{PAYMENT_ID}) immediately after a user completes the payment, the data will show that the payment is complete.

Allowing traffic to our API

If you’re connecting to our 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 requests with OAuth2 HTTP bearer tokens.

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

Authorization: Bearer {YOUR_API_KEY}

Rate limits

Per second, you can make:

up to 15 POST requests to create a payment
up to 15 POSTrequests to capture a delayed payment
up to 15 other POST requests

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 a 429 HTTP status code (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.

Pagination

Responses from search endpoints, such as search payments or search refunds, are split into pages. By default, these endpoints display 500 results per page and return the first page of results.

You can use query parameters to view different pages and control the number of results on each page.

Query parameter	Description
`page`	Returns a specific page of results. Defaults to `1`.
`display_size`	The number of results returned per results page. Defaults to `500`. Maximum value is `500`.

Pagination example

There are 74 payments in the created state. In this example search request, these 74 payments are split into 4 pages of results because display_size is 20. This request returns payments 41-60 because page is 3:

GET /v1/payments?state=created&display_size=20&page=3

Pagination links

Search endpoints also return a _links object, which includes href and method fields you can use to move between pages. Use the fields in:

self to run the same search again
first_page to get the first page of results
last_page to get the last page
prev_page to get the previous page
next_page to get the next page

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. You cannot use Swagger Editor to make test API requests.

Responses

The GOV.UK Pay API uses HTTP status codes to show the outcome of a request. 4xx and 5xx status codes give more detail in the code and description attributes of the response.

HTTP status codes

HTTP status code	Description
200 - OK	Your request was successful.
201 - Created	You created a payment.
202 - Accepted	Refund request accepted. The refund will reach the paying user soon.
204 - No content	Your request was successful.
400 - Bad request	Your request is invalid. Check the `code` and `description` response attributes to find out why the request failed.
401 - Unauthorised	Your API key is missing or invalid. Read more about authenticating GOV.UK Pay API requests.
404 - Not found	The payment, refund, or agreement you tried to access does not exist. Check the ID you sent in your request.
409 - Conflict	The payment you tried to access has already been captured or cancelled, or you sent an `Idempotency-Key` that has already been used.
412 - Precondition failed	The `refund_amount_available` value you sent does not match the amount available to refund. Read more about refunding payments.
422 - Unprocessable entity	One of the values you sent is formatted incorrectly. This could be an invalid value, or a value that exceeds a character limit. Check the `code`, `description`, and the `field` or `header` attributes in the response for more information.
429 - Too many requests	You’ve made too many requests using your API key. Read more about rate limits.
Any 500 error - Internal server error	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.

GOV.UK Pay API error codes

If your request fails, you’ll also receive a response that contains code, description, and field attributes to help you find out why the request failed.

For example:

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

Error code	Endpoint(s)	Meaning
P0101	Create a payment Send card details to authorise a MOTO payment	The request you sent is missing a required parameter. Check the `field` attribute in the response to see which parameter is missing.
P0102	Create a payment Send card details to authorise a MOTO payment	A header or parameter value you sent in your request is invalid. Check the `description` attribute in the response to find out which value is invalid.
P0104	Create a payment	You included `return_url` and `"authorisation_mode": "moto_api"` in your request. These parameters cannot be used together. Remove the `return_url` parameter to create a Mail Order / Telephone Order (MOTO) payment that accepts card details sent through the API. Remove the `authorisation_mode` parameter to create a standard payment.
P0191	Create a payment	The `Idempotency-Key` you sent in the request header has already been used to create a payment.
P0195	Create a payment	You tried to create a Mail Order / Telephone Order (MOTO) payment that accepts card details sent through the API but this feature is not turned on for your service. You can read more about setting up your service to accept card details sent through the API. To create a standard payment, remove `"authorisation_mode": "moto_api"` from your request.
P0196	Create a payment	You tried to create a type of payment that is not turned on for your service. Contact us about setting up your service for MOTO payments or recurring payments.
P0197	Create a payment	The JSON you sent in the request body is invalid. Check the formatting of the request body.
P0198	Create a payment	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0199	Create a payment	There’s a problem with your service account. Contact us with your error code and we’ll investigate.
P0200	Get information about a single payment	No payment matched the `{PAYMENT_ID}` you provided. Check the `{PAYMENT_ID}` parameter you sent.
P0298	Get information about a single payment	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0300	Get a payment’s events	No payment matched the `{PAYMENT_ID}` you provided. Check the `{PAYMENT_ID}` parameter you sent.
P0398	Get a payment’s events	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0401	Search payments	The value of a parameter you sent is invalid. Check the parameters listed in the `description` response attribute.
P0402	Search payments	The requested page of search results does not exist.
P0498	Search payments	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0500	Cancel a payment	No payment matched the `{PAYMENT_ID}` you provided. Check the `{PAYMENT_ID}` parameter you sent.
P0501	Cancel a payment	Cancelling the payment failed. This could be because this payment does not have a `cancel` attribute and so cannot be cancelled. Read our guidance on checking if you can cancel a payment. If you think you should be able to cancel a payment but you’re still receiving this error, contact us.
P0502	Cancel a payment	This payment cannot be cancelled. You can only cancel a payment if it has a `cancel` attribute when you check if you can cancel it. There’s further guidance on checking if you can cancel a payment.
P0598	Cancel a payment	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0600	Refund a payment	No payment matched the `{PAYMENT_ID}` you provided. Check the `{PAYMENT_ID}` parameter you sent.
P0601	Refund a payment	Your request is missing a required attribute. You must submit `amount` and `refund_amount_available` values in the body of your request.
P0602	Refund a payment	The value of an attribute you sent is invalid. Check the `amount` and `refund_amount_available` values you sent.
P0603	Refund a payment	This payment cannot be refunded. You can read more about checking if you can refund a payment.
P0604	Refund a payment	The `refund_amount_available` value you sent does not match the amount available to refund. `refund_amount_available` must match the `amount_available` value you receive when checking if you can refund a payment. Read more about checking if you can refund a payment.
P0697	Refund a payment	The JSON you sent in the request body is invalid. Check the formatting of the request body.
P0698	Refund a payment	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0700	Check the status of a refund	Either no refund matched the `{REFUND_ID}` you sent, or no payment matched the `{PAYMENT_ID}` you sent. Check the `{REFUND_ID}` and `{PAYMENT_ID}` parameters you sent.
P0798	Check the status of a refund	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0800	Get information about a payment’s refunds	No payment matched the `{PAYMENT_ID}` you sent. Check the `{PAYMENT_ID}` parameter you sent.
P0898	Get information about a payment’s refunds	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P0900	All endpoints	You’ve made too many requests too quickly using your API key. You can read more about rate limits.
P0920	All endpoints	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
P0940	All endpoints	Your payment service provider (PSP) account is not fully configured. You can read our Go live documentation to configure your PSP account.
P0941	Multiple endpoints	GOV.UK Pay has turned off payment and refund creation on this account. This error can have multiple causes. Contact us with your error code.
P0942	Multiple endpoints	Recurring card payments are currently turned off for this service. Contact us with your error code.
P0999	All endpoints	GOV.UK Pay is temporarily down. Check our status page for more information.
P1000	Capture a delayed payment	No payment matched the `{PAYMENT_ID}` you provided. Check the `{PAYMENT_ID}` parameter you sent.
P1001	Capture a delayed payment	GOV.UK Pay could not capture this payment. Contact us with your error code.
P1003	Capture a delayed payment	GOV.UK Pay could not capture this payment. The `status` of the payment must be `capturable`. To check this, run `GET /v1/payments/{PAYMENT_ID}`.
P1098	Capture a delayed payment	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P1101	Search refunds	The value of a parameter you sent is invalid. Check the parameters listed in the `description` response attribute.
P1100	Search refunds	The requested page of search results does not exist.
P1211	Send card details to authorise a MOTO payment	No payment matches the `one_time_token` you sent. Check the `one_time_token` parameter you sent.
P1212	Send card details to authorise a MOTO payment	The `one_time_token` you sent has already been used. You can only use a `one_time_token` once. Create a new payment to get a new `one_time_token`. Read more about creating and authorising MOTO payments by sending card details through the API.
P2101	Create an agreement for recurring payments	The request you sent is missing a required parameter. Check the `field` attribute in the response to see which parameter is missing.
P2102	Create an agreement for recurring payments	The value of a parameter you sent is invalid. Check the response to see which value in invalid.
P2197	Create an agreement for recurring payments	The JSON you sent in the request body is invalid. Check the formatting of the request body.
P2198	Create an agreement for recurring payments	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P2200	Get information about a single agreement for recurring payments	No agreement matched the `{AGREEMENT_ID}` you sent. Check your `{AGREEMENT_ID}` parameter.
P2298	Get information about a single agreement for recurring payments	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P2401	Search agreements for recurring payments	The value of a parameter you sent is invalid. Check the parameters listed in the `description` response attribute.
P2402	Search agreements for recurring payments	The requested page of search results does not exist.
P2498	Search agreements for recurring payments	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.
P2500	Cancel an agreement for recurring payments	No agreement matched the `{AGREEMENT_ID}` you sent. Check your `{AGREEMENT_ID}` parameter.
P2501	Cancel an agreement for recurring payments	This agreement cannot be cancelled. You can only cancel agreements in the `active` status. You can read more about the agreement status lifecycle or the API reference for getting information about an agreement.
P2598	Cancel an agreement for recurring payments	There’s something wrong with GOV.UK Pay. If there are no problems on our status page, you can contact us with your error code and we’ll investigate.

Errors caused by payment statuses

Failed payments return a code value in the state object when you use the API to get information about that payment. These error codes explain why the payment failed.

Error code	Meaning	Cause
P0010	Payment method rejected	The payment was rejected due to the payment method selected or the payment information entered by the user. For example, the user may have failed a fraud check, a 3D Secure authentication check, or they may not have sufficient funds in their account.
P0020	Payment expired	The payment timed out because the paying user did not confirm and complete the payment within 90 minutes of the payment being created. If the paying user’s bank already authorised the payment, GOV.UK Pay will automatically send a cancellation to the payment service provider.
P0030	Payment cancelled by your user	The paying user selected Cancel payment during the payment journey. If the paying user’s bank already authorised the payment, GOV.UK Pay will automatically send a cancellation to the payment service provider.
P0040	Payment was cancelled by your service	Your service cancelled the payment. You can read more about cancelling payments.
P0050	Payment provider returned an error	This error has multiple possible causes. For example, a configuration problem with the payment service provider, or incorrect credentials. Contact us with your error code and we’ll investigate.

Payment status lifecycle

You can get information about a payment using the API and see where the payment is in the payment status lifecycle. You can see this in the state object in the response.

For example:

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

Payment status meanings

The status value indicates where the payment is in the payment status lifecycle.

finished indicates whether the payment journey is finished. A finished payment journey does not always mean the user has made a payment. For example, a user may submit their payment details but their bank rejects the payment - the payment journey is finished but no payment has actually been made.

`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 their payment details.	`false`
`submitted`	Your user submitted payment details and went through authentication, if it was required. The payment service provider 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 their payment details and selected Confirm. You can read more about how to capture this payment.	`false`
`success`	Your user successfully completed the payment by selecting Confirm. We redirected your user to a payment confirmation page.	`true`
`failed`	The payment failed. This failure could be because the payment timed out after 90 minutes, the user’s payment method was rejected, or your user cancelled the payment. We showed the user a failure screen. Check the payment status error codes for the possible reasons for a `failed` payment.	`true`
`cancelled`	Your service cancelled the payment using an API request or the GOV.UK Pay admin tool. You can read more about how to cancel payments.	`true`
`error`	Something went wrong with GOV.UK Pay or the payment service provider. The payment failed safely with no money taken from the user. We showed the paying user 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`

If something went wrong with a payment, the code and message attributes in the API response can help you find out what happened.

code is an API error code.

message is a description of what went wrong.

API versioning

We work hard to make our API updates backwards compatible and avoid breaking changes.

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.