Payout lifecycle
How withdrawals and beneficiary payouts progress from request to completion and how fees apply.
Payouts involve balance checks, fees, provider routing, and status transitions. Behavior is spread across payout and Wave-related database functions; this page gives integrators the mental model.
Payout types
- Withdrawals — funds from your lomi. balance to your own payout method (Mobile Money, bank, etc.).
- Beneficiary payouts — funds sent to a third-party account (vendors, partners, refunds routing, etc.).
Use the dedicated API references:
Status progression
Payouts move through states such as pending, processing, completed, and failed (exact enums match your API schema).
Completion vs initiation
Some flows validate balance at creation and debit or finalize on completion. That means:
- A payout can be accepted while still processing.
- If balance changes before final settlement, completion can fail and the payout may be marked failed or reversed according to provider rules.
Always treat completed as the source of truth for “money left the platform.”
Fees
Payout fees depend on:
- Organization fee configuration (and tiered overrides where applicable)
- Provider and payment method (e.g. local vs international bank)
- Currency
Fee resolution may use tier-aware helpers for payout categories. For high-level pricing modes, see Organizations and Merchant of record pricing.
Limits
Withdrawal flows can enforce minimum/maximum amounts and per-period caps (for example monthly limits per provider). Exact numbers are configured per organization and provider.
Failure and retries
Failures may occur due to invalid account details, provider rejection, or insufficient balance at settlement time. Check payout status and metadata in the API and operational logs.