Settlement and daily close

The money you pay out has to be in place beforehand, under one of two models.

curl -s "$BASE/v1/treasury/position?asset=BS" -H "x-api-key: $KEY"

200 OK

{
  "tenantId": "3f1a0c22-9b41-4a77-8f0e-6d2c5b7a1e34", "asset": "BS",
  "prefundingBalance": "0", "platformRevenueFromTenant": "415900",
  "creditEnabled": true, "creditDrawn": "4537190",
  "creditLimit": null, "creditAvailable": null
}

creditEnabled tells you which of the two you are on.

	Prefunded (false)	Daily close (true)
When you put the money in	Before paying out	At the next day’s close
Cash you tie up	Enough for your worst day	None
If you fall short	422 insufficient_tenant_funds	Nothing: the payout goes out
The figure you watch	prefundingBalance	creditDrawn

The daily close is a credit line: it is enabled case by case and for an agreed amount.

The fields of your position

Field	What it is
prefundingBalance	Your available balance, in minor units. "0" is normal with daily close
creditDrawn	What you owe right now, as a positive number. It grows during the day, is settled at the close and goes back to 0
creditEnabled	true = daily close. false = prefunded
creditLimit · creditAvailable	Your line’s ceiling and what you have left. null if no ceiling was agreed
platformRevenueFromTenant	Fees your program has generated, to reconcile your invoice

If you overpay at a close, the excess stays in prefundingBalance and the next day’s payouts consume it before drawing on the line.

What goes into today’s close

By settlement, not by creation: a payout goes into the close of the day it became settled.

State at cut-off	Counts?
settled	Yes. The money went out
failed	No. The entry was already reversed: you owe nothing
submitted	No. It moves to the close of the day it settles
unknown	No. It moves to the close of the day it is resolved

A payout you send at 23:55 that settles at 00:05 shows up in tomorrow’s close.

That is why the outcome is closed by webhook

If your accounting marks the payout as paid when POST /payouts responds, your count and our close will not match: the usual response is submitted, not settled. Mark it with the payment.settled webhook. See tracking.

What you receive at the close

At the close we send you, through the channel we agree on:

• number of settled payouts and the amount delivered, in Bs;
• fees for the period;
• total to settle;
• the line-by-line detail, with id, beneficiary, bank, method, bank_reference and settled_at.

Reconciling it yourself

Request the day with GET /payments?from=…&to=…&status=settled, add up payout_amount and fee_amount as integers and compare with creditDrawn. The full loop, ready to copy: reconcile a day.

How we charge

Item	How it is calculated
Fee	Fixed + basis points on the amount, with a minimum and maximum. Configurable per program
Spread	Only when there is a conversion: a margin on the rate, in basis points. In the quote’s rate.spread_bps, with the market rate in rate.market
No conversion	No spread. Only the fee, charged on top of the exact amount you deliver

The quote breaks down the three figures: deliver what the beneficiary receives, fee the fee and spend what is debited from you. See quoting.