Create an agreement for recurring payments

POST/v1/agreements

You can use this endpoint to create a new agreement.

Requires a bearer token.

In this mock: reference is required. The agreement starts as created and becomes active when a payment created with set_up_agreement succeeds.

Request body

Name	Type	Description
description	string	A human-readable description of the purpose of the agreement for recurring payments. We’ll show the description to your user when they make their first payment to activate this agreement. Limited to 255 characters.
reference	string	Associate a reference with this agreement to help you identify it. Limited to 255 characters.
user_identifier	string	Associate an identifier with the user who will enter into this agreement with your service.user_identifier is not unique – multiple agreements can have identical user_identifier values.You should not include personal data in user_identifier.

Example request

curl -X POST "https://publicapi.payments.platform-engineering.com/v1/agreements" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Dorset Council 2022/23 council tax subscription.",
  "reference": "CT-22-23-0001",
  "user_identifier": "user-3fb81107-76b7-4910"
}'

Responses

201: Created

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

400: Bad request

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

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)

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