Take recurring payments

GOV.UK Pay is still developing recurring payments so this feature is only available to a limited number of services at the moment. Contact us if you’re interested in taking recurring payments.

If you are a beta service, you can take recurring payments from a user using GOV.UK Pay. The user consents to making recurring payments, enters into an ‘agreement’ with your service, and provides their payment details. The agreement allows you to take further payments through our API without the user interacting with your service again.

Your service has additional responsibilities when taking recurring payments. You’re responsible for:

managing the relationship between your service and users
providing terms and conditions to users
authenticating users
getting and recording users’ consent for you to take recurring payments
managing payment schedules
telling users when you’re going to take or change payments
letting users amend their recurring payments

This section outlines the recurring payment flow, your responsibilities, and how to set up and use agreements to take recurring payments.

How recurring payments work

You create an ‘agreement’ between your service and your user through our API. This is an agreement for you to use your user’s payment details to make ongoing payments for your service.
You set up the agreement by getting your user’s consent and taking their first payment. You instruct our API to save their payment details. This makes the agreement for recurring payments active.
You take recurring payments by referencing the active agreement in your API requests when creating payments. The agreement allows GOV.UK Pay to authorise the payment with the user’s saved payment details.
You cancel the agreement when it is no longer needed or when the user requests a cancellation. GOV.UK Pay cannot use the cancelled agreement to authorise payments. You can set the agreement up again by taking another payment and instructing our API to save the user’s payment details.

Understand the technical flow of recurring payments

In this integration example, the service creates an agreement when a user says they want to make recurring payments, then uses that agreement to continue taking payments.

A user consents to your service taking recurring payments. You record their consent.
Your service creates an ‘agreement’ for recurring payments through the POST /v1/agreements endpoint.
GOV.UK Pay returns a 201 successful response that includes an agreement_id.
Your service saves the agreement_id from the response.
Your service sets up the agreement by creating the user’s first payment using the POST /v1/payments endpoint. This payment follows the standard GOV.UK Pay payment flow, but you must include the set_up_agreement parameter with the agreement_id as its value.
GOV.UK Pay returns a 201 successful response to your payment creation request.
Your service directs the user to GOV.UK Pay to make their first payment. The user follows the standard payment flow.
The user completes their first payment and GOV.UK Pay returns them to your service. Your PSP stores the user’s payment details.
Your service creates recurring payments using the POST /v1/payments endpoint. In your request body, you set authorisation_mode to agreement and include "agreement_id": "{AGREEMENT_ID}", replacing {AGREEMENT_ID} with the agreement you set up earlier.
GOV.UK Pay authorises the payment using the user’s payment details your PSP saved during the first payment.

Before you start taking recurring payments

You need to understand your service’s responsibilities and enable recurring payments with your payment service provider (PSP) before you can take recurring payments.

1. Understand what your service is responsible for

You have more responsibilities when taking recurring payments than when taking standard payments through GOV.UK Pay.

Your additional responsibilities include:

managing the direct relationship between your service and users
providing a system to authenticate users when logging in to your service – if you’re eligible, we recommend using GOV.UK One Login to do this
making the terms, conditions, and purpose of the recurring payments clear to your users so they can consent and you can record this consent
setting up, managing, and fulfilling the schedule to take payments from users
telling users when you’re going to take a recurring payment and how much the payment will be
telling users if you change the amount or timing of their recurring payments
letting users manage or cancel recurring payments

2. Enable recurring payments with GOV.UK Pay

Email govuk-pay-support@digital.cabinet-office.gov.uk and ask us to enable recurring payments on your test account.

3. Enable recurring payments with your payment service provider

If your PSP is Worldpay, you must enable tokenisation on your account before you can take recurring payments. Contact your Worldpay relationship manager and ask them to enable tokenisation.

If your PSP is Stripe, you do not need to do anything before you start setting up recurring payments.

Create an agreement for recurring payments

An agreement represents an understanding between you and your paying user that you’ll use their payment details to make ongoing payments for a service.

Use this endpoint to create an agreement:

POST /v1/agreements

Example request:

{
"reference": "CT-22-23-0001",
"description": "Dorset Council 2022/23 council tax subscription.",
"user_identifier": "user-3fb81107-76b7-4910"
}

In the body of your request, you must include:

a human-readable description of the purpose of the agreement that we’ll show your user when they enter their payment details (description)
a reference for this agreement (reference)

You can also send a user_identifier parameter to associate an identifier with this user to help you identify them.

You’ll receive a response like this:

{
"agreement_id": "cgc1ocvh0pt9fqs0ma67r42l58",
"reference": "CT-22-23-0001",
"description" : "Dorset Council 2022/23 council tax subscription.",
"status": "CREATED",
"user_identifier": "user-3fb81107-76b7-4910",
"created_date": "2022-07-08T14:33:00.000Z",
}

This response contains:

a unique ID GOV.UK Pay automatically associated with this agreement (agreement_id)
the reference, description, and user identifier (if any) you associated with this agreement (reference, description, user_identifier)
the agreement’s current status (status)
the date and time you created the agreement (created_date)

