# Bayar Partner API
> Partner-facing REST API for the Bayar payment orchestrator. These are the endpoints the Partner Dashboard consumes, authenticated with a partner API key. This spec is hand-authored to describe the existing handlers in `internal/api` and `cmd/bayar/serve.go`; keep it in sync when those change.
Version: 1.0.0
Base URL: https://api.beever.xyz/v1 — Production, https://sandbox.beever.xyz/v1 — Sandbox — simulated PSPs, no real money, /v1 — Relative, for a client that reaches Bayar through its own reverse proxy (this is how the Partner Dashboard's BFF addresses it).
Authentication: partner API key (see the Authentication note below).

## Contract
- [OpenAPI (YAML)](https://docs.beever.xyz/openapi.yaml): the machine-readable source of truth
- [OpenAPI (JSON)](https://docs.beever.xyz/openapi.json): same contract, JSON encoding
- [Full reference as text](https://docs.beever.xyz/llms-full.txt): every endpoint in one fetch

## Reference
- [Account](https://docs.beever.xyz/account.md): The authenticated partner: who the calling key belongs to, and the account-level settings that shape every other response.
- [Payments](https://docs.beever.xyz/payments.md): Create, list, and inspect collections and payouts.
- [Balances](https://docs.beever.xyz/balances.md): Per-currency held/reserved/available balances.
- [Settlements](https://docs.beever.xyz/settlements.md): Payout settlements (a filtered view of payments).
- [Beneficiaries](https://docs.beever.xyz/beneficiaries.md): Payout destinations (bank accounts, wallets, cards, and similar).
- [Disputes](https://docs.beever.xyz/disputes.md): Chargebacks, returns, inquiries, and retrievals against payments.

## Notes
- Every mutating request accepts an `Idempotency-Key` header; reusing a key replays the original response.
- Money is always an integer in the currency's minor unit, paired with its ISO-4217 code. Never a float.
- There is no CORS policy: the API is not callable from a browser. Call it server-side.