> ## 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. # Validate an Apple Pay merchant session > Requests a merchant session from Apple's startSession endpoint on behalf of the storefront domain. Requires a Referer header matching a verified domain. ## OpenAPI ````yaml /api-reference/payments-v2026-04.yaml post /api/payments/v2026-04/carts/{cart_token}/apple_pay/validate 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}/apple_pay/validate: post: tags: - apple-pay summary: Validate an Apple Pay merchant session description: >- Requests a merchant session from Apple's startSession endpoint on behalf of the storefront domain. Requires a Referer header matching a verified domain. operationId: payments_v2026_04_apple_pay_validate 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: - company_id - country_id - apple_session_url properties: company_id: type: integer country_id: type: integer apple_session_url: type: string format: uri description: >- Apple Pay startSession endpoint URL provided by the Apple Pay JS onvalidatemerchant event. examples: validate: summary: Validate an Apple Pay merchant session value: company_id: 1024 country_id: 233 apple_session_url: >- https://apple-pay-gateway.apple.com/paymentservices/startSession responses: '200': description: Merchant session content: application/json: schema: $ref: '#/components/schemas/ApplePaySessionResponse' examples: session: summary: Apple Pay merchant session value: apple_pay: >- {"epochTimestamp":1700000000000,"merchantSessionIdentifier":"SSH1234"} meta: request_id: 018f2c1a-8b3a-7e6d-9f10-2a3b4c5d6e7f timestamp: '2026-04-01T12:00:00Z' '404': description: Company, country, or cart not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '410': description: Cart already processed content: application/json: schema: $ref: '#/components/schemas/ProcessedCartResponse' '422': description: >- Invalid parameters, missing referer, unverified domain, misconfigured Apple Pay, or Apple session failure content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorResponse' - $ref: '#/components/schemas/ApplePayFailureResponse' security: [] components: schemas: ApplePaySessionResponse: description: >- Success body for Apple Pay merchant validation. apple_pay is Apple's raw startSession response body as a JSON-encoded string. type: object additionalProperties: false required: - apple_pay - meta properties: apple_pay: type: string description: >- Apple's raw `startSession` response body, passed through as a JSON-encoded string for the browser to hand to the Apple Pay session. 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' ApplePayFailureResponse: description: >- Discriminated Apple Pay session failure (422). error_code is the machine-readable discriminator; error_message is customer-facing copy. type: object additionalProperties: false required: - error_code - error_message - errors - meta properties: error_code: type: string description: >- Machine-readable discriminator for the Apple Pay failure, used to branch on the specific cause. error_message: type: string description: Customer-facing copy describing the Apple Pay failure. errors: $ref: '#/components/schemas/ErrorBag' meta: $ref: '#/components/schemas/Meta' 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' ````