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:
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_urlprovided 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
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
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.
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:
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
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:
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.
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.
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:
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.
Existing integrations with GOV.UK Pay
The Ministry of Justice has a citizen-facing public site for sending money to prisoners.