Search agreements for recurring payments

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

Requires a bearer token.

In this mock: reference must match exactly (not case sensitive). Errors: P2401 (422), P2402 (404).

Query parameters

Name	Type	Description
`reference`	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`	string	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. One of: created, active, cancelled, inactive
`page`	string	Returns a specific page of results. Defaults to `1`. You can read about search pagination
`display_size`	string	The number of agreements returned per results page. Defaults to `500`. Maximum value is `500`. You can read about search pagination

Example request

curl -X GET "https://publicapi.payments.platform-engineering.com/v1/agreements" \
  -H "Authorization: Bearer $TOKEN"

Responses

200: OK - your request was successful.

Name	Type	Description
`_links`	object	Links to navigate through pages of your search.
`_links.first_page`	object	A link related to a payment
`_links.first_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.first_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.last_page`	object	A link related to a payment
`_links.last_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.last_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.next_page`	object	A link related to a payment
`_links.next_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.next_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.prev_page`	object	A link related to a payment
`_links.prev_page.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.prev_page.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`_links.self`	object	A link related to a payment
`_links.self.href`	string	A URL that lets you perform additional actions to this payment when combined with the associated `method`.
`_links.self.method`	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.
`count`	integer	Number of agreements on the current page of search results.
`page`	integer	The page of agreements you’re viewing. To view other pages, make this request again using the `page` parameter.
`results[]`	array of objects	Contains agreements matching your search criteria.
`results[].agreement_id`	string	The unique ID GOV.UK Pay automatically associated with this agreement when you created it.
`results[].cancelled_date`	string	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`.
`results[].created_date`	string	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`.
`results[].description`	string	The description you sent when creating this agreement.
`results[].payment_instrument`	object
`results[].payment_instrument.CardDetails`	object
`results[].payment_instrument.CardDetails.billing_address`	object	A structure representing the billing address of a card
`results[].payment_instrument.CardDetails.card_brand`	string
`results[].payment_instrument.CardDetails.card_type`	string
`results[].payment_instrument.CardDetails.cardholder_name`	string
`results[].payment_instrument.CardDetails.expiry_date`	string
`results[].payment_instrument.CardDetails.first_digits_card_number`	string
`results[].payment_instrument.CardDetails.last_digits_card_number`	string
`results[].payment_instrument.created_date`	string	The date and time you created this payment instrument. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.
`results[].payment_instrument.type`	string	The type of payment instrument. One of: card
`results[].reference`	string	The reference you sent when creating this agreement.
`results[].status`	string	The status of this agreement. You can read more about the meanings of each agreement status. One of: created, active, cancelled, inactive
`results[].user_identifier`	string	The identifier you sent when creating this agreement. `user_identifier` helps you identify users in your records.
`total`	integer	Total number of agreements matching your search criteria.

{
  "_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": {}
        },
        "created_date": "2022-07-08T14:33:00.000Z",
        "type": "card"
      },
      "reference": "CT-22-23-0001",
      "status": "created",
      "user_identifier": "user-3fb81107-76b7-4910"
    }
  ],
  "total": 100
}

401: Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)

404: Not found

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}

422: Your request failed. Check the `code` and `description` in the response to find out why your request failed.

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}

429: Too many requests

Name	Type	Description
`code`	string	A GOV.UK Pay API error code. You can find out more about this code in our documentation.
`description`	string	Additional details about the error

{
  "code": "P0900",
  "description": "Too many requests"
}

500: Downstream system error

Name	Type	Description
`code`	string	An API error codethat explains why the payment failed.<br><br>`code` only appears if the payment failed.
`description`	string	Additional details about the error.
`field`	string	The parameter in your request that's causing the error.
`header`	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}