---
title: "Changes to Create a payment"
method: POST
path: "/v1/payments"
---

# Changes to Create a payment

`POST /v1/payments`

> Every recorded change to this operation, newest first.

## Timeline

Changed in 13 of 40 revisions.

- **2026-10-13** `6dc4b2c91eb8`: 1 breaking, 1 info
- **2025-10-03** `4dc2d80f453a`: 1 info
- **2025-01-21** `fdf8c84e093b`: 1 warning, 8 info
- **2023-09-26** `c030b46b3923`: 1 info
- **2023-07-06** `ec312e19c6b1`: 1 warning
- **2023-05-24** `5b2a07839c95`: 1 info
- **2023-04-27** `53c381c6cbdf`: 1 breaking
- **2023-04-18** `c8f226fc66d4`: 4 info
- **2023-02-09** `37a88eb77e2c`: 1 breaking
- **2023-02-09** `8d28e758fd65`: 3 info
- **2022-05-31** `85a2dd6e13df`: 1 info
- **2022-04-19** `ba9494f145d3`: 1 warning
- **2021-10-25** `de9164c91396`: 1 info

## Changes

- **2026-10-13** `6dc4b2c91eb8`: 1 breaking, 1 info
  - the request property `metadata/metadata` became required
  - the response property `metadata/metadata` became required for the status `201`
- **2025-10-03** `4dc2d80f453a`: 1 info
  - added the new optional request property `agreement_payment_type`
- **2025-01-21** `fdf8c84e093b`: 1 warning, 8 info
  - removed the optional property `card_details/wallet_type` from the response with the `201` status
  - the response optional property `card_details/card_brand` became not read-only for the status `201`
  - the response optional property `card_details/card_type` became not read-only for the status `201`
  - the response optional property `card_details/expiry_date` became not read-only for the status `201`
  - the response optional property `card_details/first_digits_card_number` became not read-only for the status `201`
  - the response optional property `card_details/last_digits_card_number` became not read-only for the status `201`
  - removed the `credit` enum value from the `card_details/card_type` response property for the response status `201`
  - removed the `debit` enum value from the `card_details/card_type` response property for the response status `201`
  - removed the `null` enum value from the `card_details/card_type` response property for the response status `201`
- **2023-09-26** `c030b46b3923`: 1 info
  - added the optional property `card_details/wallet_type` to the response with the `201` status
- **2023-07-06** `ec312e19c6b1`: 1 warning
  - changed the pattern of the `header` request parameter `Idempotency-Key` from `^[a-zA-Z0-9-]+$` to `^$|^[a-zA-Z0-9-]+$`
- **2023-05-24** `5b2a07839c95`: 1 info
  - added the optional property `state/can_retry` to the response with the `201` status
- **2023-04-27** `53c381c6cbdf`: 1 breaking
  - added the pattern `^[a-zA-Z0-9-]+$` to the `header` request parameter `Idempotency-Key`
- **2023-04-18** `c8f226fc66d4`: 4 info
  - added the new optional `header` request parameter `Idempotency-Key`
  - added the optional property `header` to the response with the `400` status
  - added the optional property `header` to the response with the `422` status
  - added the optional property `header` to the response with the `500` status
- **2023-02-09** `37a88eb77e2c`: 1 breaking
  - removed the enum value `external` of the request property `authorisation_mode`
- **2023-02-09** `8d28e758fd65`: 3 info
  - added the new optional request property `agreement_id`
  - added the new optional request property `authorisation_mode`
  - added the new optional request property `set_up_agreement`
- **2022-05-31** `85a2dd6e13df`: 1 info
  - added the optional property `_links/auth_url_post` to the response with the `201` status
- **2022-04-19** `ba9494f145d3`: 1 warning
  - added the new `debit` enum value to the `card_details/card_type` response property for the response status `201`
- **2021-10-25** `de9164c91396`: 1 info
  - removed the `debit` enum value from the `card_details/card_type` response property for the response status `201`

---

[Operation](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/docs/v1/payments/post.md) - [API](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api.md) - [Page](https://skmtc.dev/government-digital-service/apis/gov-uk-pay-api/changes/v1/payments/post)