> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Set the cart payment method > Sets the payment method on the cart (idempotent). The request and response shapes vary by payment type. The declared contract requires type; the saved-payment-method flow (payment_method_id) is the only flow that may omit payment_method. ## OpenAPI ````yaml /api-reference/payments-v2026-04.yaml put /api/payments/v2026-04/carts/{cart_token}/payment_method openapi: 3.1.0 info: title: Fluid Cart Payments API version: v2026-04 description: >- Consumer-agnostic, cart-scoped payment endpoints under /api/payments/v2026-04/carts/{cart_token}. The same endpoints serve checkout, admin, and portal identically. Authentication is cart-token based (the token in the path); no JWT or API key is required. This spec is the source of truth for generated payment API clients and is intentionally separate from payment-v2026-04.yaml, which documents the bearer-authenticated gateway/transaction admin surface at /api/payment/v2026-04. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app security: [] tags: - name: payments description: >- Cart-scoped payment method selection, VGS card tokenization, and 3D Secure verification. - name: paypal description: >- PayPal checkout — client SDK token, order creation and authorization, and shipping-change callbacks. - name: braintree description: Braintree checkout — client token issuance and transaction authorization. - name: klarna description: Klarna checkout — payment session creation and updates. - name: apple-pay description: Apple Pay checkout — merchant session validation. paths: /api/payments/v2026-04/carts/{cart_token}/payment_method: put: tags: - payments summary: Set the cart payment method description: >- Sets the payment method on the cart (idempotent). The request and response shapes vary by payment type. The declared contract requires type; the saved-payment-method flow (payment_method_id) is the only flow that may omit payment_method. operationId: payments_v2026_04_set_payment_method parameters: - name: cart_token in: path required: true description: > Opaque cart token returned by the create-cart response. It scopes the request to a single cart and is the credential for these endpoints — cart-token authentication carried in the path, with no bearer token or API key. schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - type properties: type: type: string description: >- Payment type (credit_card, paypal, apple_pay, klarna, bread, affirm, or a platform type such as *_citcon, *_ppro, *_dlocal). payment_method: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: >- Type-specific payment payload (e.g. VGS card fields for credit_card; order_id/token for paypal; authorization_token/session_id for klarna). billing_address: type: object additionalProperties: false description: Optional billing address. All fields are optional. properties: id: type: integer name: type: string address1: type: string address2: type: - string - 'null' city: type: string state: type: string postal_code: type: string country_code: type: string payment_account: type: - string - 'null' description: PaymentAccount UUID override for routing. customer_details: type: - object - 'null' additionalProperties: $ref: '#/components/schemas/JsonValue' description: Integration-specific customer details. device_data: type: - string - 'null' description: Braintree Data Collector fraud fingerprint. use_customer_payment_method: type: boolean description: >- Resolve payment_method_id against the customer's saved payment methods instead of the shared wallet. payment_method_id: type: - integer - string description: Existing saved PaymentMethod id (saved payment method flow). jwt: type: string description: >- Customer/user JWT authorizing use of a saved payment method (may also be sent as an Authorization header). token: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: Raw Apple Pay payment token envelope (apple_pay flow). apple_pay_token: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: >- VGS-decrypted Apple Pay token data (apple_pay flow, inbound VGS route). payment_type: type: string description: >- Secondary payment-type selector. When set to "paypal" on an apple_pay request, routes the decrypted Apple Pay token through the PayPal-on-Apple-Pay flow. examples: credit_card: summary: Credit card tokenized via VGS value: type: credit_card payment_method: vgs_card_id: card_9f8e7d6c billing_address: name: Ada Lovelace address1: 1 Analytical Way city: London state: LDN postal_code: EC1A 1BB country_code: GB saved_payment_method: summary: Reuse a customer's saved payment method value: type: credit_card payment_method_id: 4412 use_customer_payment_method: true responses: '201': description: Payment method set content: application/json: schema: $ref: '#/components/schemas/SetPaymentMethodResponse' examples: credit_card: summary: Stored card returned for a credit_card flow value: card: id: 88123 brand: visa last_four: '4242' exp_month: 12 exp_year: 2030 paypal: summary: PayPal order id returned for a paypal flow value: order_id: 5O190127TN364715T '404': description: Cart, payment, or saved payment method not found content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/BareErrorResponse' '410': description: Cart already processed content: application/json: schema: $ref: '#/components/schemas/ProcessedCartResponse' '422': description: Unprocessable entity content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/BareErrorResponse' security: [] components: schemas: JsonValue: description: >- Any valid JSON value for provider-specific payloads (card payloads, payment method payloads, Apple Pay token envelopes) whose keys are not fixed by the API contract. anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' SetPaymentMethodResponse: description: >- Success body for setting the cart payment method. The shape varies by payment type: credit_card/apple_pay return card; saved payment methods return card + payment_method; paypal returns order_id (Braintree SDK PayPal also returns transaction_id); klarna returns authorization_token; bread/affirm/platform payments return an empty object. type: object additionalProperties: false properties: order_id: type: string description: PayPal order id (paypal and decrypted Apple Pay-on-PayPal flows). transaction_id: type: string description: Braintree transaction id (Braintree SDK PayPal flow). authorization_token: type: string description: Klarna authorization token (klarna flow). card: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: >- Sanitized stored-card JSON (credit_card, apple_pay, and saved payment method flows). payment_method: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: Formatted payment method (saved payment method flow). ErrorResponse: description: >- Standard error envelope — a human-readable error_message, a structured errors object, and response meta. type: object additionalProperties: false required: - error_message - errors - meta properties: error_message: type: string description: Human-readable summary of the failure, safe to surface to the buyer. errors: $ref: '#/components/schemas/ErrorBag' meta: $ref: '#/components/schemas/Meta' BareErrorResponse: description: >- Legacy error body returned by certain payment-method creation error paths. Carries errors (array or object) and sometimes error_message, but no meta. type: object additionalProperties: false required: - errors properties: errors: $ref: '#/components/schemas/ErrorBag' error_message: type: string description: >- Optional human-readable failure summary; some legacy payment-method error paths omit it. ProcessedCartResponse: description: >- Returned with 410 Gone by every cart payment endpoint when the cart has already been processed (converted to an order). type: object additionalProperties: false required: - error_message - errors - meta properties: error_message: type: string description: >- Human-readable message stating the cart has already been processed into an order. errors: $ref: '#/components/schemas/ErrorBag' meta: $ref: '#/components/schemas/ProcessedCartMeta' ErrorBag: description: >- Validation errors keyed by field, a list of errors, a single error message, or null when no structured error details are available. anyOf: - type: string - type: array items: $ref: '#/components/schemas/ErrorValue' - type: object additionalProperties: $ref: '#/components/schemas/ErrorValue' - type: 'null' Meta: description: Standard response metadata included on every response. type: object additionalProperties: false required: - request_id - timestamp properties: request_id: type: - string - 'null' description: >- Server-assigned id for this request, echoed so responses can be correlated with server logs and support tickets; `null` when none was assigned. timestamp: type: string format: date-time description: ISO 8601 timestamp (UTC) marking when the response was generated. ProcessedCartMeta: description: >- Meta for the processed-cart guard. Carries the shop URL and the full processed cart. The cart is returned as an open object here; its fully-typed shape is documented in the checkout API. type: object additionalProperties: false required: - request_id - timestamp - shop_url - cart properties: request_id: type: - string - 'null' description: >- Server-assigned id for this request, echoed for log correlation; `null` when none was assigned. timestamp: type: string format: date-time description: ISO 8601 timestamp (UTC) marking when the response was generated. shop_url: type: - string - 'null' description: >- Storefront URL of the shop that owns the processed cart; `null` when it cannot be resolved. cart: type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: >- The full processed cart as an open object. Its fully-typed shape is documented on the Cart checkout surface (Checkout endpoints reference). ErrorValue: description: A validation or API error value. anyOf: - type: string - type: array items: type: string - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' ````