> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Changelog

<Update label="API v2.4" description="This version includes improvements to the Client Session API, Payments API and the Payment Methods API.">
  You must set the `X-Api-Version` header to `2.4` to use v2.4 of the API.

  * **Improved Payment Type Logic → More Accurate & Reliable Processing**

    * The `paymentType` field logic has been refined for better accuracy.
    * If no `paymentType` is provided, it remains blank, allowing the system to determine the best value internally.
    * Fixes incorrect categorization of one-off and vaulted payments, ensuring proper routing.
  * **Extended Timeout Management → Reduced Synchronization Issues & Better Monitoring**
    * Payment API timeout increased from 25s to 90s, allowing more time for processor responses.
    * Introduced a new `GATEWAY_TIMEOUT` decision type for better timeout tracking.
  * **Partial Captures & Targeted Refunds → Improved Reconciliation & Marketplace Payments**
    * Supports **partial captures** and **targeted refunds**, aligning payments with marketplace and logistics workflows.
    * Each partial capture generates a unique `transactionEventId`, enabling better tracking.
  * **New Payment Parameters → Enhanced Compliance & Vaulting Flexibility**
    * Added `firstPaymentReason` to specify why a payment method is vaulted (`CardOnFile`, `Recurring`, `Unscheduled`).
    * Introduced `vaultOnAgreement` to support vaulting after an agreement mandate is successfully completed.
      Removed processor data and external IDs from the API responses and webhooks in favour of [`transactions.events`](/changelogs/migration-guides/API-2.3-to-2.4).
      For more details, please see our [detailed migration guide](/changelogs/migration-guides/API-2.3-to-2.4).
</Update>

<Update label="API v2.3" description="This version includes improvements to the Payments API.">
  Set `X-Api-Version` header to `2.3` to use v2.3 of the API.

  **Payments API**

  **Improvements**<br />

  * The Payments API endpoints were modified to return error code `IdempotencyKeyAlreadyExists` with status `409` when a payment request is submitted with an `X-Idempotency-Key` that was already sent in a previous request.
  * The payment creation endpoint was improved to return the correct [paymentMethodType](/sdk/web/v2.x.x/constants/payment-method-types/)
  * The payment status webhook was improved to return the correct [paymentMethodTypeAPI](/sdk/web/v2.x.x/constants/payment-method-types)
</Update>

<Update label="API v2.2" description="This version includes improvements to the Client Session API, Payments API and the Payment Methods API.">
  You must set the `X-Api-Version` header to `2.2` to use v2.2 of the API.

  **Client Session API**
  Added `order.lineItems.productData` on the request and response

  **Payments API**
  Added `order.lineItems.productData` on the request and response
</Update>

<Update label="API v2.1" description="Version 2.1 includes improvements to the Client Session API, Payments API and the Payment Methods API.">
  Starting API v2.1, the API Version X-Api-Version is a semantic version without a patch (e.g. 2.1) rather than a date 🎉 Set the `X-Api-Version` header to `2.1` to use v2.1 of the API.

  **Client Session API**

  * Added `paymentMethod.paymentType` and `paymentMethod.descriptor` on the request and response of the client session
  * Added `order.lineItems[].productType` on the request and response of the client session
  * Added `GET /client-session` to get the content of a client session
  * Added `PATCH /client-session` to update the content of a client session
  * Additional validation has been put in place to ensure that a `currencyCode` is always passed if any `amount` value is passed

  **Payments API**

  * Added `paymentMethod.isVaulted` boolean field to indicate whether the `paymentMethod.paymentMethodToken` in the response is a vaulted token (and can therefore be used for future payments) or not. This replaces `vaultedPaymentMethodToken`.
  * Added `order.lineItems[].productType` on the request and response
    `amount`, `currencyCode`, `customerId` and `orderId` are now required fields when making a payment with a vaulted token (i.e. a recurring payment).
  * When paying with a vaulted token, additional validation has been put in place to ensure the customerId matches the customerId associated with the vaulted token.

  **Payment Methods API**

  * Added verify in `POST /payment-instruments/{paymentMethodToken}/vault` to set whether or not the payment method token should be verified before vaulting
  * Added `isVerified` to the payment method response
</Update>

<Update label="API v2" description="Version 2 includes improvements to the Client Session API and the Payments API.">
  **Client Session API**

  * `X-API-Version` -> `2021-09-27`

  * Creating a payment using only a payment method token is now possible. The `order`, `customer` and `metadata` passed on the Client Session request is then used for the payment.

  * The create Client Session endpoint request was extended to include `order`, `customer`, etc.

  * All references to `paymentInstrument` from the previous Payments API version have been refactored to `paymentMethod` to be more consistent throughout

  * The customer `billingAddress` and `shippingAddress` fields are now all optional

  **Payments API**

  * `X-API-Version` -> `2021-09-27`

  * Creating a payment using only a payment method token is now possible. The `order`, `customer` and `metadata` passed on the Client Session request is then used for the payment.

  * The create payment endpoint request was extended to include `order`, `customer`, etc. It now more closely resembles the `/client-session` endpoint

  * The response of all the Payments API endpoints was refactored to match the create payment request structure

  * All references to `paymentInstrument` from the previous Payments API version have been refactored to `paymentMethod` to be more consistent throughout

  * All the payments API endpoints (create, capture, cancel, refund, etc.) are now versioned

  * `paymentMethodData` in `PaymentMethod` responses (for card payment method types ) all now contain a `first6digits` field in addition to the `last4digits` returned. This is an opt-in field, so it is null by default.

  * The customer `billingAddress` and `shippingAddress` fields are now all optional
</Update>