Get information about a single agreement for recurring payments

GET/v1/agreements/{agreementId}

You can use this endpoint to get information about a single recurring payments agreement.

Requires a bearer token.

In this mock: payment_instrument appears once the agreement is active.

Path parameters

Name	Type	Description
agreementId required	string	Returns the agreement with the matching agreement_id. GOV.UK Pay generated an agreement_id when you created the agreement.

Example request

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

Responses

200: OK - your request was successful.

Name	Type	Description
agreement_id	string	The unique ID GOV.UK Pay automatically associated with this agreement when you created it.
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.
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.
description	string	The description you sent when creating this agreement.
payment_instrument	object
payment_instrument.CardDetails	object
payment_instrument.CardDetails.billing_address	object	A structure representing the billing address of a card
payment_instrument.CardDetails.billing_address.city	string	The paying user's city.
payment_instrument.CardDetails.billing_address.country	string	The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.
payment_instrument.CardDetails.billing_address.line1	string	The first line of the paying user’s address.
payment_instrument.CardDetails.billing_address.line2	string	The second line of the paying user’s address.
payment_instrument.CardDetails.billing_address.postcode	string	The paying user's postcode.
payment_instrument.CardDetails.card_brand	string
payment_instrument.CardDetails.card_type	string
payment_instrument.CardDetails.cardholder_name	string
payment_instrument.CardDetails.expiry_date	string
payment_instrument.CardDetails.first_digits_card_number	string
payment_instrument.CardDetails.last_digits_card_number	string
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.
payment_instrument.type	string	The type of payment instrument. One of: card
reference	string	The reference you sent when creating this agreement.
status	string	The status of this agreement. You can read more about the meanings of each agreement status. One of: created, active, cancelled, inactive
user_identifier	string	The identifier you sent when creating this agreement. user_identifier helps you identify users in your records.

{
  "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",
    "type": "card"
  },
  "reference": "CT-22-23-0001",
  "status": "created",
  "user_identifier": "user-3fb81107-76b7-4910"
}

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"
}

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"
}