Take recurring payments

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.

When you’ve tested your recurring payments service, follow our go live documentation to start taking payments from your users.

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

Update a user’s recurring payment card details

You can update the card used to take recurring payments. This overrides the existing card details. You should do this if a user’s existing card is going to expire soon, or if a user tells you they want to pay with a different card.

To update the user’s card details, repeat the process to set up an agreement by creating a payment and adding set_up_agreement: "{AGREEMENT_ID}" to your API request body. Replace "{AGREEMENT_ID}" with the same agreement_id you sent when first setting up this agreement.

Once the user has successfully made the payment, you can take recurring payments using their new card.

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. You can read more about what you need to do when a recurring payment fails.

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

Handling failed recurring payments

If a recurring payment fails, you may not be able to continue using the same agreement for recurring payments.

Get information about the failed recurring payment through our API (GET v1/payments/{PAYMENT_ID}) to find out if you can continue using the agreement to take payments.

Our API returns a can_retry attribute in the state object. Depending on why the payment failed, can_retry has two possible values:

true - you can try to take another payment with the the associated agreement
false - you cannot try to take another payment with the associated agreement

You can try to take another payment with the user’s agreement if, for example, the paying user had insufficient funds when you first tried to take the payment.

You cannot try to take more payments with the same agreement if, for example, the paying user has lost their payment card or contacted their bank to block payments to your service.

Handling failed recurring payments that can be retried

If can_retry is true, you can try to take another recurring payment with the agreement.

Take another payment in the same way you usually take recurring payments. Create a new payment (POST /v1/payments) and include "authorisation_mode": "agreement" and "agreement_id": "{AGREEMENT_ID}" in your request body.

Before you try to take the payment again, contact your paying user to tell them their payment was declined. You should also tell them when you will try to take the payment again.

You should wait at least 48 hours after a declined payment before trying to take another payment.

If you try to take a payment more than 15 times in 30 days, card issuers may charge you for excessive retries.

Handling failed recurring payments that cannot be retried

If can_retry is false, you cannot take another recurring payment with the agreement. The agreement’s status will become inactive and additional recurring payment attempts will fail. Your payment service provider may charge fees on failed recurring payments.

You should contact the user to resolve the situation.

To continue using the same agreement to take recurring payments, you must set up the agreement again by taking a payment from your user. This is the same thing you did when you set up the agreement the first time. Depending on your user journey, you may need to get consent from the user again.

You can also create a new agreement for recurring payments. The user’s payment history will still be associated with the cancelled agreement. Any new recurring payments will be associated with the new agreement.

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

Idempotency in an API is when multiple identical requests have the same effect as making a single request. In GOV.UK Pay, you can avoid double-charging users by using the Idempotency-Key header to make your API requests idempotent when taking 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

Use this header when creating a recurring payment to make your request idempotent:

-H "Idempotency-Key: {KEY}"

Replace {KEY} with a unique identifier for this payment. You could follow a system to generate this identifier, such as a combination of the agreement reference and payment date. You could also randomly generate this identifier using version 4 universally unique identifiers (UUIDs). For example:

-H "Idempotency-Key: 77b115e0-f765-4bbe-8891-eec2239e633e"

Idempotency-Key must be between 1 and 255 characters and made up of numbers, letters, or hyphens. Do not use special characters.

If you send a payment creation request with an identical Idempotency-Key and request body within 24 hours of your original request, you’ll get a 200 successful response. Our API returns details of the original payment. You have not created a new payment.

If you send a payment creation request with the same Idempotency-Key but a different request body, our API returns a 409 response. You have not created a new payment.

If you send an invalid Idempotency-Key, our API returns a 422 response. You have not created 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.
`inactive`	You have tried to take a payment with this agreement, but the payment failed. You cannot use this agreement to take recurring payments unless you set it up again. Read more about handling failed recurring payments.

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.