Table of contents

How to integrate with the GOV.UK Pay API

Before you build an integration, your service team should have the necessary skills. You can refer to the GOV.UK Service Manual for more information.

This guidance is for technical architects or developers planning to integrate their service with the GOV.UK Pay API. It describes:

  • the requirements for your service’s backend

  • what data you need to store and why

  • typical data flows for using the GOV.UK Pay API in an integration

  • when to release services to users

  • making sure that all payments are processed

  • integrating with finance and accounting systems (see also Reporting)

The following diagram shows a typical high-level architecture with a GOV.UK Pay integration:

A typical high-level GOV.UK Pay architecture

Service backend

Your service backend is server-side software. You should build this to:

  • make a call to the GOV.UK Pay API to start the payment journey

  • store information about user payment journeys in your datastore

  • redirect the user to the next_url provided by GOV.UK Pay, where the user will enter their payment information and confirm their payment

  • receive users’ requests when they are redirected back to your service via the return_url, where the user will return after completing payment

  • identify the returning user via the session

  • make a call to the GOV.UK Pay API to determine the outcome of the payment

  • display information about the outcome of the payment and next steps to the user

Datastore

You will likely need some kind of server-side datastore to record payment information for each payment journey. You should store:

  • an ID or primary key

  • the service the user requested

  • the GOV.UK Pay paymentId

  • the status of the payment

  • the date and time the payment was started

Finance and accounting systems

You may want to integrate your finance and accounting systems with GOV.UK Pay using the API.

For example, you could automatically fetch data about the outcome of payment journeys. You could import that into your finance system so payments can be reconciled against bank transaction information.

You can also add custom metadata to payments if you want to reconcile payments using your own internal reference numbers.

You could also connect a customer-relationship management (CRM) or case management system to GOV.UK Pay, so your staff can issue refunds from within your system.

You can read more in the Reporting and Refunding payments sections of this documentation.

The GOV.UK Pay API

The GOV.UK Pay API offers a set of operations to conduct and report on payments. For more information:

When to release your service to users

It’s your responsibility to decide when to release your service to users. This will depend on the nature of your service.

In some cases you may be comfortable releasing a service before a payment has been confirmed. For example, if you’re taking payments in advance because a user has an account with you.

In most cases, you’ll want to confirm that a payment has been completed before releasing the service to users. Typically you’ll do this when the user visits the return_url on your service.

The following example UML sequence diagram shows a typical happy-path payment journey:

Typical happy-path user payment sequence

Identifying the user when they return to your service

We recommend using a cookie-based session to identify the user when they return to your service. You could use either encrypted client side sessions, or server-side sessions using session store.

We recommend that you do not encode any reference number or user- specific information in the return_url.

If you do, an attacker may be able to guess the reference in your return_url and gain access to another user’s personal information displayed on your confirmation screen.

Example
Good https://my.service.gov.uk/return
Bad https://my.service.gov.uk/return/payment_12345

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

Make sure that all payments are processed

There are 2 failure cases which affect the design of your integration with GOV.UK Pay:

  • user abandons their payment journey before completing it

  • user completes their payment successfully, but their network connection is interrupted before they return to your service

In the happy-path scenario you want to release your service as quickly as possible to your user, so you would check the payment outcome when your return_url is visited.

However, in the failure cases, users will never visit the return_url. Instead, you should either:

  • make sure your service team can manually check payment outcomes in the GOV.UK Pay admin tool

  • use an automatic mop-up job (recommended)

Have your service team manually check the payment outcome

If your team manually checks payment outcomes before releasing payments to users, you may have a low-volume service. This would always be the case if you are using payment links.

You should make sure your service staff check the outcomes of payments in the GOV.UK Pay admin tool before releasing the service to the user.

A ‘mop-up job’ provides the best guarantee that the failure cases are handled properly and automatically. A mop-up job is a background process which checks the outcome of incomplete payment journeys.

In order to use a mop-up job, you need:

  • a datastore which keeps track of incomplete payment journeys

  • a server-side process which periodically checks the datastore for incomplete payment journeys, and queries the GOV.UK Pay API to determine the outcome

The following UML sequence diagram shows an example of an incomplete payment journey, and how a mop-up job would clean it up:

A mop-up job acting on an incomplete payment journey

Your mop-up job should run frequently, for example every half an hour. It should ignore payments made in the past 3 hours to avoid interfering with payments that are still being processed. If it finds ‘stale’ incomplete payment journeys then it’s likely users have abandoned those payments. The mop-up job should call the GOV.UK Pay API to determine the status of the payment.

Collecting your users’ billing addresses

You can enable or disable collecting your users’ billing addresses in your GOV.UK Pay account Settings screen.

This change can take up to 15 minutes to take effect.

If you collect a user’s billing address in your service before you redirect them to GOV.UK Pay, you can prefill the billing address field on the Enter card details page.


Warning If you disable billing address collection, your service will receive a `null` `billing_address` object in API responses. The `billing_address` object is inside the `card_details` object. You should check if disabling billing address collection will affect your service‘s integration with GOV.UK Pay.

Existing integrations with GOV.UK Pay

The Ministry of Justice has a citizen-facing public site for sending money to prisoners.