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 your 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 your user to the
next_urlprovided 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 completing payment
identify your 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 your 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 your 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 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
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 staff check 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.
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 your 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 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 card details page.
Existing integrations with GOV.UK Pay
The Ministry of Justice has a citizen-facing public site for sending money to prisoners.