GOgovernment-digital-service
Agreements

Search agreements for recurring payments

Changed on

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.

get/v1/agreements

Request

  • Base URL
    https://publicapi.payments.service.gov.uk
  • URL
    https://publicapi.payments.service.gov.uk/v1/agreements
  • Auth
    HTTP bearer

Query parameters

referencestring

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'created' | 'active' | 'cancelled' | 'inactive'

Returns agreements in a matching status. status reflects where an agreement is in its lifecycle. You can read more about the meanings of the different agreement status values.

pagestring

Returns a specific page of results. Defaults to 1. You can read about search pagination

display_sizestring

The number of agreements returned per results page. Defaults to 500. Maximum value is 500. You can read about search pagination

Response

OK - your request was successful.

countinteger

Number of agreements on the current page of search results.

pageinteger

The page of agreements you’re viewing. To view other pages, make this request again using the page parameter.

totalinteger

Total number of agreements matching your search criteria.

Example response

{
  "_links": {
    "first_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "last_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "next_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "prev_page": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "count": 20,
  "page": 1,
  "results": [
    {
      "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"
    }
  ],
  "total": 100
}

Changes

  • fdf8c84e093bRevision changes
    • warning

      removed the optional property //// from the response with the status

    • info

      the response optional property //// became not read-only for the status

    • info

      the response optional property //// became not read-only for the status

    • info

      the response optional property //// became not read-only for the status

    • info

      the response optional property //// became not read-only for the status

    • info

      the response optional property //// became not read-only for the status

    • info

      removed the credit enum value from the //// response property for the response status

    • info

      removed the debit enum value from the //// response property for the response status

    • info

      removed the null enum value from the //// response property for the response status

  • c030b46b3923Revision changes
    • info

      added the optional property //// to the response with the status