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
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 they complete their 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.
If you search payments using the API at the end of each day, you should run the search at least one hour after your
to_date. This is because the API may not return up-to-date information about payment events from the last hour.
To help you reconcile payments, you can:
- add custom metadata to payments
- contact us to change what appears on your bank statement - if you use Stripe
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.
When you’ll receive payments
You’ll receive the money in your bank account within 2 working days of your user completing their payment.
It will take 3 working days if your user completed their payment at the weekend or on a bank holiday.
Your payment service provider (PSP) will only transfer money to you when the total of your users’ payments is above your PSP’s ‘minimum payout’. For example, if you use GOV.UK Pay’s PSP, the minimum payout is £1.
If your PSP is Worldpay, SmartPay or ePDQ, ask your PSP if you need to know your exact minimum payout or payment times.
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
return_url. For example, do not use
/payment_12345 at the end of your
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.