Changelog

How to read this page

This page records changes to the Feddi Partner API contract, newest first. Each entry names the api_version it ships and what moved: new operations and shape changes to existing requests or responses.

Pin the meta.api_version you send. It locks the contract you build against. Call GET /capabilities and GET /openapi at runtime for the authoritative list of operations, currencies, and credential types enabled for your integration.

2026-06-01 (api_version: 2026-06-01)

First public release of the Feddi Partner API, served as a single OpenAPI 3.1 document. Operations are tagged ga (stable) or beta (callable, shapes may still tighten additively). Pin your api_version. Confirm which operations are enabled for your credentials at runtime with GET /capabilities.

Platform and discovery

• GET /health: liveness and readiness. Unauthenticated. Returns status and a degraded_subsystems array.
• GET /capabilities: the runtime operation set, supported currencies, supported credential types, and feature flags for your credentials. Read this before assuming any enum.
• GET /openapi: the live OpenAPI 3.1 contract served from the running service. Validate your request bodies against it.

Authentication

• POST /auth/keys: provision a scoped integration API key. The raw key is returned exactly once.
• GET /auth/keys: list API key metadata for the calling integration. No secrets are returned.
• POST /auth/keys/{keyId}/revoke: soft-revoke a key (status flag, preserved for audit).
• POST /auth/keys/{keyId}/regenerate: rotate a key. Revoke and reissue at the same scope; the new raw key is shown once.
• POST /auth/keys/{keyId}/delete: hard-delete a key record.
• POST /auth/token: exchange an API key for a short-lived POS terminal JWT (600-second TTL).
• GET /auth/token/validate: check a POS terminal JWT freshness and remaining TTL without making a money call.

See Authentication for the two-credential model and key lifecycle.

Identity and customers

• POST /identify: resolve a customer credential (phone, card_fingerprint, short_code, provider_customer_id, or qr) to a CustomerContext. Standalone, for cashier-panel and balance-check use. Never returns a debit token.
• POST /checkout/sessions/{id}/identify: attach an identity to an open checkout session. The session-anchored form of identify. Never returns a debit token.
• GET /customers/lookup: cashier-panel lookup returning identity, balance, recent activity, and badge. A not_found result is returned as HTTP 200.

See Identity and credentials.

Enrollment and claims

• POST /enroll/initiate: create a pending_proof wallet and send a verification link.
• POST /enroll/verify: verify phone ownership and flip pending_proof to verified, releasing locked grants atomically.
• POST /enroll/resend: resend the verification SMS. Rate-limited and attempt-capped.
• POST /claims: re-drive the claim release for a pending_proof wallet's locked promotional grants.

See PENDING_PROOF and promo release.

Payments and redemption

• POST /payments: authorize and debit a wallet payment via a credential, promo-first. OTP and QR credentials supported.
• GET /payments/{id}: read a wallet payment by id.
• POST /payments/{id}/capture: capture or close an authorized payment.
• POST /qr/mint: mint a rotating QR or short code for the customer's wallet app.

See Payments and redemption.

Top-up and reload bonus

• POST /topup/confirm: confirm a top-up against a provider settlement reference. Credits the wallet and accrues any reload bonus.
• POST /topup/sku/{skuId}: record a top-up SKU sold at the POS. Credits the wallet and accrues the SKU bonus.
• POST /topup/reload-bonus/config: set reload-bonus tiers for the merchant.

See Top-up and reload bonus.

Incentives

• GET /customers/{customerId}/grants: list a customer's promotional grants and their state-machine state.
• POST /grants/{id}/clawback: clawback a fraudulent or voided promotional grant. Operator-gated. A clawback never touches the customer's actual cash.

See Incentives.

Transactions

• GET /{integrationId}/transactions: list transactions for an integration.
• GET /{integrationId}/transactions/{transactionId}: read a single transaction's full detail.

See Transactions.

Conventions baked into the contract

• Money is two-class. Every balance separates actual money (actual_minor) from promotional credit (promo_*_minor), which is locked, expirable, clawback-able, and spent first. The two are never conflated. See Money: actual vs promotional.
• Every mutating call sends the canonical envelope (meta plus context) and an Idempotency-Key header. Every response is the typed envelope { ok, data, error, meta }. Errors are typed string codes in error.code, never a bare HTTP number. See API conventions and Idempotency and errors.

Where to go next