Create an agreement for recurring payments API reference

This page is part of GOV.UK Pay’s API reference and is an index of the following things you’ll use when creating agreements for recurring payments:

• parameters
• example requests
• example responses
• attributes you’ll get in your response

You can also read more about the end-to-end process of taking recurring payments using GOV.UK Pay in our task-based guidance.

The URL for this endpoint is:

POST https://publicapi.payments.service.gov.uk/v1/agreements

You can use this endpoint to create a new agreement.

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

The data from this endpoint is strongly consistent, meaning it is updated immediately after you make any changes. You can read more about data consistency in our API.

JSON body parameters for ‘Create an agreement for recurring payments’

Name	Type	Description
reference (required)	string	Associate a reference with this agreement to help you identify it. Limited to 255 characters.
description (required)	string	A human-readable description of the purpose of the agreement for recurring payments. We’ll show the description to your user when they make their first payment to activate this agreement. Limited to 255 characters.
user_identifier (optional)	string	Associate an identifier with the user who will enter into this agreement with your service. user_identifier is not unique – multiple agreements can have identical user_identifier values. You should not include personal data in user_identifier.

Example request for ‘Create an agreement for recurring payments’

This example request creates an agreement for the service to take council tax from the user user-3fb81107-76b7-4910 for the year 2022/23:

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

Example response for ‘Create an agreement for recurring payments’

After you send your request to create an agreement for recurring payments, you’ll receive a response similar to this example:

{
"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",
}

Attributes you’ll get in a ‘Create an agreement for recurring payments’ response

Name	Type	Description
agreement_id	string	The unique ID GOV.UK Pay automatically associated with this agreement when you created it.
reference	string	The reference you sent when creating this agreement.
description	string	The description you sent when creating this agreement.
status	string	The status of this agreement. status value will automatically be set to created because you’ve just created this agreement. You can read more about the meanings of each agreement status.
user_identifier	status	The identifier you sent when creating this agreement. user_identifier helps you identify users in your records.
created_date	date (ISO 8601)	The date and time you created this agreement. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – YYYY-MM-DDThh:mm:ss.sssZ.