Skip to main content

Quick start

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

You can use the GOV.UK Pay API to:

  • 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

The API follows REST principles. Endpoints return JSON data and use standard HTTP status codes for errors.

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

When you’ve signed up for GOV.UK Pay and created a service, create a test API key and make a test payment request.

You can still use test API keys for a service after it goes live.

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.

Warning You must store API keys securely. You must not include them in emails, support tickets or other messages to GOV.UK Pay. You must not put them in publicly accessible documents or repositories. Share API keys only with people or organisations that need them.
Read more about securing your API keys.

Use test API keys only in sandbox or ‘not live yet’ modes. Live API keys will not work properly in these modes.

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 page. 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.