> ## 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="New Payment Attempts API for Backend-Driven CIT (manual payment approval).">
  Added support for **manual payment approval** (Backend-Driven CIT), which lets your backend approve or abort each payment after tokenization and before the payment is created. See the [Manual payment approval](/docs/checkout/primer-checkout/guides-and-recipes/manual-payment-approval) guide.

  **Client Session API**

  * Added `approvalMode` (`AUTO` / `MANUAL`) on the request and response. Set to `MANUAL` to require explicit approval of each payment attempt. Defaults to `AUTO`. Set at creation only; it cannot be changed with `PATCH /client-session`.
  * Added `currentAttemptId` on the response, pointing to the active payment attempt for `MANUAL` sessions.

  **Payment Attempts API (new)**

  * Added `POST /payment-attempts/{id}/approve` to approve a payment attempt and trigger payment creation. Returns `paymentAttemptId` and `paymentId`. Requires the `transactions:authorize` scope.
  * Added `POST /payment-attempts/{id}/abort` to cancel a pending payment attempt. No payment is created and the tokenized payment method is invalidated.
</Update>

<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.
  * **Authorization Code → Easier Reconciliation & Chargeback Matching**
    * Added `transactions[].authorizationCode`, the authorization code returned by the processor on a successful authorization. It is returned in Payments API responses and payment webhooks, and omitted when not present. This field is available for selected processors only and is being rolled out processor by processor, so it will be absent for processors that are not yet supported. Treat a missing `authorizationCode` as "not available" rather than an error.
      Removed processor data and external IDs from the API responses and webhooks in favour of [`transactions.events`](/docs/changelogs/migration-guides/API-2.3-to-2.4).
      For more details, please see our [detailed migration guide](/docs/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](/docs/sdk/web/v2.x.x/constants/payment-method-types/)
  * The payment status webhook was improved to return the correct [paymentMethodTypeAPI](/docs/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>