Skip to main content

Quick start

Warning You must store your API keys securely. You must not share this key in publicly accessible documents or repositories. You must not share it with anyone who should not be using the GOV.UK Pay API directly.

Read this section to learn about what to do to get started with GOV.UK Pay.

Before you start

Before you start using GOV.UK Pay, you should:

Decide how you want to take payments

There are 2 ways you can take payments with GOV.UK Pay:

  • integrate with the GOV.UK Pay API
  • set up a payment link

Integrate with the API

If you want to build a technical integration between your service and the GOV.UK Pay API, your service team should have the necessary skills.

You can refer to the GOV.UK Service Manual for more information.

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

Read our documentation on integrating with the API for more information. Read our API reference for an index of everything the GOV.UK API can do.

Payment links are individual pages for taking online payments.

To set up a payment link, create an account or sign in to the admin tool.

The GOV.UK Pay API

The GOV.UK Pay API is based on REST principles with endpoints returning data in JSON format, and standard HTTP error response codes. Our API lets you:

  • begin and complete payments
  • view the event history for individual payments
  • view transactions, refunds, and disputes within a specified time period
  • issue full or partial refunds
  • create agreements to take recurring payments

You can create 2 types of API keys for your GOV.UK Pay service. These are:

If your payment service provider (PSP) is Stripe, you can test how transaction fees and payments to your bank account work.

When you’ve signed up for GOV.UK Pay and created a service, follow these instructions to get started with our API and make a test API request.

Test the API

Create a test API key

  1. Sign in to the GOV.UK Pay admin tool.

  2. Select the service you want to test from My services.

  3. Select Settings.

  4. Select Developers, then API keys.

  5. Select Create a new API key.

Make sure you keep your API keys safe.

Warning Only use test API keys in sandbox or ‘not live yet’ modes. Do not use a live API key in these modes. It will not work properly.

Make a test API request

You can make test API requests to GOV.UK Pay, using your test API key for authentication.

You can use API testing tools such as Bruno to make test API requests.

This is an example API request and request body to create a new payment for a passport application:

POST /v1/payments

{
"amount": 12000,
"reference": "12345",
"description": "New passport application",
"return_url": "https://service-name.gov.uk/transactions/12345"
}

Services testing in sandbox or ‘not live yet’ modes can optionally use HTTP, rather than HTTPS, for return URLs.

If the test request is successful, you will receive a 201 Created response with a JSON body.

The JSON includes a next_url link. This URL is where your service should redirect your user for them to make their payment.

Read more about taking payments.

Simulate your users’ payment journey

Go to the next_url with a browser, and you’ll see the payment screen. Choose a mock card number and enter it to simulate a payment. For the other required details, enter some test information which should have:

  • an expiry date that is in the future and in the format MM/YYYY or MM/YY

  • a valid postcode

Submit the payment.

View transactions at GOV.UK Pay admin tool

Select an account in the GOV.UK Pay admin tool, then select Transactions.

You can also view test transactions using the API.