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. From the landing page, select API key, then Generate a new key.

Pay 9

Enter a description for your API key:

Describeapikey+image2

Your API key will be shown for you to copy:

Newkeygenerate+image+3

Read the Security section for more information on how to keep your API key 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. You can read more about this in the Security section.

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.

You can refer to the “Making payments” section for more detailed information.

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 from the Testing GOV.UK Pay section 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

Go to the GOV.UK Pay admin tool. From the landing page, select Transactions:

Transaction+list+image+4

Enter search criteria to find transactions using the available filters.