Sign in

v39

latestOpenAPI 3.0.1raw.githubusercontent.com2025-10-031646108.8 KB
Agreements

Create an agreement for recurring payments

You can use this endpoint to create a new agreement.

post/v1/agreements

Request body

descriptionstring

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.

referencestring

Associate a reference with this agreement to help you identify it. Limited to 255 characters.

user_identifierstring

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

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

Response

Created

agreement_idstring

The unique ID GOV.UK Pay automatically associated with this agreement when you created it.

cancelled_datestring

The date and time this agreement was cancelled. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – YYYY-MM-DDThh:mm:ss.sssZ.

created_datestring

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.

descriptionstring

The description you sent when creating this agreement.

referencestring

The reference you sent when creating this agreement.

status'created' | 'active' | 'cancelled' | 'inactive'

The status of this agreement. You can read more about the meanings of each agreement status.

user_identifierstring

The identifier you sent when creating this agreement. user_identifier helps you identify users in your records.

Example response

{
  "agreement_id": "cgc1ocvh0pt9fqs0ma67r42l58",
  "cancelled_date": "2022-07-08T14:33:00.000Z",
  "created_date": "2022-07-08T14:33:00.000Z",
  "description": "Dorset Council 2022/23 council tax subscription.",
  "payment_instrument": {
    "CardDetails": {
      "billing_address": {
        "city": "address city",
        "country": "GB",
        "line1": "address line 1",
        "line2": "address line 2",
        "postcode": "AB1 2CD"
      }
    },
    "created_date": "2022-07-08T14:33:00.000Z"
  },
  "reference": "CT-22-23-0001",
  "user_identifier": "user-3fb81107-76b7-4910"
}