Table of contents

Direct Debit

Before reading this section, you should be familiar with making payments. You should also have integrated your service with the GOV.UK Pay API.

Synchronous and asynchronous payment methods

Card payments are a synchronous payment method. When a user completes a card payment using GOV.UK Pay, the platform immediately confirms to your service whether the payment has succeeded or failed. If a user pays by card, you can immediately provide the purchased service to the user.

Direct Debit payments are an asynchronous payment method. When a user completes a Direct Debit payment process using GOV.UK Pay, the platform makes a request to the user’s bank to set up a Direct Debit mandate and transfer the funds. It takes 3 to 4 working days to confirm the success of the payment.

Get started

To use the Direct Debit feature, you must request a GOV.UK Pay Direct Debit test account from our support team.

Contact us if you want to add Direct Debit to an existing integration.

Set up an account with the Direct Debit supplier

  1. Sign in to the GOV.UK Pay admin tool.

  2. Select your account in the My services page and follow the on-screen instructions.

Set the payment method

When you create an API key, you link your GOV.UK Pay account with the payment method you want to use. For example “testing” or “Worldpay”.

You can use different API keys to direct paying users to different payment methods.

To use Direct Debit, select the corresponding payment method.

GOV.UK Pay agreements

In order to support Direct Debit, GOV.UK Pay uses ‘agreements’. An agreement represents an individual payer’s consent for future payments using a particular funding source. For example, a personal bank account.

For Direct Debit transactions, GOV.UK Pay fulfils an agreement by registering a Direct Debit mandate with the payer’s bank.

Agreement lifecycle


State Description
CREATED Your service made an API call to create the agreement.
STARTED Payer has visited the next_url and landed on the GOV.UK Pay page to enter their account details.
PENDING Indicates that account details have been submitted to the payment service provider (PSP), but the PSP is not yet able to confirm whether the mandate has been successfully set up.

The agreement then reaches 1 of 5 different finished states.

Possible agreement finished states


Finished state Description
SUCCESS Mandate successfully set up.
FAILED User attempted to make a payment but the mandate was not set up successfully.
CANCELLED The user has cancelled their mandate.
CANCELLED - USER NOT ELIGIBLE The user indicated that they are not the sole signatory on the bank account, so the mandate setup could not be completed.
ERROR Something went wrong with GOV.UK Pay or the underlying Payment Service Provider.

Possible agreement state transitions

An agreement changes states as it moves through its lifecycle.


Original state New state Meaning
CREATED STARTED Payer has visited the `next_url` and landed on the GOV.UK Pay page to enter their account details.
STARTED PENDING Payer has provided their account details, and confirms their consent to the agreement. PENDING is only used with delayed payment types such as Direct Debit. This indicates that payer consent has been given but the agreement has not yet been confirmed with the issuing bank.
STARTED CANCELLED - USER NOT ELIGIBLE Payer has indicated that they are not the sole signatory for their bank account, and has selected the link to go back and try a different payment method.
PENDING ACTIVE The issuing bank has confirmed that funding source (for example, Direct Debit mandate) is valid.
PENDING FAILED The issuing bank has rejected the funding source. Possible reasons: incorrect bank account details, bank account requires multiple signatories to set up a Direct Debit.
PENDING CANCELLED Cancelled by the payer.
ACTIVE CANCELLED Cancelled by the payer.

One-off payments using Direct Debit

To take a single payment using Direct Debit, you must set up a Direct Debit mandate.

  1. Create an API key linked to your Direct Debit service.

  2. Follow the instructions in the “Payment flow” section of this documentation.

The same API call is used for single payments in all contexts, including Direct Debit:

POST /v1/payments

You cannot take further payments from users using this method without creating a new payment. This requires users to re-enter their account details.

Variable payments using Direct Debit

You can collect payments of variable amounts at any time by using a variable agreement. For example you may want to collect:

  • money each time a service is provided

  • payments where the amounts vary according to service usage

  • regular payments where you do not know in advance how much each payment will be

You could also use this functionality to simulate a recurring or scheduled Direct Debit payment, by sending an API call on a set schedule. Users would be emailed each time a payment is collected against their mandate.

Variable Direct Debit payment process

These steps happen in order.

