Table of contents

Quick start guide

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

  • initiate and complete payments
  • issue refunds
  • view the event history for individual payments
  • view transactions within a specified time period

    This section explains how 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 sandbox account login details you received.

  2. Click on the API key section, then click Generate a new key.

Pay 9

Enter a description for your API key.

Describeapikey+image2

Your API key will be shown on the screen for you to copy.

Newkeygenerate+image+3

You must store your API keys away securely. Make sure you never share this key in publicly accessible documents or repositories, or with people who should not be using the GOV.UK Pay API directly. [Read our security section](/security/#security) for more information on how to keep your API key safe.

API Explorer setup

The quickest way to learn about the API is to use the API Explorer (link opens in new window) with the API key that you just created.

  1. Go to the API Explorer (link opens in new window), sign in, and click the “Add API Key” button.

    Pay add api key

  2. In the resulting pop-up, enter the following values:
    • For API Key, enter “[YOUR-API-KEY]” (do not include the quotation marks), replacing [YOUR-API-KEY] with the actual value of your sandbox API key. You do not need to put the “Bearer: ” prefix which is required when calling the API from code; the API Explorer adds that automatically.
    • For Label, enter “Authorization” (do not include the quotation marks).

Make sure you are using an API key from your sandbox account on the admin site, not the live account.

Making a test API call

You will now make a test API call to GOV.UK Pay by creating a new payment. This is the call your service will make when initiating a payment using GOV.UK Pay.

  1. To test the API Explorer, select General from the API Explorer Resource dropdown menu. Select Create new payment (link opens in new window) from the API Explorer Action dropdown menu. Click on the Body tab lower 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"
}

As well as details of the payment, you’ll notice that you need to send a return_url when creating a payment. The reason for this is that users go to GOV.UK Pay hosted pages to actually make their payment. 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

  1. Click 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. Note that the JSON includes a next_url link. This URL is where your service should redirect the user for them to make their payment.

    Pay api explorer response

Follow end user payment journey

  1. Go to the next_url with your browser. You’ll see the payment screen. Refer to the Testing GOV.UK Pay section to find a mock credit card number that you can enter to simulate a payment in the sandbox environment. For the rest of the details, enter some test information, bearing in mind that:

    • the expiry date must be in the future and in the format MM/YYYY
    • the postcode must be valid
  2. Submit the payment.

View transaction at GOV.UK Pay Admin site

  1. Go to the service admin site and select Transactions.

Transaction+list+image+4

Self-service payments

You may want to use self-service payment links rather than integrate with the GOV.UK Pay API if your service:

  • is non-digital and uses paper applications to process payments
  • is non-digital and has low transaction volumes
  • asks users for payment by sending email or letters
  • does not have a development team that can integrate your service with GOV.UK Pay

Prerequisites

Before you set up a self-service payment link, you must have a live service. You do not need an API key or to use the API explorer.

  1. Sign in to your GOV.UK Pay account.
  2. Select Create a payment link in the Dashboard.
  3. Select Create a payment link.

On the Set payment link information page:

  1. Complete the Title field.
  2. Complete the optional Details field if necessary, and select Continue.
  3. You must change your payment link if it is identical to an existing link.

Specify payment reference

  1. Select either Yes, create a unique payment reference number for my users or No, I would like to use my own.
  2. If you selected No, I would like to use my own, complete the Name of your payment reference number and optional Hint text fields if necessary.
  3. Select Continue.

Specify whether payment is fixed or variable

  1. Select Yes or No, the user can choose the amount for the payment amount
  2. If you selected Yes, enter the payment amount.
  3. Select Continue.
  1. Review your payment link details.
  2. Select Create link.

You can now send the live payment link to your users.

Reference number and confirmation

Your users will receive a reference number and confirmation email when they use a self-service payment link. You can find the reference number on the Transactions page. You will not receive a transaction reference number by default, unless you tell your users to send them to you.

GOV.UK Pay creates and hosts the self-service payment confirmation page.