> ## 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 <token>; 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.

# Create a gateway

> Creates a new payment gateway for the authenticated merchant from the
`gateway` payload. Returns `201` with the created gateway. `credentials` are
write-only and never returned. Returns `422` when required fields are missing
or `integration_type`/`mode` is invalid.




## OpenAPI

````yaml /api-reference/payment-v2026-04.yaml post /api/payment/v2026-04/gateways
openapi: 3.1.0
info:
  title: Fluid Payment API
  version: v2026-04
  description: >-
    Payment gateway and transaction management API. Supports API key
    authentication (fp_live_*/fp_test_*) and JWT bearer tokens.
  contact:
    email: support@fluid.app
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.fluid.app
security:
  - bearer_auth: []
tags:
  - name: Gateways
    description: >-
      Manage payment gateways and run gateway-level transactions — purchase,
      authorize, and $0 verification.
  - name: Transactions
    description: >-
      Read transactions and run transaction lifecycle operations — capture,
      void, and credit/refund.
  - name: Merchant Configuration
    description: >-
      Root-admin-only access to a merchant's VGS, Kount, 3DS acquirer, payout,
      and platform-fee settings.
paths:
  /api/payment/v2026-04/gateways:
    post:
      tags:
        - Gateways
      summary: Create a gateway
      description: >
        Creates a new payment gateway for the authenticated merchant from the

        `gateway` payload. Returns `201` with the created gateway. `credentials`
        are

        write-only and never returned. Returns `422` when required fields are
        missing

        or `integration_type`/`mode` is invalid.
      operationId: createGateway
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - gateway
              properties:
                gateway:
                  $ref: '#/components/schemas/GatewayCreateRequest'
            examples:
              stripe:
                summary: Create a Stripe credit-card gateway
                value:
                  gateway:
                    name: Stripe (USD)
                    integration_type: CreditCard
                    mode: live
                    country_codes:
                      - US
      responses:
        '201':
          description: Gateway created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayDataResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    GatewayCreateRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - integration_type
      properties:
        name:
          type: string
          description: Display name for the new gateway.
        integration_type:
          type: string
          description: >
            Integration class for the gateway (e.g. `CreditCard`, `PayPal`);
            selects the

            provider adapter.
        mode:
          type: string
          enum:
            - live
            - test
            - sandbox
          description: |
            Environment the gateway runs in: `live`, `test`, or `sandbox`.
        credentials:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          description: >
            Provider credentials (API keys, secrets) for the gateway. Write-only
            —

            obfuscated or omitted on read.
        country_codes:
          type: array
          items:
            type: string
          description: ISO 3166-1 alpha-2 country codes the gateway should be enabled for.
        settings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          description: >-
            Provider-specific configuration key/values; shape varies by
            `integration_type`.
    GatewayDataResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/Gateway'
        meta:
          $ref: '#/components/schemas/Meta'
    JsonValue:
      description: >-
        Any valid JSON value for provider, integration, theme, metadata, or
        other dynamic payloads 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'
    Gateway:
      type: object
      required:
        - id
        - name
        - integration_type
        - mode
        - supported_sources
        - country_codes
        - settings
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: >
            Gateway slug identifier — the stable string used to address this
            gateway

            on `/gateways/{id}` and its transaction sub-routes.
        name:
          type: string
          description: Human-readable display name for the gateway.
        integration_type:
          type: string
          description: >
            Integration class backing the gateway (e.g. `CreditCard`, `PayPal`).
            Selects

            the provider adapter and the credential set used to process
            transactions.
        mode:
          type: string
          enum:
            - live
            - test
            - sandbox
          description: >
            Environment the gateway operates in. `live` moves real funds; `test`
            and

            `sandbox` route to the provider's non-production environment.
        supported_sources:
          type: array
          items:
            type: string
          description: >-
            Card brands / payment sources the gateway accepts (e.g. `visa`,
            `mastercard`).
        country_codes:
          type: array
          items:
            type: string
          description: ISO 3166-1 alpha-2 country codes the gateway is enabled for.
        settings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          description: >
            Provider-specific configuration key/values for the gateway. The
            shape varies

            by `integration_type`; secret values are obfuscated on read.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the last update to the gateway (ISO 8601).
    Meta:
      type: object
      required:
        - request_id
        - timestamp
      properties:
        request_id:
          type:
            - string
            - 'null'
          description: |
            Unique identifier for this request, echoed on every response for log
            correlation and support; `null` when none was assigned.
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp (UTC) of when the response was generated.
    UnauthorizedResponse:
      type: object
      required:
        - message
        - meta
      properties:
        message:
          type: string
          description: Human-readable reason the credentials were rejected.
        status:
          type: string
          description: Error status string, when present.
        meta:
          $ref: '#/components/schemas/Meta'
    ForbiddenResponse:
      description: |
        Authenticated but not authorized. Two body shapes occur:
        - a bare `message` when the credential lacks the required role/tier
          (e.g. a non-admin JWT calling an admin endpoint)
        - a `status` + `message` envelope from payment API endpoint gates
      anyOf:
        - type: object
          required:
            - message
            - meta
          properties:
            message:
              type: string
            meta:
              $ref: '#/components/schemas/Meta'
        - type: object
          required:
            - status
            - message
            - meta
          properties:
            status:
              type: string
              enum:
                - error
            message:
              type: string
            meta:
              $ref: '#/components/schemas/Meta'
    ErrorResponse:
      oneOf:
        - type: object
          required:
            - status
            - message
            - meta
          properties:
            status:
              type: string
              enum:
                - error
              description: Always `error` for this envelope.
            message:
              type: string
              description: Human-readable description of what went wrong.
            meta:
              $ref: '#/components/schemas/Meta'
        - type: object
          required:
            - error_message
            - errors
            - meta
          properties:
            error_message:
              type: string
              description: Human-readable summary of the failure.
            errors:
              $ref: '#/components/schemas/ErrorBag'
            meta:
              $ref: '#/components/schemas/Meta'
    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'
    ErrorValue:
      description: A validation or API error value.
      anyOf:
        - type: string
        - type: array
          items:
            type: string
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedResponse'
    Forbidden:
      description: Authenticated but not authorized for this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenResponse'
    UnprocessableEntity:
      description: Validation or business error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: API key (fp_live_*/fp_test_*) or JWT bearer token

````