Build with an AI Agent

A checklist for the agent doing the integration

If you are an AI coding agent wiring a point-of-sale platform, payment gateway, or commerce platform to Feddi, read this before you generate integration code. It is a short set of disciplines that keep a generated client correct against a live, tenant-scoped API. The Feddi Partner API is REST over JSON. The base URL is https://api.feddi.io/v1/partner for production and https://api.dev.feddi.io/v1/partner for dev. Every path in this guide is relative to that base.

Do not assume any enum, currency, credential type, or feature flag from prose. Read GET /capabilities and GET /openapi for the live, tenant-scoped set. A wrong guess on a money path is worse than a question.

Read the live contract first

Your highest-value first action is to read what is enabled for the integration the API key authenticates as. Two endpoints are the runtime source of truth, and both are stable.

Read GET /capabilities for the tenant-scoped enabled set

Returns api_version, provider, supported_currencies, supported_identify_credential_types (credential types accepted to resolve who a customer is), supported_payment_credential_types (credential types accepted to authorize a wallet debit), a features map, and rate_limits. This is tenant-specific. Never hardcode a currency, a credential_type, or a feature flag. An empty collection means the feature is not provisioned for this integration, so branch on the response, not on a hardcoded list.

Read GET /openapi for the served contract

Returns the current OpenAPI 3.1 document. This is the contract a generated client validates against. Where this guide and the served spec disagree, the spec wins.

A capability descriptor that you cache should honor its Cache-Control header. Re-fetch it when you receive a CREDENTIAL_TYPE_UNSUPPORTED or CURRENCY_NOT_SUPPORTED typed error.

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

{
  "ok": true,
  "data": {
    "api_version": "2026-06-01",
    "integration_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "provider": "POS_PROVIDER",
    "supported_currencies": ["QAR", "SAR"],
    "supported_identify_credential_types": ["phone", "qr", "short_code"],
    "supported_payment_credential_types": ["otp", "qr"],
    "features": { "identify": true, "checkout": true, "topup": false },
    "rate_limits": {
      "identify": { "per_minute": 120 },
      "payments": { "per_minute": 60 }
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_a1b2c3",
    "idempotency_replayed": false,
    "api_version": "2026-06-01"
  }
}

Validate generated code against the served spec

Generated TypeScript types are a convenience, not the contract. The contract is the document served at GET /openapi. Validate your generated client and your request bodies against that document, not against a hand-written type.

Fetch the served spec

GET /openapi returns the current OpenAPI 3.1 document for the mounted surface. It is unauthenticated, so SDK generators and contract tests can bootstrap without a key.

Validate every request body against its schema

The envelope, the credential discriminated unions, and the money fields all have schemas. Validate against them. Money is always a minor-units integer paired with an explicit ISO-4217 currency (for example amount_minor: 3500, currency: QAR), never a float.

Reconcile drift toward the spec

If your types and the served document disagree, regenerate from the served document. The spec is the source of truth.

Authenticate, then exchange for a terminal token

You authenticate with the x-api-key header. For hot-path calls (identity and money), exchange the API key for a short-lived POS terminal JWT and present it as a bearer token.

Exchange the API key for a terminal JWT

POST /auth/token with your x-api-key returns a bearer JWT scoped to the terminal (token_type: Bearer, expires_in: 600). The token carries scope claims derived from the key. It is never a debit token and never carries customer PII.

Refresh before the TTL expires

The JWT has a 600-second TTL. Call GET /auth/token/validate to read remaining_seconds and refresh before starting a checkout, so you avoid a mid-transaction 401. A malformed or expired token returns HTTP 200 with valid: false, not a 401: it is a freshness check, not an auth gate.

Sandbox access is granted per partner agreement. Request sandbox credentials from your Feddi contact. Sandbox keys run against mock providers and never touch production money or PII, so you can exercise every money path while you build.

Send the canonical envelope on every mutating call

Every mutating call carries a meta block and a context block. Every response is the envelope ok, data, error, meta. Errors are typed string codes in error.code, never a bare HTTP number. Idempotency is the Idempotency-Key HTTP header, and only that.

{
  "meta": {
    "partner_request_id": "bb22ccdd-1111-2222-3333-444455556666",
    "occurred_at": "2026-06-05T09:05:00Z",
    "sent_at": "2026-06-05T09:05:01Z",
    "api_version": "2026-06-01"
  },
  "context": {
    "merchant_id": "11111111-2222-3333-4444-555566667777",
    "branch_id": "22222222-3333-4444-5555-666677778888",
    "terminal_id": "POS-360-0007",
    "cashier_id": "cashier-42",
    "partner_session_id": "pos-txn-90021",
    "feddi_session_id": "9a7c1e10-0001-4a2b-bb33-aa44cc55dd66"
  }
}

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "request_id": "req_8f31a2",
    "idempotency_replayed": false,
    "api_version": "2026-06-01",
    "data_completeness_score": 80,
    "decision_trace_id": "dt_a91c"
  }
}

required

A partner-generated UUID, one per logical mutating operation (24h TTL). Same key plus the same payload replays the original byte-identical response with meta.idempotency_replayed: true. Same key plus a different payload returns IDEMPOTENCY_KEY_REUSED. meta.partner_request_id is your correlation id, not the deduplication basis.