You can see definitions and possible values of every parameter and attribute in our reference documentation for this endpoint.

Set up an agreement for recurring payments

Once you’ve created the agreement, you need to set it up to start taking recurring payments with the user’s card.

To set up the agreement, you must take the first payment from your user and tell the GOV.UK Pay API to save their card details:

Make your user aware of the terms, conditions, and purpose of the recurring payments. They must understand that you’ll use their payment details to take future payments.
Record the user’s consent to your terms and conditions.
Add set_up_agreement: "{AGREEMENT_ID}" to your request when creating the user’s first payment. Replace {AGREEMENT_ID} with the agreement_id the API sent when you created the agreement. You’ll also need to include the usual required parameters for creating a payment - amount, description, reference, and return_url.

Your request to create this first payment should look something like this:

{
  "amount": 1000,
  "description": "First payment for 2022/23 council tax.",
  "reference": "CT-payment1",
  "return_url": "https://service.gov.uk",
  "set_up_agreement": "cgc1ocvh0pt9fqs0ma67r42l58"
}

set_up_agreement tells our API to save your user’s card details when they complete this payment. We use a token to represent the user’s card details. This token is associated with the agreement with the ID you send.

You can also use set_up_agreement to reactivate a cancelled or expired agreement.

When your user is making their first payment, GOV.UK Pay will show your user the description you sent when you created the agreement.

Once the user has made the payment, the agreement’s status will be active. You can use active agreements to take recurring payments.

If the user’s payment fails, their payment details are not saved and the agreement’s status remains created.

Read more about creating payments in our guidance for taking payments or our API reference page for creating payments.

Taking recurring payments

Once you’ve set up the agreement, you can use it to take recurring payments without the paying user interacting with your service.

Your user must know when you are going to take payments. For example, if you take payments on an agreed schedule, you must make your user aware of which day of the month you’ll take payments. If you take payments irregularly, you must let your user know you’re going to take a payment.

To take a recurring payment, create a payment through the API (POST /v1/payments) and include the following parameters in the request body:

"authorisation_mode": "agreement"
"agreement_id": "{AGREEMENT_ID}"

Replace {AGREEMENT_ID} with the agreement_id you just set up.

You do not need to send a return_url.

Your request should look something like this:

{
  "amount": 1000,
  "description": "Council tax payment for 2022/23",
  "reference": "CT-payment1",
  "authorisation_mode": "agreement",
  "agreement_id": "cgc1ocvh0pt9fqs0ma67r42l58"
}

The API returns a standard create payment response. Successful responses include the agreement_id you sent and authorisation_mode is agreement.

GOV.UK Pay uses a token representing the user’s saved payment details from the agreement to take the payment.

Check the status of the payment through our API (GET /v1/payments/{PAYMENT_ID}) or by using webhooks to get automatic payment event updates.

If a recurring payment fails when we try to take it, it’s handled like any other failed payment.

Read more about creating payments in our guidance for taking payments or our API reference page for creating payments.

Use GOV.UK Pay’s optional features with recurring payments

You can use some of GOV.UK Pay’s optional features when taking recurring payments. You can:

Use idempotency to avoid double-charging a user

Warning We have not yet built idempotency for recurring payments but this section explains how we intend to add it later in Q1 2023. This information is subject to change.

Idempotency in an API is when multiple identical requests have the same effect as making a single request. In GOV.UK Pay, you’ll be able to avoid double-charging users by making idempotent requests when creating recurring payments.

Idempotency is useful if you create a recurring payment through our API but do not receive a response due to network failure. In this situation:

with idempotency, further payment creation requests with the same idempotency key will not create new payments
without idempotency, further payment creation requests will create new payments and could double-charge your user

We have not built idempotency into GOV.UK Pay yet but plan to finalise how it will work in Q1 2023. Our most likely approach will be to add a new header to API requests. To make an idempotent request, you’ll use this header when creating a recurring payment:

-H "Idempotency-Key: {KEY}"

Replace {KEY} with a unique identifier for this payment. You could randomly generate this identifier or follow a system, such as a combination of the agreement reference and payment date.

If you make another payment creation request with the same Idempotency-Key, it will not create a new payment.

Use webhooks to receive automatic event updates

You can use webhooks to automatically receive updates when recurring payments fail or succeed.

You may want to use these webhooks to trigger a notification in your case management or finance systems.

Test your recurring payments integration

GOV.UK Pay have mock card numbers for you to test your integration, including a mock card number for testing recurring payments. You can use this mock card number to set up an agreement with an initial payment, but further recurring payments will be declined.

Reporting on recurring payments

You can find information about agreements you’ve created in the GOV.UK Pay admin tool or through our API.

Reporting using the GOV.UK Pay admin tool

The GOV.UK Pay admin tool lists your service’s agreements for recurring payments.

Using the admin tool, you can find agreements, cancel agreements, and see payments associated with an agreement.

