Skip to main content
Table of contents

Quick start guide


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:

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. This does not apply if you only use payment links.

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. The platform API allows you to:

  • begin and complete payments
  • view the event history for individual payments
  • view transactions and refunds within a specified time period
  • issue full or partial refunds

You’ll be able to generate API keys for 2 different accounts. These are your:

When you’ve received a test account, follow these instructions to get started with our API and make a test API call.

Test the API

Generate a test API key

  1. Sign in to the GOV.UK Pay admin tool with the test account login details you received.

  2. Select API keys, then generate a new key.

Make sure you keep your API keys safe.


Warning Do not use an API key from a live account on the GOV.UK Pay admin tool. Only use a test API key.

Make a test API call

You can make test API calls to GOV.UK Pay with your test API key.

You can use API testing tools such as Postman or Insomnia REST to make test API calls.

This section shows an example API call and request body, to make 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 that use test accounts can optionally use HTTP, rather than HTTPS, for return URLs.

If the test call 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 making 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 in the test environment. 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

  • a valid postcode

Submit the payment.

View transactions at GOV.UK Pay admin tool

Sign in to the GOV.UK Pay admin tool and select Transactions.