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

# Credit/refund a transaction

> Refunds or credits a prior transaction. Send `amount_cents` for a partial
refund; omit it to refund the full amount. Partial refunds accumulate in the
source transaction's `credited_amount_cents`. Creates a `refund`/
`general_credit` transaction linked via `parent_transaction_id` and returns it
with `201`. Pass an `Idempotency-Key` header to make retries safe. Returns
`404` when the transaction is not found, `409` on an in-flight duplicate key,
and `422` when the requested amount exceeds the refundable balance or the
transaction cannot be refunded.




## OpenAPI

````yaml /api-reference/payment-v2026-04.yaml post /api/payment/v2026-04/transactions/{id}/credit
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/transactions/{id}/credit:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Transaction slug (transaction to refund)
    post:
      tags:
        - Transactions
      summary: Credit/refund a transaction
      description: >
        Refunds or credits a prior transaction. Send `amount_cents` for a
        partial

        refund; omit it to refund the full amount. Partial refunds accumulate in
        the

        source transaction's `credited_amount_cents`. Creates a `refund`/

        `general_credit` transaction linked via `parent_transaction_id` and
        returns it

        with `201`. Pass an `Idempotency-Key` header to make retries safe.
        Returns

        `404` when the transaction is not found, `409` on an in-flight duplicate
        key,

        and `422` when the requested amount exceeds the refundable balance or
        the

        transaction cannot be refunded.
      operationId: creditTransaction
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                transaction:
                  type: object
                  additionalProperties: false
                  properties:
                    amount_cents:
                      type: integer
                      minimum: 1
                      description: >-
                        Partial refund amount (defaults to full transaction
                        amount)
                    metadata:
                      type: object
                      additionalProperties:
                        $ref: '#/components/schemas/JsonValue'
            examples:
              full_refund:
                summary: Refund the full transaction amount
                value: {}
              partial_refund:
                summary: Partial refund of $10.00
                value:
                  transaction:
                    amount_cents: 1000
      responses:
        '201':
          description: Credit created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDataResponse'
          headers:
            X-Idempotent-Replayed:
              description: >-
                Present and `true` when this response is a cached replay of an
                earlier request with the same Idempotency-Key.
              schema:
                type: string
                enum:
                  - 'true'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Optional client-generated key (UUID recommended) used to deduplicate
        retries. The first request with a given key executes normally; a retry
        with the same key replays that first response with
        `X-Idempotent-Replayed: true` for up to 24 hours. A concurrent retry
        while the first request is still in flight returns 409.

        The response cache is keyed on the authenticated merchant and this key
        ONLY — not on the operation, path, or request body. Use a fresh, unique
        key per logical request: reusing one key across different operations
        (for example a purchase and then a capture) replays the first
        operation's cached status and body instead of performing the second.
      schema:
        type: string
        maxLength: 255
  schemas:
    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'
    TransactionDataResponse:
      type: object
      required:
        - data
        - meta
      properties:
        data:
          $ref: '#/components/schemas/Transaction'
        meta:
          $ref: '#/components/schemas/Meta'
    Transaction:
      type: object
      required:
        - id
        - action
        - status
        - amount_cents
        - currency_code
        - processing_fee_cents
        - credited_amount_cents
        - retain_on_success
        - metadata
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: >
            Transaction slug identifier — the stable string used to address this

            transaction on `/transactions/{id}` and its lifecycle sub-routes
            (capture,

            void, credit).
        gateway_id:
          type:
            - string
            - 'null'
          description: >-
            Slug of the gateway that processed the transaction; `null` when not
            applicable.
        payment_method_id:
          type:
            - string
            - 'null'
          description: >-
            UUID (v7) of the vaulted card used; `null` when no card is
            associated.
        card_network:
          type:
            - string
            - 'null'
          description: >
            Canonical card network brand for the transaction. Resolved from the
            vaulted

            card record, the gateway success response, or the gateway decline
            response,

            in that order, then normalized via
            `Payments::CardBrand.canonicalize`.

            Common values: `visa`, `mastercard`, `american_express`, `discover`,
            `jcb`.

            Not an enum — unmapped brands pass through as-is (e.g. `unknown`,
            `link`).

            `null` when no brand source is available.
        parent_transaction_id:
          type:
            - string
            - 'null'
          description: >
            Slug of the originating transaction when this row is a capture,
            void, or

            credit/refund; `null` for the initial purchase or authorization.
        action:
          type: string
          enum:
            - purchase
            - authorize
            - capture
            - void
            - refund
            - verify
            - general_credit
          description: >
            Operation this transaction represents. `purchase` and `authorize`
            are

            initiated on a gateway; `capture`, `void`, `refund`, and
            `general_credit`

            act against a prior transaction; `verify` is a $0 payment-method
            check.
        status:
          type: string
          enum:
            - success
            - declined
            - error
            - pending
          description: >
            Outcome of the transaction: `success`, `declined` (rejected by the

            provider), `error` (processing failure), or `pending` (awaiting a
            final

            result from the provider).
        amount_cents:
          type:
            - integer
            - 'null'
          description: >
            Transaction amount in the smallest currency unit (cents); `null`
            when not

            applicable, such as a $0 verification.
        currency_code:
          type: string
          description: ISO 4217 currency code
        payment_source:
          type:
            - string
            - 'null'
          description: Integration class (e.g. CreditCard, PayPal)
        gateway_transaction_id:
          type:
            - string
            - 'null'
          description: >
            Identifier assigned by the payment provider for this transaction;
            `null`

            until the provider responds.
        reference_token:
          type:
            - string
            - 'null'
          description: Merchant reference token
        description:
          type:
            - string
            - 'null'
          description: Optional free-text description carried on the transaction.
        processing_fee_cents:
          type: integer
          description: Processing fee in cents
        platform_fee_cents:
          type: integer
          description: Fluid platform fee in cents
        credited_amount_cents:
          type: integer
          description: >
            Cumulative amount (in cents) refunded or credited against this
            transaction;

            partial refunds accumulate here.
        retain_on_success:
          type: boolean
          description: >
            Whether the payment method used was retained for future reuse when
            the

            transaction succeeded.
        metadata:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          description: >-
            Arbitrary merchant key/value pairs stored on and echoed back with
            the transaction.
        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 transaction (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'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: |
        A request with the same Idempotency-Key is already being processed.
        Retry once the in-flight request completes; the cached response then
        replays with `X-Idempotent-Replayed: true`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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

````