Skip to main content

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 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
  • expired

    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:SSZ.
    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