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 within a specified time period
  • issue full or partial refunds

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

Generate API Key for API Explorer

  1. Sign in to the GOV.UK Pay admin site 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.

API Explorer setup

The quickest way to get started with the API is to use the API Explorer [external link] with your API key.

  1. Sign in to the API Explorer and select Add API Key.

    Pay add api key

  2. In the pop-up, enter the following values:
  • For API Key, enter your test API key. You do not need to add the "Bearer:" prefix, because the API Explorer adds that automatically.
  • For Label, enter Authorization.


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

Make a test API call

This section describes how to make a test API call to GOV.UK Pay, by creating a new payment. This is the same call your service will make when beginning a payment using GOV.UK Pay.

  1. Sign in to the API Explorer [external link]
  2. Under Resource, select General. Under Action, select Create new payment [external link]. Select the Body tab down to see an example JSON body that you would send when creating a payment.
{
"amount": 12000,
"reference": "12345",
"description": "New passport application",
"return_url": "https://service-name.gov.uk/transactions/12345"
}

You also need to send a return_url when you create a payment. This is because users go to pages hosted by GOV.UK Pay to actually make payments. The return_url is the URL of a page on your service that the user will be redirected to after they have completed their payment (or payment has failed).

Pay api explorer createpay

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.

  1. Select the green Send Request button.

  2. If the API Explorer is set up correctly, you will receive a 201 Created response with a JSON body, confirming that the payment was created:

Pay api explorer response

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

Simulate an end-user 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 site

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

Transaction+list+image+4

Enter search criteria to find transactions using the available filters.