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

# Feddi Partner API

> Accept and reconcile closed-loop wallet payments and loyalty at the point of sale. REST, JSON, and a typed response envelope on every call.

The Feddi Partner API lets your point-of-sale platform identify customers, read wallet balances, accept closed-loop wallet payments, run top-ups, and reconcile transactions at checkout.

It is a REST API with JSON request and response bodies, predictable resource URLs, and a typed response envelope on every call. All amounts are integer minor units paired with an explicit ISO-4217 currency. Balances are merchant-held and closed-loop.

<Tip>
  New here? Start with the [Quickstart](/getting-started/quickstart), then walk the [Make your first payment](/getting-started/make-your-first-payment) flow end to end.
</Tip>

## Base URL and authentication

Every endpoint is mounted under a versioned base URL. Use the dev base URL while building.

```bash theme={null}
# Production
https://api.feddi.io/v1/partner

# Dev
https://api.dev.feddi.io/v1/partner
```

Authenticate with your integration key in the `x-api-key` header. For hot-path calls (identity and money), exchange the key for a short-lived POS terminal JWT and present it as a bearer token. See [Authentication](/api-reference/authentication) for the full credential model and key lifecycle.

```bash theme={null}
curl https://api.dev.feddi.io/v1/partner/capabilities \
  -H "x-api-key: fddi_odo_YOUR_KEY"
```

<Info>
  Sandbox access is granted per partner agreement. Request sandbox credentials from your Feddi contact.
</Info>

## The response envelope

Every response, success or error, uses the same envelope: `ok`, `data`, `error`, and `meta`. Error codes are strings (for example `INSUFFICIENT_FUNDS`), never a bare HTTP status number. Branch on `error.code`, not on the HTTP status.

<CodeGroup>
  ```json 200 OK theme={null}
  {
    "ok": true,
    "data": {
      "api_version": "2026-06-01",
      "supported_currencies": ["QAR", "SAR"],
      "supported_identify_credential_types": ["phone", "qr", "short_code"],
      "supported_payment_credential_types": ["otp", "qr"]
    },
    "error": null,
    "meta": {
      "request_id": "req_a1b2c3",
      "idempotency_replayed": false,
      "api_version": "2026-06-01"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "ok": false,
    "data": null,
    "error": {
      "code": "INVALID_API_KEY",
      "message": "Missing or invalid x-api-key."
    },
    "meta": {
      "request_id": "req_a1b2c4",
      "api_version": "2026-06-01"
    }
  }
  ```
</CodeGroup>

For the full envelope reference, money model, idempotency, and pagination rules, see [Conventions](/api-reference/conventions). For every error code with its HTTP status and recovery action, see [Errors](/api-reference/errors).

## Discover what your integration can do

Two endpoints describe your integration at runtime. Read them before you assume any enum, currency, or feature.

<Steps>
  <Step title="Read GET /capabilities">
    Returns the credential types, currencies, and features enabled for your `x-api-key`. Empty collections mean a feature is not provisioned for your integration, not that it is unsupported globally.
  </Step>

  <Step title="Read GET /openapi">
    Serves the current OpenAPI 3.1 contract. Validate your request bodies against this document rather than relying on generated types.
  </Step>
</Steps>

## Two money classes

Balances carry two distinct classes of value. Keep them separate in your UI and your reconciliation.

<Columns cols="2">
  <Card title="Actual" icon="wallet" horizontal="false">
    Real, spendable balance the customer topped up. Reported in minor units with an explicit currency.
  </Card>

  <Card title="Promotional" icon="gift" horizontal="false">
    Cashback and reload bonuses. Locked or released, expirable, clawback-able, and spent before actual balance. See [Money: actual vs promotional](/concepts/money-classes).
  </Card>
</Columns>

## Where to go next

<Columns cols="3">
  <Card title="Quickstart" href="/getting-started/quickstart" icon="zap" horizontal="false">
    Make your first authenticated call.
  </Card>

  <Card title="Make your first payment" href="/getting-started/make-your-first-payment" icon="credit-card" horizontal="false">
    Identify a customer and debit their wallet, end to end.
  </Card>

  <Card title="Build with an AI agent" href="/getting-started/build-with-an-agent" icon="bot" horizontal="false">
    Point your AI coding agent at the runtime contract.
  </Card>

  <Card title="Authentication" href="/api-reference/authentication" icon="key" horizontal="false">
    The two-credential model and key lifecycle.
  </Card>

  <Card title="Conventions" href="/api-reference/conventions" icon="book-open" horizontal="false">
    Envelope, money, idempotency, versioning, pagination.
  </Card>

  <Card title="API Reference" href="/api-reference/errors" icon="code" horizontal="false">
    Error codes, recovery, and the endpoint reference.
  </Card>
</Columns>