Float revenue payouts API and webhook

Float revenue payouts API and webhook

Balances held with Accrue earn float revenue, paid each period. Two read-only endpoints now report those payouts, and a webhook topic fires when one is paid, so there is no need to poll.

Endpoint	Returns
GET /api/v1/yield-payouts	One page of paid payouts, most recent period first. Paged, and filterable on the period with filter[periodFrom] and filter[periodTo]
GET /api/v1/yield-payouts/{yieldPayoutId}	One payout with its per-account breakdown and the rates that applied

The new YieldPayoutCreated topic carries yieldPayoutId, amount in cents, currency, periodStart, periodEnd, and paidAt — enough to record a payout without re-reading the API. Subscribe to it like any other topic when creating or updating a webhook.

Payouts appear once they are paid

A payout is not addressable before it settles, so there is nothing to reconcile against a period that has closed but not yet paid. YieldPayoutCreated fires at the moment a payout becomes retrievable, which makes it the signal to act on rather than a schedule.

Periods are contiguous and never overlap — the next payout starts the day after the previous one ended. The most recent periodEnd reconciled is therefore a complete watermark, with no earlier gap to backfill.

Simulate a payout before a real one exists

POST /api/v1/simulation/yield-payouts simulates the interest deposit that produces a payout, in development, sandbox, and local environments. Everything after the deposit is the real pipeline — it is recorded, split across your accounts, and paid, then YieldPayoutCreated fires and the payout becomes retrievable. Nothing about the resulting payout is synthetic.

Pass an amount in cents. That is the deposit, not the payout: the payout is your contractual share of it, so it will be smaller. The request returns 204 and the payout appears asynchronously, so wait for the webhook rather than reading straight afterwards.

The breakdown attributes revenue per counterparty

The detail endpoint returns a breakdown array with one line per counterparty that held a balance during the period, each carrying dayCount, averageDailyBalance, and the amount it earned. Lines use the same counterpartyId the counterparties API returns, so a breakdown joins directly to counterparty records. A period in which no counterparty held a balance returns an empty array and an amount of zero.

Line amounts always sum exactly to the payout amount. Use that as the reconciliation check.

Notes

• averageDailyBalance is an integer number of cents sent as a decimal string, because an average balance can exceed the range the integer fields use. Parse it with an arbitrary-precision integer type, not a float.
• rateSegments records the rates applied across the period. When it holds more than one entry the reference rate changed mid-period, and a line cannot be recomputed from averageDailyBalance alone — the line amount is authoritative.
• A line can sit a cent away from an independent recomputation: the payout total is rounded once and apportioned across lines, which is what makes the lines sum exactly.
• An unknown payout id, an id belonging to another merchant, and a payout not yet paid all return 404 YieldPayoutNotFound.