# 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 checkout takes MAJOR units (`"totalAmount": 49.99`) while its
  payouts take `amountMinor`. 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`.
- **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 the raw body>` plus
  `X-Fynex-Timestamp`). 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 read-oriented.** Contracts, invoices, subscriptions and
  credit grants are created in the dashboard, not through the API. Metering is
  the exception and is fully writable. Do not invent a `POST /invoices` — ask
  the user.
- **`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](/api-reference) — 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. The sandbox is `https://staging-api.fynex.ai`, with
the same paths. What decides whether money is real is the ACCOUNT's mode, not
the host: a demo account behaves as a sandbox on either.