Skip to main content

Settlement / Cashout

Accepting payments credits your gateway balance. Settlement (also called cashout) is the opposite direction: moving that balance out to an external address as a payout. It is a separate concern from receiving payments, with its own security model.

Balance maturation​

Funds you receive do not become withdrawable instantly. Each balance has two buckets:

  • Matured / available — past the settlement waiting window; withdrawable now.
  • Maturing / pending — still inside the waiting window; not yet withdrawable.

The balances endpoint reports both per asset.

Platform-billed gateways​

Some gateways run on a platform-billed arrangement, set up per gateway by Finomesh. On these:

  • Nothing is deducted from your payments. Finomesh covers the network fee and the commission, so the full amount a customer sends is credited to your balance.
  • Those fees are billed to you separately instead of per payment, and you settle them as one invoice rather than losing a slice of every deposit.
  • Accepting payments is never affected by an unpaid invoice — you keep receiving normally.
  • Cashouts can be paused if you fall behind. If an invoice goes overdue, or your outstanding balance with us passes the limit agreed for your gateway, a new settlement is refused with 409 conflict and a message naming the amount. Paying the invoice lifts it immediately — see Cashout errors.

Your integration is otherwise identical to a standard gateway. If you are not on this arrangement, none of the above applies.

Two ways to cash out​

MethodWhereNotes
DashboardThe Cashout page in the merchant dashboardManual, always available.
Cashout APIPOST /api/v1/merchant/settlementsProgrammatic. Off by default — Finomesh enables it per gateway — and hardened with an IP allowlist + HMAC request signing.

Settlement lifecycle​

A settlement moves through REQUESTED → PROCESSING → SETTLED (terminal) or REJECTED (terminal). It is dispatched on-chain after your gateway's configured delay; you learn the terminal result by polling or via the settlement webhook.

If you set a cashout approval cap (a USD ceiling, configured per gateway in the dashboard), an API cashout above the cap starts at PENDING_APPROVAL and is held until a team member approves it — a manual sign-off step for large programmatic withdrawals. See Create Settlement → Approval cap.

Next​