Searching agreements for recurring payments

You can use the GOV.UK Pay API to search agreements for recurring payments.

Use the following endpoint to search agreements:

GET /v1/agreements

Example response:

{
  total: 45,
  count: 20,
  page: 1,
  results: [
    {
      "agreement_id": "cgc1ocvh0pt9fqs0ma67r42l58",
      "reference": "CT-22-23-0001",
      "description": "Dorset Council 2022/23 council tax subscription.",
      "status": "active",
      "user_identifier": "user-3fb81107-76b7-4910",
      "created_date": "2022-07-08T14:33:00.000Z",
      "payment_instrument": {
        "type": "card",
        "card_details": {
          "card_brand": "Visa",
          "card_type": "debit",
          "last_digits_card_number": "1234",
          "first_digits_card_number": "123456",
          "expiry_date": "04/24",
          "cardholder_name": "Sherlock Holmes",
          "billing_address": {
            "line1": "221 Baker Street",
            "line2": "Flat b",
            "postcode": "NW1 6XE",
            "city": "London",
            "country": "GB"
          }
        }
      }
    }
    {
      "agreement_id": "tut4wrjk5lp1qbr5jz92a37t00",
      "reference": "CT-22-23-0002",
      "status": "active",
      ...
    }
    ]
  }

Each object in results represents a single agreement and contains:

the unique ID GOV.UK Pay automatically associated with this agreement (agreement_id)
the reference you associated with this agreement when you created it (reference)
the current status of the agreement (status)
information about the user’s card (payment_instrument)

Read our API reference for more information about this endpoint. For example, what parameters you can use to narrow your search, and a full index of response attributes.

Getting information about an agreement for recurring payments

You can get information about a specific recurring payments agreement through the GOV.UK Pay API.

Use the following endpoint to get information about an agreement:

GET /v1/agreements/{AGREEMENT_ID}

Replace {AGREEMENT_ID} with the ID of the agreement you’re getting information about.

Example response:

{
  "agreement_id": "cgc1ocvh0pt9fqs0ma67r42l58",
  "reference": "CT-22-23-0001",
  "description": "Dorset Council 2022/23 council tax subscription.",
  "status": "active",
  "created_date": "2022-07-08T14:33:00.000Z",
  "payment_instrument": {
    "type": "card",
    "card_details": {
      "card_brand": "Visa",
      "card_type": "debit",
      "last_digits_card_number": "1234",
      "first_digits_card_number": "123456",
      "expiry_date": "04/24",
      "cardholder_name": "Sherlock Holmes",
      "billing_address": {
        "line1": "221 Baker Street",
        "line2": "Flat b",
        "postcode": "NW1 6XE",
        "city": "London",
        "country": "GB"
      }
    }
  }
}

In the response, you’ll receive:

details you entered and GOV.UK Pay generated when the agreement was created (agreement_id, reference, description)
the current status of the agreement (status)
the date you created the agreement (created_date)
details about the user’s payment method if you’ve set up the agreement (payment_instrument)

Read our API reference for a full index of this endpoint’s response attributes.

Finding recurring payments by agreement

You can use the search payments endpoint (GET /v1/payments) to find payments that GOV.UK Pay authorised using a specific agreement.

Use the agreement_id={AGREEMENT_ID} query parameter. Replace {AGREEMENT_ID} with the ID of an agreement to return payments authorised by that agreement.

This example would return all payments authorised by the agreement with the ID cgc1ocvh0pt9fqs0ma67r42l58:

GET /v1/payments?agreement_id=cgc1ocvh0pt9fqs0ma67r42l58

Understanding agreement status

When you use the API to get information about agreements, the status response attribute tells you what state the agreement is currently in.

Status	Meaning
`created`	You have created the agreement using the API. Your user has not yet made their first payment to set up the agreement.
`active`	You have set up the agreement by saving a user’s card details when they make their first payment. You can use this agreement to take recurring payments.
`cancelled`	You have cancelled the agreement. You cannot use this agreement to take recurring payments unless you set it up again. Read more about cancelling and reactivating agreements for recurring payments or API reference documentation.
`expired`	The user’s payment method has expired. You cannot use this agreement to take recurring payments unless you set it up again.

Cancel an agreement for recurring payments

You can cancel an agreement for recurring payments at any time. You may want to cancel an agreement if a user no longer needs to make payments. You cannot use a cancelled agreement to take payments.

You must provide a way for your users to return to your service and cancel their recurring payments.

To cancel an agreement, use this endpoint:

POST /v1/agreements/{AGREEMENT_ID}/cancel

Replace {AGREEMENT_ID} with the ID of the agreement you’re cancelling.

A successful agreement cancellation returns a 204 HTTP status code without a response body.

You can set up a cancelled agreement again by taking a payment from the user and telling the GOV.UK Pay API to save the user’s card details. This is the same thing you did to set up the agreement the first time.

Read our API reference for request and response examples, and a full index of this endpoint’s response attributes.