> ## Documentation Index
> Fetch the complete documentation index at: https://docs.feddi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Serve the CI-validated OpenAPI 3.1 contract

> Returns the current OpenAPI 3.1 specification covering all mounted `/v1/partner/*` routes. This endpoint is the self-description anchor: an integrating agent, SDK generator, or contract test validates against this spec rather than relying on generated TypeScript types. Every mounted route has a corresponding entry in the spec, so the spec stays in sync with the live surface. Unauthenticated, so tooling (Postman, Swagger UI, custom SDK generators) can bootstrap without a key.



## OpenAPI

````yaml /api-reference/openapi.yaml get /openapi
openapi: 3.1.0
info:
  title: Feddi Partner API
  version: '2026-06-01'
  description: >-
    Operate a Feddi closed-loop wallet and loyalty program at the point of sale:
    identify customers, read balances, accept wallet payments, run top-ups, and
    reconcile transactions.


    All amounts are integer minor units with an explicit ISO-4217 currency.
    Balances are merchant-held and closed-loop.


    Every response uses a typed envelope (`ok` / `data` / `error` / `meta`) with
    string error codes (never a bare HTTP number) and an idempotency-replay
    flag. Authenticate with the `x-api-key` header; exchange it for a
    short-lived POS terminal JWT for hot-path calls.


    Self-validate against this document (`GET /openapi`) and read `GET
    /capabilities` for the credential types, currencies, and features enabled
    for your integration before assuming any enum.


    Operations are tagged `x-feddi-availability: ga` (stable) or `beta`
    (callable, contract may still change additively); confirm what is enabled
    for your credentials via `GET /capabilities`.


    Sandbox access is granted per partner agreement; request credentials from
    your Feddi contact.
servers:
  - url: https://api.feddi.io/v1/partner
    description: production
  - url: https://api.dev.feddi.io/v1/partner
    description: dev
security:
  - ApiKeyAuth: []
tags:
  - name: platform
    description: >-
      Platform cross-cutting: health, capabilities, openapi self-serve, merchant
      provisioning, settlement, reconciliation.
  - name: checkout_session
    description: >-
      Checkout sessions: every interaction opens a session, then identity and
      basket attach to it, and payment, top-up, and offers run against it.
  - name: auth
    description: >-
      Partner authentication + onboarding: API key lifecycle, POS terminal JWT
      exchange, terminal heartbeat.
  - name: customers
    description: >-
      Customer lookup + identification: resolve identity, cashier-panel
      summaries, preferences, GDPR export/erase.
  - name: enrollment
    description: >-
      Enrollment + signup: OTP enroll, cashback claims, identity/consent,
      customer correction + merge.
  - name: payments
    description: >-
      Payments + redemption: debit wallet (promo-first), balance-check, void,
      refund, QR mint.
  - name: topup
    description: >-
      Wallet top-up: 2-step prepare/confirm, reload-bonus grants, SKU top-up,
      settlement + reconciliation.
  - name: incentives
    description: >-
      Incentives + offers: offer feeds, apply/redeem/release locks, proposals,
      budget envelopes, points, grant clawback.
  - name: transactions
    description: >-
      Transactions + receipts: transaction detail, void, receipts, disputes,
      settlements, reconciliation, exports.
  - name: webhooks
    description: >-
      Webhooks + events: subscriptions, delivery history + retry, event catalog,
      polling fallback.
paths:
  /openapi:
    get:
      tags:
        - platform
      summary: Serve the CI-validated OpenAPI 3.1 contract
      description: >-
        Returns the current OpenAPI 3.1 specification covering all mounted
        `/v1/partner/*` routes. This endpoint is the self-description anchor: an
        integrating agent, SDK generator, or contract test validates against
        this spec rather than relying on generated TypeScript types. Every
        mounted route has a corresponding entry in the spec, so the spec stays
        in sync with the live surface. Unauthenticated, so tooling (Postman,
        Swagger UI, custom SDK generators) can bootstrap without a key.
      operationId: getOpenApiSpec
      parameters: []
      responses:
        '200':
          description: OpenAPI 3.1 JSON document.
          content:
            application/json:
              schema:
                type: object
                description: Valid OpenAPI 3.1 document object.
      security: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Partner API key (platform- or merchant-scoped). Contract key-enforces
        context.merchant_id.

````