Settlement modes
As an external merchant, you settle through non-custodial on-chain direct settlement: the net amount lands on-chain in your own wallet and fluxa only ever takes a fee. The API also models custodial funds-flow modes (gateway custody and fiat processing), but those are operator-internal — they are not offered to external merchants. The charge endpoint, webhook contract, and dashboard are shared across all of them, so this page documents the full funds-flow model while making clear which mode you actually receive.
Direct settlement (non-custodial)
This is the mode external merchants get. Self-hosted on-chain channels (USDT/USDC on TRON, Ethereum, Base, BSC, Polygon, Arbitrum, …) settle directly to your own wallet. The customer pays a single-use deposit address; once the required confirmations are reached, fluxa sweeps the net amount (after fees) straight to the settlement address you configured — the platform treasury keeps only the fee, and fluxa never retains your principal.
- Your platform balance for these currencies stays at ~0 by design: you are paid on-chain, not from a withdrawable balance, so there is no withdrawal step and no frozen funds.
- A settlement address is required before a live charge can be created (per chain kind: one
0xaddress serves all EVM chains, TRON needs its ownT…address — see Account). - Orders cannot be refunded through the platform (
refund_unsupported) and these currencies cannot be paid out — the funds were never held by fluxa. Refund customers off-platform if needed. - Confirmation is driven by fluxa's own chain watcher; the
settlement.completedwebhook carries the on-chain sweep transaction. - Because settlement is non-custodial, there is no chargeback or dispute path: the on-chain transfer is final, and there is no custodial balance for the platform to claw back.
Operator-internal custodial modes
The two modes below are custodial and operator-internal. They exist in the funds-flow model and the API enum, but they are not offered to external merchants — an external merchant cannot enable them or collect through them. They are documented here only so the settlement / settlement_mode enum and the comparison below are complete.
Gateway custody (hosted crypto)
Hosted crypto gateways (e.g. a NOWPayments-backed gateway, Binance Pay) are a custodial mode in which the provider watches the chain and confirmed payments credit a custodial fluxa balance that is settled out via Payouts. Refund support depends on the provider. This is a platform-internal mode and is not exposed to external merchants.
Fiat processing
Local payment aggregators (bank transfer / QR) are a custodial mode for payments made in local fiat. Confirmed payments credit a custodial fluxa balance; refunds are supported where the processor supports them, and chargebacks/disputes exist only in this mode. This is a platform-internal mode and is not exposed to external merchants.
Comparison
The table below is the API's funds-flow model across all three modes. As an external merchant you are always on the Direct settlement column; the other two columns describe the operator-internal custodial modes.
| Direct settlement | Gateway custody | Fiat processing | |
|---|---|---|---|
| Offered to merchants | Yes | Operator-internal | Operator-internal |
| Platform holds your funds | No (fee only) | Yes | Yes |
| Settles to | Your own wallet | fluxa balance | fluxa balance |
| Withdrawal step | None | Payouts | Payouts |
| Platform refunds | No | Provider-dependent | Yes (where supported) |
| Chargeback risk | No | No | Yes |
| Setup prerequisite | Settlement address | None | None |
The settlement_mode field
Every order is stamped at creation with the funds-flow mode it was created under:
- Name
settlement_mode- Type
- string
- Description
direct(non-custodial direct settlement) orcustodial(everything else). Immutable for the life of the order — it reflects how this order's money actually flowed, even if the channel is reconfigured later.
Branch on it to decide, per order, whether a platform refund is possible and whether the proceeds live in your fluxa balance.
Channel capabilities expose the same axis: each entry returned by Channels carries
settlement (direct / custodial) alongside kind, so you can group your enabled channels
into the three modes in your own UI.
How a charge resolves to a channel
As an external merchant you don't choose a custodial mode — your charges resolve to non-custodial direct on-chain channels. You select (or let fluxa pick) a channel, and the channel determines the mode:
- Pass
channelexplicitly to use a specific channel. - Or omit
channeland passnetwork+currencyto let fluxa route: self-hosted direct-settlement channels are preferred. The custodial gateway fallback in the router is operator-internal and not part of the external-merchant path. See Charges.
One routing guard to know: an asset fluxa settles direct (on any network) is never silently routed through a custodial gateway on a network fluxa doesn't self-host — that credit would land in a custodial balance you cannot pay out (the payout guard blocks direct-settlement currencies). Such requests fail with no_route.
The platform operator can disable whole modes for an account; a live charge through a disabled mode is rejected with payment_mode_disabled (403). Test-mode charges are unaffected.