Merchant settlement statements

OpenAPI 0.13 adds GET /v1/settlements, GET /v1/settlements/{id} and GET /v1/settlements/{id}/statement?format=pdf|csv. These require settlements:read; existing keys retain their scopes. Owner/Admin can issue a new settlement-read key. A settlement-only key cannot read payments or perform financial actions. Lists accept optional currency=USD|CDF and a merchant-owned UUID cursor, with 25 items and next_cursor.

Portal equivalents use /portal/merchants/{merchant}/settlements, merchant OIDC identity and X-Futa-Membership-Version. Owner, Admin and Finance may read; Support and Developer may not. Live role/version and shared quota checks apply. No response exposes other merchants, batch-wide instructions, sponsor evidence or staff identities.

New proposals atomically capture an immutable merchant breakdown. It uses a cumulative basis at proposal, not per-payment allocation: eligible gross credits minus all confirmed refunds, previous settlements, zero test fees and other unavailable funds equals this batch’s net. Unavailable funds include pending refunds, holds and reserved settlements. The original instruction controls the net; a changed funding calculation aborts proposal creation. Later state changes or ledger entries do not rewrite the breakdown.

All monetary JSON values are decimal strings in minor units; 100 represents 1 USD or 1 CDF. Do not convert cumulative totals to a JavaScript Number. snapshot_available=false identifies old batches that predate capture; their original net/destination/state remains readable, their breakdown fields are null, and statement download returns 409 STATEMENT_UNAVAILABLE.

PDF and CSV downloads are private and no-store. CSV is a single merchant breakdown row with exact minor-unit text and quoted, formula-neutralized cells, not a fabricated transaction allocation. PDF displays decimal currency amounts and the batch state at download time. Only COMPLETED confirms synthetic settlement; proposed, processing, uncertain and failed are not transfer confirmations. No document proves a real transfer. Synthetic zero fees/accounts are not commercial pricing or verified settlement accounts.