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.

On AML-screened gateways there is a third, separate pool — held (totalQuarantined*): deposits our screening flagged. It never counts toward available, and you withdraw from it by naming it on the cashout (route: "AML_HELD") — in exact amounts, under the same rules as the ordinary pool. Which payments are in it is visible as amlState: "HELD" on verify.

The balances endpoint reports all of these per asset.

Monthly-billed gateways​

Some gateways are set up by Finomesh to collect fees monthly rather than per payment. This covers two arrangements — the platform-billed arrangement, and standard gateways switched to monthly fee billing (your dashboard shows which applies). On these:

  • Nothing is deducted from your payments. The full amount a customer sends is credited to your balance. Finomesh covers the network cost of moving your funds and bills you at the fees agreed for your gateway instead: a transaction fee on each payment we confirm, and a settlement fee on each cashout you make. Each is either a percentage or a flat amount, and both are shown in your dashboard.
  • Those fees are billed to you as a monthly invoice instead of per payment, so you settle them in one payment rather than losing a slice of every deposit.
  • Token cashouts arrive in full. When you cash out a token (USDT, USDC, …), the destination receives exactly the amount you requested — no network fee is deducted (estimate-fee returns feeLocked: "0" and netAmount equal to amount); the settlement fee appears on your monthly statement instead. Cashouts of a chain's native coin (TRX, ETH, BNB) still deduct the network fee from the payout, and carry no settlement fee on the invoice.
  • 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 customer never pays a fee on top. Fee-payer settings do not apply on these gateways: both fees show as covered at checkout, and payments report them as PLATFORM.

Your integration is otherwise identical to a standard gateway. If you are not on either arrangement, fees are deducted from each payment as itemised on every transaction, and 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.

A cashout can also be parked before it claims anything — UNDERFUNDED when you asked for more than the balance holds, WAITING_AML_CREDIT when a destination screen could not run. A parked cashout reserves nothing and completes itself once the blocker clears, so you never re-type the request. See Create Settlement → Parked cashouts.

Next​