Search agreements for recurring payments

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

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:

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

You can use this endpoint to search for recurring payments agreements. The agreements are sorted by date, with the most recently-created agreements appearing first.

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 ‘eventually consistent’, meaning it is updated on a delay. You can read more about data consistency in our API.

Query parameters for ‘Search agreements for recurring payments’

Your request will return agreements that match all of the criteria specified in your query parameters.

If your request has no query parameters, this endpoint returns all agreements.

Name	Type	Description
`reference` (optional)	string	Returns agreements with a `reference` that exactly matches the value you sent. This parameter is not case sensitive. A `reference` was associated with the agreement when that agreement was created.
`status` (optional)	string	Returns agreements in a matching `status`. `status` reflects where an agreement is in its lifecycle. Available `status` values are: `created` `active` `cancelled` You can read more about the meanings of the different agreement `status` values.
`page` (optional)	number	Returns a specific page of results. Defaults to `1`. You can read more about search pagination.
`display_size` (optional)	number	The number of agreements returned per results page. Defaults to `500`. Maximum value is `500`. You can read more about search pagination.

Example request for ‘Search agreements for recurring payments’

This example request returns agreements that are in the active status.

curl -X GET "https://publicapi.payments.service.gov.uk/v1/agreements?status=active" -H "Authorization: Bearer api_test_123abc456def"

Example response for ‘Search agreements for recurring payments’

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

Attributes you’ll get in a ‘Search agreements for recurring payments’ response

Name	Type	Description
`total`	number	Total number of agreements matching your search criteria.
`count`	number	Number of agreements on the current page of search results.
`page`	number	The page of results you’re viewing. To view other pages, make this request again using the `page` parameter.
`results`	object	Contains agreements matching your search criteria.
`agreement_id`	string	The unique ID GOV.UK Pay automatically associated with this agreement.
`reference`	string	The reference you associated with this agreement.
`description`	string	The description you associated with this agreement.
`status`		The status of this agreement. Possible values are: `created` `active` `cancelled` `inactive` You can read more about the meanings of each agreement `status`.
`user_identifier`	string	An identifier to help you identify the user this agreement is with.
`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`.
`cancelled_date`	date (ISO 8601)	The date and time you cancelled this agreement. `cancelled_date` only appears on cancelled agreements. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.
`payment_instrument`	object	Contains information about the user’s saved payment details. `payment_instrument` only appears if you have set up the agreement by saving the user’s payment details.
`payment_instrument.type`	string	The payment method the user is making recurring payments with. Currently, the only possible value is `card`.
`payment_instrument.card_details`	object	Contains information about the card the user is making recurring payments with.
`payment_instrument.card_details.card_brand`	string	The brand of card the user paid with. Possible values are: `american-express` `diners-club` `discover` `Jcb` `maestro` `master-card` `unionpay` `visa`
`payment_instrument.card_details.card_type`	string	The type of card the user paid with. Possible values are: `credit` `debit` `null` `null` means your user paid with Google Pay or we did not recognise which type of card they paid with.
`payment_instrument.card_details.last_digits_card_number`	number	The last 4 digits of the card the user paid with.
`payment_instrument.card_details.first_digits_card_number`	number	The first 6 digits of the card the user paid with.
`payment_instrument.card_details.expiry_date`	string	The expiry date of the card the user paid with.
`payment_instrument.card_details.cardholder_name`	string	The name on the card the user paid with.
`payment_instrument.card_details.billing_address`	object	Contains the billing address the user entered when they paid. `billing_address` can contain: `line1` (the first line of the paying user’s address) `line2` (the second line of the paying user’s address) `postcode` (the paying user’s postcode) `city` (the paying user’s city) `country` (the paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code