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 your users
making sure that all payments are processed
integrating with finance and accounting systems

Service backend

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

make a request to the GOV.UK Pay API to start the payment journey
store information about user payment journeys in your datastore
redirect your user to the next_url provided by GOV.UK Pay, where your user will enter their payment information and confirm their payment
receive your user’s request when they are redirected back to your service via the return_url, where your user will return after they complete their payment
identify your returning user via the session
make a request 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 your 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 your user requested
the GOV.UK Pay paymentId
the status of the payment
the date and time the payment was started

The GOV.UK Pay API

The GOV.UK Pay API offers a set of endpoints to help your organisation reconcile and report on payments. For more information:

read our API reference
look at our OpenAPI file

When to release your service to your users

It’s your responsibility to decide when to release your service to your 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 your users. Typically you’ll do this when your user visits the return_url on your service.

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

Identifying your user when they return to your service

We recommend using a cookie-based session to identify your 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. For example, do not use /payment_12345 at the end of your 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.

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:

your user abandons their payment journey before completing it
your 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, your user 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 your 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 team checks the outcomes of payments in the GOV.UK Pay admin tool before releasing the service to your users.

Use an automatic mop-up job (recommended)

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.

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:

Your mop-up job should run frequently, for example every half an hour. The mop-up job should ignore payments made in the past 3 hours to avoid interfering with payments that are still being processed.

If the mop-up job finds ‘stale’ incomplete payment journeys then it’s likely your users have abandoned those payments. The mop-up job should send a request to the GOV.UK Pay API to determine the status of the payment.

Collecting your users’ billing addresses

You can turn user billing address collection on or off by selecting an account in the GOV.UK Pay admin tool, then selecting Settings.

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

If you collect your users’ billing addresses in your service before you redirect them to GOV.UK Pay, you can prefill the billing address field on the Enter payment details page.

Warning If you turn off 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.