# Fynex APIs

> Two public REST surfaces on this host, one product and one credential.
> Payments moves money — checkout, payouts, wallets, payment links. Billing
> raises and collects the documents that say how much — contracts,
> subscriptions, metered usage, invoices, credits.

## Instructions for coding agents

Read these before writing code against either surface. Each is a mistake this
platform has actually seen.

- **The two APIs do not agree about money units.** Billing is integer minor
  units throughout — a field ending `Minor` carries `4999` for €49.99.
  Payments requests take MAJOR units — checkout `"totalAmount": 49.99`,
  payouts `"amount": "49.99"` as a decimal string (`amountMinor` there is a
  deprecated fallback). Read the field name, never the other API's habit:
  guessing here is wrong by a factor of a hundred, and neither surface will
  reject the wrong one.
- **One credential covers both.** A seller secret key issued in the Fynex
  dashboard (Integration → API keys — see [/keys](/keys)) authenticates
  Payments and Billing alike,
  as `Authorization: Bearer sk_test_…` or `sk_live_…`. There is no second
  token to obtain. The prefix says which mode the account is in; after go-live
  the test key answers `401`. Older accounts may also hold a prefix-less
  dashboard token: it authenticates Payments only, and Billing answers `401`
  to it — use the `sk_` key for both.
- **One webhook pipe.** Both surfaces deliver through the same signed pipe,
  with one endpoint registration and one signature scheme
  (`X-Fynex-Signature: sha256=<hex HMAC-SHA256 of "<X-Fynex-Timestamp>.<raw body>">`
  — the timestamp header, a literal dot, then the raw body — plus
  `X-Fynex-Timestamp`; only a `200` counts as delivered, anything else is
  retried up to 3 attempts). A body is an envelope — `eventId`, `eventType`,
  `sellerAccountUuid`, `occurredAt` — with the event's fields under `payload`.
  Deduplicate on `eventId`.
- **`Subscription*` and `BillingSubscription*` are different objects.** The
  unprefixed events describe payment-link recurring subscriptions; the
  prefixed ones describe billing subscriptions on a contract. Subscribing to
  one tells you nothing about the other.
- **Billing v1 is fully writable for its lifecycle — customers, contracts,
  subscriptions, invoices, credit top-ups — as well as metering.** The routes:
  `POST /customers`, `POST /contracts` and
  `POST /contracts/{contractId}/amendments`,
  `POST /contracts/{contractId}/subscriptions` and
  `POST /subscriptions/{subscriptionId}/{cancel|pause|resume|change-plan|end-trial}`,
  `POST /invoices` and `POST /invoices/{invoiceId}/send`,
  `POST /contracts/{contractId}/credits/top-up`, `POST /prices/evaluate`,
  `POST /contracts/{contractId}/test-clock/advance` (sandbox only — it issues
  real documents), and the metering surface under `/usage`. Exactly four calls
  require an `Idempotency-Key` header: create contract, create subscription,
  create invoice, credit top-up. Metering idempotency is the `idempotencyKey`
  field in the event body; reusing a key with a DIFFERENT payload answers `409`,
  while the same payload is a duplicate (`200`). Issued documents are
  never edited in place — a contract is amended by appending a version, an
  invoice corrected by a credit note.
- **`sellerAccountId` is the Fynex account; `sellerCustomerId` is who pays
  it; a `payee` is who it pays out to.** One marketplace operator is all three
  at once.

## Billing API — `/billing-api/v1`

- [Agent front door](/billing-api/v1/llms.txt) — start here; the facts specific
  to billing, and links to every guide as markdown
- [OpenAPI 3.1 document](/billing-api/v1/openapi.json) — operations and the
  webhook catalog; generate a client from this
- [Complete reference (markdown)](/billing-api/v1/docs.md)
- [Rendered documentation](/billing-api/v1/docs)

## Payments API — endpoints under `/payments-api/v1`, documentation under `/payments-api/v2`

- [Agent front door](/payments-api/v2/llms.txt) — start here; the facts
  specific to payments, and links to every guide as markdown
- [OpenAPI document](/payments-api/v2/openapi.json) — generate a client from
  this; every operation path in it already carries its `/payments-api/v1` base
- [Complete reference (markdown)](/payments-api/v2/docs.md)
- [Rendered documentation](/payments-api/v2/docs)

## Everything at once

- [llms-full.txt](/llms-full.txt) — this file with both complete references
  inlined, so you do not need a request per guide
- [API reference index](/) — plain HTML, no JavaScript, both
  surfaces linked
- [sitemap.xml](/sitemap.xml) — every documentation URL on this host
- [/keys](/keys) — where the credential comes from, in one page
- [Agent skills](/.well-known/skills/index.json) — task-shaped skills for
  marketplaces, splits, payouts, metering, reconciliation and migrating off
  Stripe Connect. Install with `npx skills add https://api.fynex.ai`

Both surfaces serve each guide as markdown at its own URL
(`…/docs/<guide>.md`), and answer `Accept: text/markdown` at the
extensionless URL with the same content.

## Environments

Production is this host.
What decides whether money is real is the ACCOUNT's mode, not
the host: a demo account behaves as a sandbox on either.