Get information about a single 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 getting information about a recurring payments agreement:

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/{AGREEMENT_ID}

You can use this endpoint to get information about a single recurring payments 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.

Path parameters for ‘Get information about a single agreement for recurring payments’

Name	Type	Description
`{AGREEMENT_ID}`	string	Returns the agreement with the matching `agrement_id`. GOV.UK Pay generated an `agreement_id` when you created the agreement.

Example request for ‘Get information about a single agreement for recurring payments’

This example request gets information about the agreement with the ID cgc1ocvh0pt9fqs0ma67r42l58:

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

Example response for ‘Get information about a single agreement for recurring payments’

After you send your request, 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": "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"
      }
    }
  }
}

Attributes you’ll get in a ‘Get information about a single agreement for recurring payments’ response

Name	Type	Description
`agreement_id`	string	The unique ID GOV.UK Pay automatically associated with this agreement. `agreement_id` will match the ID you sent in your request.
`reference`	string	The reference you associated with this agreement.
`description`	string	The human-readable description you associated with this agreement.
`status`	string	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