1. GOV.UK Pay creates the agreement

API call: POST /v1/agreements/

Your service must specify:

  • a return_url where GOV.UK Pay will direct the user when they have finished setting up the agreement

  • the agreement_type (on demand)

  • a reference (optional) - your reference for this agreement

The response contains a next_url.

2. Your service directs the user to the next_url

3. The user provides their account details

For example, account number and sort code for Direct Debit.

GOV.UK Pay makes an API call to our Direct Debit supplier to verify account details.

4. GOV.UK Pay presents the user with a confirmation screen

The screen presents the user’s account details. The user grants their consent by selecting Confirm. GOV.UK Pay sends an email to the user to confirm that their mandate has been set up. If the mandate subsequently fails, the GOV.UK Pay team will send an email to update the user that their mandate could not be set up.

5. GOV.UK Pay securely passes the user’s details on to the Direct Debit provider

The Direct Debit provider submits a request to BACS to set up a mandate, and sends a mandate ID to GOV.UK Pay. At this point, services can send a payment request.

6. GOV.UK Pay returns the user to your service using the return_url

7. Call the API to check the status of the agreement

API call: GET /v1/agreements/<AGREEMENT-ID>

This is to display an appropriate screen to the user. For a Direct Debit payment, this will initially be in a ‘pending’ state until the bank confirms the mandate. You can confirm this state by signing into the GOV.UK Pay admin tool. The mandate confirmation process takes 2 working days.

8. The GOV.UK Pay admin tool updates the transaction status

When GOV.UK Pay receives confirmation that the mandate is confirmed, the GOV.UK Pay admin tool will show an updated transaction status.

Collecting payments against a mandate

API call: POST /v1/payments

Required arguments:

{
 "amount"
 "description"
 "reference"
 "agreement_id"
 }

Once a mandate has been set up and a mandate ID is available, you can make an API call to collect a payment against the mandate.

You do not need to wait until the mandate is confirmed to send a collection request to GOV.UK Pay.

When collecting a payment against a mandate, you must supply a Reference number and description.

If a mandate does not exist prior to a payment request, it takes 4 working days to collect a payment.

If a mandate has already been set up, it takes 3 working days to collect a payment each time a subsequent one is requested. It then takes a further 2 working days before the payment reaches the service’s bank account.

GOV.UK Pay will send an email to the user giving them 3 working days’ advance notification that payment will be collected against their mandate. The email will contain the mandate reference number.

You can collect at any time interval. You may collect between £1 and £5000 each time.

Direct Debit payment statuses

These apply to both one-off and variable Direct Debit payments.


State Description
CREATED Your service made an API call to create the agreement.
STARTED Your service sent an API request to GOV.UK Pay.
PENDING Indicates that account details have been submitted to the payment service provider (PSP), but the PSP is not yet able to confirm whether the payment is complete.

The payment reaches one of several finished states.


Finished state Description
SUCCESS Payment succeeded.
FAILED Payment failed.
CANCELLED The service cancelled the payment.
ERROR Something went wrong with GOV.UK Pay or the underlying Payment Service Provider.

Differences compared to card payment statuses

The states created, started and submitted are all represented as a single state: STARTED.

Direct Debit payments can have the non-terminal state PENDING.

Reference numbers

You can control what appears on paying users’ bank account statements. You’ll enter this when you set up your account with the Direct Debit supplier. This applies to both one-off and variable Direct Debit payments.

The Direct Debit supplier will generate a mandate reference number, which is given to the user in the confirmation email. The first part of the reference will be generated from the account name you enter with the Direct Debit supplier. This is limited to 12 characters.

When you create a mandate for a variable Direct Debit, you can also create your own reference. You may want to do this so you can link an existing case record with the Direct Debit transaction. References that your service supplies with mandates will not be shown to the user, but will be available on the GOV.UK Pay admin tool and through the GOV.UK Pay API.

Users will only receive the mandate reference number generated by the Direct Debit supplier. It’s a mandatory requirement of the Direct Debit scheme that paying users receive their mandate reference number.

Refunds

Contact us if you need to issue refunds for any kind of Direct Debit payment.

Indemnity claims

Contact us if you need to handle indemnity claims for any kind of Direct Debit payment.