> ## 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. # Provision VGS vault credentials > Resolves the CreditCard payment account for the cart, pins the routing decision on the cart, and returns the VGS Collect vault credentials used to tokenize card data client-side. No request body. This begins the card payment flow: after tokenizing the card (and completing 3D Secure via `verify` when the returned `requires_3ds` is `true`) the server produces a Fluid payment reference that the Cart checkout `complete_cart` step (`POST /api/checkout/v2026-04/carts/{cart_token}/complete`, Checkout endpoints reference) consumes as its `payment_uuid` query parameter. Cart-token authenticated. Returns `404` when the cart or payment account is not found and `410` when the cart has already been processed. ## OpenAPI ````yaml /api-reference/payments-v2026-04.yaml post /api/payments/v2026-04/carts/{cart_token}/tokenize 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}/tokenize: post: tags: - payments summary: Provision VGS vault credentials description: > Resolves the CreditCard payment account for the cart, pins the routing decision on the cart, and returns the VGS Collect vault credentials used to tokenize card data client-side. No request body. This begins the card payment flow: after tokenizing the card (and completing 3D Secure via `verify` when the returned `requires_3ds` is `true`) the server produces a Fluid payment reference that the Cart checkout `complete_cart` step (`POST /api/checkout/v2026-04/carts/{cart_token}/complete`, Checkout endpoints reference) consumes as its `payment_uuid` query parameter. Cart-token authenticated. Returns `404` when the cart or payment account is not found and `410` when the cart has already been processed. operationId: payments_v2026_04_tokenize 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 responses: '200': description: Vault credentials content: application/json: schema: $ref: '#/components/schemas/TokenizeResponse' examples: vault: summary: VGS vault credentials for client-side tokenization value: vault: vault_id: tntabc123 environment: sandbox route_id: rt_9x8y7z mode: preflight requires_3ds: false requires_3ds: false payment_account_id: 4021 meta: request_id: 018f2c1a-8b3a-7e6d-9f10-2a3b4c5d6e7f timestamp: '2026-04-01T12:00:00Z' '404': description: Cart or payment account not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '410': description: Cart already processed content: application/json: schema: $ref: '#/components/schemas/ProcessedCartResponse' security: [] components: schemas: TokenizeResponse: description: Success body for VGS vault provisioning. type: object additionalProperties: false required: - vault - requires_3ds - payment_account_id - meta properties: vault: $ref: '#/components/schemas/VgsVault' requires_3ds: type: boolean description: >- `true` when 3D Secure is required for this card; mirrors `vault.requires_3ds`. When `true`, call `verify` before authorizing. payment_account_id: type: integer description: >- Id of the CreditCard payment account resolved and pinned to the cart for this tokenization; routing is fixed to this account for the rest of the flow. meta: $ref: '#/components/schemas/Meta' 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' 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' VgsVault: description: VGS Collect vault credentials used to tokenize card data client-side. type: object additionalProperties: false required: - vault_id - environment - route_id - mode - requires_3ds properties: vault_id: type: - string - 'null' description: >- VGS Collect vault (tenant) id the browser initializes VGS Collect with; `null` when no vault is configured for the resolved payment account. environment: type: - string - 'null' description: >- VGS environment for the vault (e.g. `sandbox`, `live`); `null` when unset. route_id: type: - string - 'null' description: >- VGS route id that governs how the tokenized card is forwarded to the gateway; `null` when unset. mode: type: string description: VGS Collect operating mode for this tokenization attempt. requires_3ds: type: boolean description: >- `true` when the resolved payment account requires 3D Secure; the client must then run the `verify` step before the card can be authorized. 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. 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' 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' 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' ````