Feddi Partner API

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.

New here? Start with the Quickstart, then walk the Make your first payment flow end to end.

Base URL and authentication

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

# 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 for the full credential model and key lifecycle.

curl https://api.dev.feddi.io/v1/partner/capabilities \
  -H "x-api-key: fddi_odo_YOUR_KEY"

Sandbox access is granted per partner agreement. Request sandbox credentials from your Feddi contact.

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.

{
  "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"
  }
}

{
  "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"
  }
}

For the full envelope reference, money model, idempotency, and pagination rules, see Conventions. For every error code with its HTTP status and recovery action, see Errors.

Discover what your integration can do

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

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.

Read GET /openapi

Serves the current OpenAPI 3.1 contract. Validate your request bodies against this document rather than relying on generated types.

Two money classes

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

Actual

Real, spendable balance the customer topped up. Reported in minor units with an explicit currency.

Promotional

Cashback and reload bonuses. Locked or released, expirable, clawback-able, and spent before actual balance. See Money: actual vs promotional.

Where to go next

Quickstart

Make your first authenticated call.

Make your first payment

Identify a customer and debit their wallet, end to end.

Build with an AI agent

Point your AI coding agent at the runtime contract.

Authentication

The two-credential model and key lifecycle.

Conventions

Envelope, money, idempotency, versioning, pagination.

API Reference

Error codes, recovery, and the endpoint reference.

Get started

Core concepts

Guides

Base URL and authentication

The response envelope

Discover what your integration can do

Two money classes

Actual

Promotional

Where to go next

Quickstart

Make your first payment

Build with an AI agent

Authentication

Conventions

API Reference

​Base URL and authentication

​The response envelope

​Discover what your integration can do

​Two money classes

Actual

Promotional

​Where to go next

Quickstart

Make your first payment

Build with an AI agent

Authentication

Conventions

API Reference

Base URL and authentication

The response envelope

Discover what your integration can do

Two money classes

Where to go next