Table of contents

Direct Debit

You can use Direct Debit if you want to take recurring payments.

You can take payments whenever you need to. You can take the same amount or a different amount each time.

You cannot automatically schedule payments. If you need to take regular payments, you could create your own scheduler to send API calls on a set schedule.

Before you start

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

Set up an account with our 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.

You must contact us before you switch to live, so we can send you your GoCardless contract to sign.

Set up a mandate

Before you can take payments, your user needs to set up a Direct Debit mandate (also known as an ‘instruction’) by entering their bank account details on a GOV.UK Pay page.

A mandate is your user’s agreement that you can take payments from their bank account.

These steps happen in order.

1. GOV.UK Pay creates the mandate

API call: POST /v1/directdebit/mandates

You must include the following required parameters in your API call:

  • reference
  • return_url

You can include the optional description parameter in your API call.

reference (required)

reference is a reference number you want to associate with this mandate.

The reference number does not need to be unique, and can be any data type as long as it does not:

  • be longer than 255 characters
  • contain URLs

return_url (required)

return_url is an HTTPS URL on your site. GOV.UK Pay will direct your user to this URL when GOV.UK Pay have finished setting up the mandate.

The URL should not be JSON-encoded, because backslashes are invalid characters in the API.

description (optional)

description is a human-readable description of the mandate.

The description must be no longer than 255 characters, and must not contain URLs.

2. Direct the user to GOV.UK Pay

When the API responds, you need to:

  • direct the user to the next_url from the API response
  • store the mandate_id from the API response, so you can use that ID to collect payments against the mandate later

3. The user provides their bank account details

When your service redirects the user to next_url, the user will see a Set up a Direct Debit page. The user enters their bank account details and selects Continue.

GOV.UK Pay checks with GoCardless that the user’s account number and sort code match a real bank account.

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 is being set up.

5. GOV.UK Pay securely passes the user’s details on to GoCardless

GoCardless submits a request to BACS to set up a mandate, and sends a mandate ID to GOV.UK Pay. At this point, you can send a payment request.

If the mandate then fails, the GOV.UK Pay team will send an email to update the user that their mandate could not be set up.

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

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

API call: GET /v1/directdebit/mandates/<mandateid>

The API response includes a state object. This includes the following parameters:

You should use these status and details parameters to display an appropriate final page to your user.

The status will be pending until the user’s bank confirms the mandate. The mandate confirmation process takes 2 working days.

You can also check the status of a mandate by signing into your GoCardless account through the GOV.UK Pay admin tool.

Collecting payments against a mandate

API call: POST /v1/directdebit/payments

Required arguments:

{
   "amount"
   "reference"
   "mandate_id"
}

Optional argument:

{
   "description"
}

Once a mandate has a status of pending, you can make an API call to collect a payment against the mandate.

GoCardless will take the payment from your user’s bank account in:

  • 3 working days if the mandate’s status is pending
  • 2 working days if the mandate’s status is active

It then takes a further one working day before the payment reaches your service’s bank account.

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

You can collect payments whenever you need to. You may collect between £1 and £5000 each time. Contact us if you need to collect more than £5000 at any one time.

Getting information about a payment

The call to check the status of a payment with the GOV.UK Pay API is:

GET /v1/directdebit/payments/<paymentid>

If the payment exists, the API response will include a state object. This includes the following parameters:

You can also check the status of a payment by signing into your GoCardless account through the GOV.UK Pay admin tool.

Generating a list of mandates or payments

You can use the API to search mandates or payments and return a list of results.

Searching mandates

The call to search mandates with the GOV.UK Pay API is:

GET /v1/directdebit/mandates?<queryparameters>

For example:

GET /v1/directdebit/mandates?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z&reference=12345&status=pending

The query parameters you can use to search are:

  • reference
  • status
  • bank_statement_reference
  • email
  • name

All the parameters are case insensitive. You can search for partial values of reference, email and name.

If you search for a specific mandate, all criteria you use must match. Otherwise your search will not return that mandate in the results.

If your request has no query parameters, the API will return all mandates.

Searching payments

The call to search payments with the GOV.UK Pay API is:

GET /v1/directdebit/payments?<queryparameters>

For example:

GET /v1/directdebit/payments?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z&reference=12345&status=success

The query parameters you can use to search are:

  • reference
  • status
  • mandate_id

All the parameters are case insensitive. You can search for partial values of reference.

If you search for a specific payment, all criteria you use must match. Otherwise your search will not return that payment in the results.

If your request has no query parameters, the API will return all payments.

Filtering by date

You can use the following query parameters to filter mandates or payments by date:

  • from_date, which is the start date to search, inclusive

  • to_date, which is the end date to search, exclusive

Dates must be in ISO 8601 format. For example 2015-08-13T12:35:00Z.

Splitting results into pages

You can use the following query parameters to split results into pages:

  • display-size, which has a default of 500, and must be between 1 and 500
  • page, which has a default of 1

These must be a positive integer.

For example, you run the following search and get 1500 mandates in the response:

GET /v1/directdebit/mandates?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z

You could then get a single page of these mandates by running:

GET /v1/directdebit/mandates?from_date=2018-10-01T13:30:00Z&to_date=2018-10-14T15:00:00Z&display-size=500&page=2

This would return payments 501 to 1000.

Mandate statuses

State Description
created Your service made an API call to create the mandate.
started Your user has visited the next_url and landed on the GOV.UK Pay page to enter their account information.
abandoned GOV.UK Pay did not set up the mandate, because your user cancelled or took longer than 90 minutes to finish entering their account information.
failed GoCardless could not set up the mandate, for example because your user’s bank account does not support Direct Debit.
pending GOV.UK Pay has sent your user’s account information to GoCardless, but GoCardless has not yet confirmed if the mandate has been successfully set up.
active GoCardless has confirmed that the mandate was successfully set up.
cancelled The mandate was cancelled, for example because your user asked their bank to cancel the mandate.
inactive You can no longer collect payments because the mandate expired. A mandate usually expires if you do not collect payments against it for 13 months.
error There was an internal error. Contact us for help.

Payment statuses

State Description
pending You’ve requested the payment.
success GoCardless has taken the payment from your user’s bank account.
paidout GoCardless has sent the money to your bank account.
cancelled The payment was cancelled, for example because your user asked their bank to cancel the mandate.
failed The payment failed, for example because your user did not have enough money in their bank account.
indemnityclaim Your user’s bank refunded the payment because your user claimed they did not authorise it.
error There was an internal error. Contact us for help.

Reference numbers

You can control what appears on paying users’ bank account statements. You’ll enter this when you set up your account with GoCardless.

GoCardless 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.

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

If a user asks you for a refund, you can process the refund by signing into your GoCardless account through the GOV.UK Pay admin tool.

If the payment’s status is indemnityclaim, you do not need to do anything because your user’s bank will have refunded the payment. If you disagree with the refund, read about how to dispute the claim on the GoCardless website.