required

The resolved Feddi tenant. Key-enforced: a merchant_id outside the credential’s authority is rejected, never honored. It is not a free-text trust field.

required

Your own correlation id, echoed in logs and responses. Not the idempotency basis.

An opaque integer Feddi may use internally. No action required.

An opaque correlation id. Persist it and echo it where a call accepts one.

See Conventions and Idempotency & Errors for the full envelope and replay rules.

Handle every typed error code

Branch on error.code, the typed string enum, never the HTTP status. Some codes echo the valid set in error.details so you can present or reconcile the accepted values.

{
  "ok": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Wallet balance is insufficient for this payment.",
    "details": {
      "shortfall_minor": 1200,
      "available_actual_minor": 1800,
      "available_promo_minor": 500,
      "currency": "QAR"
    }
  },
  "meta": {
    "request_id": "req_p2",
    "idempotency_replayed": false,
    "api_version": "2026-06-01"
  }
}

{
  "ok": false,
  "data": null,
  "error": {
    "code": "CREDENTIAL_TYPE_UNSUPPORTED",
    "message": "Credential type 'card_fingerprint' is not enabled for this integration.",
    "details": {
      "requested": "card_fingerprint",
      "supported": ["phone", "provider_customer_id", "short_code"]
    }
  },
  "meta": {
    "request_id": "req_cs_id_unsup",
    "idempotency_replayed": false,
    "api_version": "2026-06-01"
  }
}

The error.code enum your client must handle:

INSUFFICIENT_FUNDS (HTTP 402): the wallet balance is less than amount_minor. The credential is not consumed, so a retry is valid after a top-up. Route this to recovery, never a dead end.
WALLET_PROGRAM_AMBIGUOUS (HTTP 422): the identity matches more than one active wallet program. details.candidates lists the wallet_program_id values so you can present a disambiguator.
CREDENTIAL_TYPE_UNSUPPORTED (HTTP 422): the credential is not enabled for this integration. details.supported lists the accepted set. Re-read GET /capabilities.
REQUIRES_DYNAMIC_CREDENTIAL: a money call needs a fresh dynamic credential (OTP or QR), not a static identifier.
IDEMPOTENCY_KEY_REUSED (HTTP 422): the same Idempotency-Key was presented with a different payload.
CURRENCY_NOT_SUPPORTED: the currency is not provisioned for this integration. details lists the supported ISO-4217 codes.
INVALID_API_KEY (HTTP 401), FORBIDDEN (HTTP 403), NOT_FOUND (HTTP 404), VALIDATION_ERROR (HTTP 400), RATE_LIMITED (HTTP 429), CONFLICT, INTERNAL_SERVER_ERROR.

We recommend handling INSUFFICIENT_FUNDS explicitly on every money path. The customer can top up and the same payment retries. Confirm a top-up against a provider settlement reference with POST /topup/confirm, then re-issue the payment.

See Errors for the full code table with status and recovery for each.

Identity and money are separate

An identity call resolves a credential to a customer context and returns balance state. It never returns a debit token, an authorization token, or any artifact that permits a ledger mutation. To charge a wallet, you make a separate payment call with a fresh dynamic credential.

Identify the customer

POST /identify resolves a credential and returns a resolution_state of registered, pending_proof, or not_found. The not_found state is HTTP 200 with a null balance, not a 404, so a polling UI can tell ‘no wallet’ from a server error. Read GET /capabilities for the enabled supported_identify_credential_types before you send one.

Charge the wallet

POST /payments debits the wallet for amount_minor in currency, promo balance first, then actual balance. The result carries debited_promo_minor and debited_actual_minor so the two are always reconcilable, plus the full balance_after.

A customer’s balance is scoped per merchant. Promotional money is a separate, expiring, non-cashable class distinct from the actual balance; the two are never merged. See Money: actual vs promotional and Identity & credentials.

Where to go next

Make your first payment

The callable identify, pay, recover loop worked end to end.

Authentication

The API-key lifecycle and the terminal JWT exchange.

Conventions

The response envelope, money-as-minor-integers, idempotency, versioning, and pagination.

Errors

Every typed code, its HTTP status, and its recovery action.

Get started

Core concepts

Guides

A checklist for the agent doing the integration

Read the live contract first

Validate generated code against the served spec

Authenticate, then exchange for a terminal token

Send the canonical envelope on every mutating call

Handle every typed error code

Identity and money are separate

Where to go next

Make your first payment

Authentication

Conventions

Errors

​A checklist for the agent doing the integration

​Read the live contract first

​Validate generated code against the served spec

​Authenticate, then exchange for a terminal token

​Send the canonical envelope on every mutating call

​Handle every typed error code

​Identity and money are separate

​Where to go next

Make your first payment

Authentication

Conventions

Errors

A checklist for the agent doing the integration

Read the live contract first

Validate generated code against the served spec

Authenticate, then exchange for a terminal token

Send the canonical envelope on every mutating call

Handle every typed error code

Identity and money are separate

Where to go next