In this article
Design a balance view that separates provider observations, pending activity, and internal business obligations.
A wallet screen can show one attractive number and still leave a user confused about what they can do next. Product teams need to distinguish the provider’s balance information from incoming activity, outgoing commitments, and the platform’s own accounting classifications. Combining everything into a single homemade “available” figure invites mistakes.
Anchor the display to a defined observation
Moov’s wallet guide describes funding, wallet-to-wallet movement, and cashing out. It also explains that funding may be held for review in some circumstances. A planned incoming payment is therefore not a reason to promise that the same amount is already usable.
For every displayed amount, specify its source, timestamp, currency, and meaning. If the amount comes from the provider, preserve the documented definition. If it is calculated internally, label the calculation and explain its components. Do not reuse a provider field name for a different internal concept. A user should not need to reverse-engineer your accounting model to understand a payout screen.
Separate money from obligations
Your platform may owe a merchant money for completed work even while the related payment activity is still unresolved. That business obligation and the observed wallet position answer different questions. Keep them in separate records and connect them through identifiers. Otherwise, an operational delay can accidentally erase an obligation, or an earned amount can be mistaken for immediately spendable funds.
Plan how concurrent actions affect the display. If two payout requests inspect the same earlier balance, both can appear affordable in isolation. The design needs a controlled reservation or coordination approach appropriate to the system, plus a fresh authoritative check where required. The article does not prescribe a Moov balance algorithm; it highlights the application-side concurrency question your engineers must resolve.
Fictional worked example: a tempting total
Consider a fictional business, Laurel Classes. Its planning worksheet shows an observed wallet amount of $500, a $150 incoming item still unresolved, and a $200 payout request already recorded internally. A designer adds the incoming amount and subtracts the payout to display $450 as “ready now.” The review team rejects that label because it mixes observations with assumptions.
Instead, Laurel’s mockup displays the provider-reported figure with its observation time, the incoming item as separate activity, and the payout request as a separate commitment. The team documents whether the provider figure already reflects the payout before subtracting anything in an internal calculation. That check prevents the same outgoing amount from being counted twice.
The numbers are fictional, and the example does not establish the exact semantics of any live balance field. Its lesson is to reconcile definitions before performing arithmetic. Correct arithmetic on mismatched categories still gives a misleading answer.
Handle stale and unavailable data honestly
If the application cannot refresh a balance, preserve the last observation with a visible timestamp where appropriate. Do not turn a retrieval failure into a zero balance, and do not imply that an old amount is current. A payment action that depends on fresh information may need to pause even while a read-only activity history remains available.
Design negative or unexpected balances as explicit operational cases. The support procedure should identify the related activity, responsible business owner, and approved next step. It should not invite staff to edit a displayed number to make the screen look normal. Corrections must preserve an explainable record of what changed and why.
Balance-model checklist
- Define each displayed amount and its authoritative source.
- Show currency and the observation time where relevant.
- Keep pending activity separate from confirmed availability.
- Check whether outgoing activity is already reflected before subtracting it.
- Separate business obligations from wallet observations.
- Review concurrent payout requests and stale-data behavior.
- Provide an investigation path for unexpected balances.
Limits of the model
This design exercise does not establish safeguarding, insurance, legal ownership, or the availability of funds for a specific account. Those questions require the applicable official terms and account-specific information. The goal is narrower: make the screen explainable, keep calculations traceable, and prevent a convenient total from becoming an unsupported promise that money can move immediately.