Skip to main content

Take a payment

This section tells you how to take a payment using the GOV.UK Pay API.

When your user makes a payment, your service should supply a reference. If possible, this should be a unique identifier for the payment. If your organisation already has an existing identifier for payments, you can use it as this reference.

Your service will also need to supply a return_url. This is a URL that your service hosts for your user to return to, after their payment journey on GOV.UK Pay ends.

Creating a payment

The call to create a payment with the GOV.UK Pay API is:

POST /v1/payments

For example:

{
  "amount": 14500,
  "reference" : "12345",
  "description": "Pay your council tax",
  "return_url": "https://your.service.gov.uk/completed",
  "delayed_capture": false,
  "metadata": {
    "ledger_code": "AB100",
    "an_internal_reference_number": 200
  },
  "email": "sherlock.holmes@example.com",
  "prefilled_cardholder_details": {
    "cardholder_name": "Sherlock Holmes",
    "billing_address": {
        "line1": "221 Baker Street",
        "line2": "Flat b",
        "postcode": "NW1 6XE",
        "city": "London",
        "country": "GB"
    }
  },
  "language": "en",
  ...
}

API call parameters

amount

amount is the amount in pence. In the example, the payment is for £145.

The amount must be a number data type rather than a string.

The minimum amount is one pence plus your payment service provider’s (PSP’s) transaction fee. To see your PSP’s transaction fee, check your contract by either:

The maximum amount is either:

  • 10,000,000 pence (£100,000)
  • 500,000 pence (£5,000) if you use Government Banking

Your PSP may set a lower maximum amount. Check with your PSP if you cannot make payments up to the maximum amount.

If you need to take payments above the maximum amount, either:

 delayed_capture

You can use this field to delay taking a payment.

description

description is a human-readable description of the payment. This is shown to your user on the payment pages and to your staff on the GOV.UK Pay admin tool.

The description must be no longer than 255 characters, and must not contain URLs.

email and prefilled_cardholder_details

You can use the email and prefilled_cardholder_details parameters to prefill some of the fields on the Enter card details page.

 language

You can use the language field to use Welsh on your payment pages.

metadata

You can use the metadata parameter to add custom metadata.

reference

reference is the reference number you wish to associate with this payment.

The reference number does not need to be unique, and must not:

  • be longer than 255 characters
  • contain URLs

The format is variable. If you have an existing format, you can keep using it if your values are no longer than 255 characters.

return_url

This is a URL that your service hosts for your user to return to, after their payment journey on GOV.UK Pay ends.

You must use HTTPS for your return_url, but you can use HTTP with test accounts.

The URL must be no longer than 2,000 characters, and must not be JSON-encoded because backslashes are invalid characters in the API.

Receiving the API response

Example response:

{
  "created_date": "2020-03-03T16:17:19.554Z",
  "state": {
    "status": "created",
    "finished": false,
  },
  "_links": {
    "self": {
      "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93",
      "method": "GET"
   },
    "next_url": {
      "href": "https://publicapi.payments.service.gov.uk/secure/bb0a272c-8eaf-468d-b3xf-ae5e000d2231",
      "method": "GET"
    },
    ...
  },
  "amount": 14500,
  "reference" : "12345",
  "description": "Pay your council tax",
  "return_url": "https://your.service.gov.uk/completed",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "payment_provider": "worldpay",
  "provider_id": "10987654321",
  ...
}

There are two URLs in the _links object – one in the self section and one in the next_url section.

The URL in self is the unique URL for the new payment. You can also find this URL in the Location response header. A GET request to this URL returns information about the new payment and its status.

The next_url is the URL the paying user will visit to make their payment. You should direct your users to this URL.

Your service needs to store the self URL or the payment_id for each new payment you create. This is so you can check on the status of these payments later.

Read more about reporting and payment flow.

Warning Do not expose the `next_url` to anyone other than your paying user. Anyone in possession of the `next_url` could hijack your user’s payment.

API response fields

The _links object includes href and method fields that you can use to make API requests related to the payment. Use the fields in:

The _links object also includes a next_url_post object, For example:

"next_url_post": {
   "type": "application/x-www-form-urlencoded",
   "params": {
       "chargeTokenId": "bb0a272c-8eaf-468d-b3xf-ae5e000d2231"
   },
   "href": "https://www.pymnt.uk/secure",
   "method": "POST"
},

You can use the href and chargeTokenId to make a POST API request to next_url, instead of a GET API request.

created_date

created_date is when you created the payment, in ISO 8601 format.

payment_provider

payment_provider is the name of your payment service provider (PSP), or sandbox if you’re using a test (‘sandbox’) account.

provider_id

provider_id is the unique ID your PSP generated for this payment.

state

Use state to see the status of the payment.

Track the progress of a payment

You can track the progress of a payment by getting information about it from the reporting API.

The status of the payment will pass through several states until it either succeeds or fails. Read more about the payment status lifecycle.

Choose the return URL and match your users to payments

For security reasons, GOV.UK Pay does not add the payment_id or outcome to your return_url as parameters.

You can match your users with payments with an encrypted cookie, or by creating a secure random ID:

You can use an encrypted cookie containing the payment ID from GOV.UK Pay. Your service should issue this when a payment is created, before sending your user to next_url. Your users will not be able to decrypt an encrypted cookie, so a malicious user could not alter the payment ID and intercept other users’ payments.

Create a secure random ID

You can create a secure random ID, such as a UUID, and include this as part of the return_url. You should use a different return_url for each payment. Malicious users will be unable to guess securely generated UUIDs.

If you use this method, you should store your IDs safely. For example, in a datastore mapped to the payment ID just after a payment is created.

Warning Make sure the way you match your returning users to payments is tamper-proof.

For example, don’t store the payment ID in an unencrypted cookie or rely on a `return_url` parameter that isn’t secret (like the payment ID or reference).

Accepting your users when they return

If your user is directed to the return_url, they could have:

  • paid successfully

  • not paid because their card was rejected or they selected cancel

  • not paid because your service (via the API) cancelled the payment in progress

  • not paid because of a technical error

Your service should use the API to check the payment status when your user reaches the return_url, and provide an appropriate response based on the final status of the payment attempt.

When your user does not complete their payment journey

Your user may close their browser or lose internet connectivity in the middle of their payment journey on GOV.UK Pay. In this event, your user will not be redirected back to your service.

You can still check the status of these payments, but you should be aware GOV.UK Pay will allow your user 90 minutes to complete their payment before it expires. You can only be certain of the payment’s status after this time.

If a payment fails, GOV.UK Pay will not allow your user to attempt the payment again with alternative card details. In this situation your user would need to return to the service to retry the payment. Your service should account for this.

Cancel a payment that’s in progress

Your user can select a link on the payment page to cancel a payment that’s in progress. Alternatively, a service can make the following API call for a given payment_id:

POST /v1/payments/{PAYMENT_ID}/cancel

Replace {PAYMENT_ID} with the ID of the payment you are cancelling.

A 204 response indicates success. Any other response indicates an error.

Check if you can cancel a payment

Use a GET request against a single payment to check if you can cancel that payment:

GET /v1/payments/{PAYMENT_ID}

Replace {PAYMENT_ID} with the ID of the payment you are checking.

If the JSON response body contains a "cancel" field (in the _links object) that’s not null, you can cancel the payment. For example:

"cancel": {
  "href": "https://publicapi.payments.service.gov.uk/v1/payments/hu20sqlact5260q2nanm0q8u93/cancel",
  "method": "POST"
}