Balance and settlement
How merchant balances, fees, and availability work after a successful payment.
Balances are updated when a transaction reaches completed. This page explains how balances, fees, and fund availability work after a successful payment.
In the test environment, completed payments credit your dashboard test balance only, they do not update your live withdrawable balance. See Sandbox payments.
When balances change
- Merchant-receivable balance increases by the net amount of the transaction (gross minus platform fee).
- Updates run only for
completedtransactions. - A metadata flag records that balances were already applied for that transaction, so retries cannot double-credit.
Availability delay
Each transaction stores an available_at timestamp computed from organization payment settings:
NOW() + get_payment_availability_delay(organization, provider, payment_method)- Example: some card configurations default to a delayed availability window; Mobile Money may be immediate.
The dashboard may show available vs pending/settling based on this and related rules.
Multi-currency settlement
When you accept payments in multiple currencies, lomi. may convert amounts for fee and settlement accounting. Your dashboard balance is credited in your organization's settlement currency according to your product settings.
Exact API fields for “available” vs “pending” balances are exposed in Balances.
Settlement periods (API)
Funds become withdrawable when available_at passes. For accounting, group completed payments by availability date and currency:
GET /settlements: list periods with gross, fee, and net totals per{currency}:{YYYY-MM-DD}(UTC date ofavailable_at).GET /settlements/{id}/transactions: line items for one period; sums should match the period totals.
status on each period is available when all underlying transactions are past available_at, otherwise pending. This is org-scoped reconciliation, not the same as provider payout batches from Paystack or Flutterwave.
See List settlement periods and List settlement transactions.
Coupons and completion
Coupon redemption counts typically advance when the transaction completes, not when the coupon is merely typed at checkout.