Skip to main content

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:

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.

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

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

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.

    Read more about staying up to date with GOV.UK Pay API updates.