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

# Changelog

> Contract changes to the Feddi Partner API, newest first. Each entry names the api_version it ships, the operations it adds, and any shape changes.

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

<Info>
  `GET /capabilities` and `GET /openapi` are the authoritative answer to what is mounted in your environment right now. This page records contract history; the runtime descriptors record current state.
</Info>

## 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, the supported identify and payment credential type lists (`supported_identify_credential_types` and `supported_payment_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](/api-reference/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](/concepts/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](/concepts/pending-proof).

### 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. Reserved for v2 hold and capture flows; nothing routes through it in v1.
* `POST /payments/otp/send`: trigger the OTP leg of a wallet payment. Resolves the wallet from the phone, mints an OTP session bound to the order and amount, and SMSes a 6-digit code. No money moves; the point of sale then submits the code via `POST /payments` with the `otp` credential, where verify and debit are atomic in that one call.
* `POST /qr/mint`: mint a rotating QR or short code for the customer's wallet app.

See [Payments and redemption](/guides/payments).

### 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](/guides/topup).

### 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](/guides/incentives).

### Transactions

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

See [Transactions](/guides/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](/concepts/money-classes).
* 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](/api-reference/conventions) and [Idempotency and errors](/concepts/idempotency-and-errors).

## Where to go next

<Columns cols="2">
  <Card title="API conventions" icon="book-open" href="/api-reference/conventions">
    The response envelope, money as minor units, idempotency, versioning, and pagination.
  </Card>

  <Card title="Make your first payment" icon="route" href="/getting-started/make-your-first-payment">
    A worked loop across the callable operations: identify, pay, and recover insufficient funds.
  </Card>

  <Card title="Money: actual vs promotional" icon="coins" href="/concepts/money-classes">
    The two-class money model and the promo-grant state machine.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    The two-credential model, JWT scope claims, and key lifecycle.
  </Card>
</Columns>