LogoZebo Studio

Understand balances

Your balance aggregates all funds flowing through your Commerce account into a single financial snapshot. Unlike individual transactions which show moment-to-moment activity, balance states tell you exactly what money is available for payout, what's still aging through settlement, what's reserved for disputes, and what you've allocated for refunds. This guide explains how the balance system works, why snapshots are eventually consistent, and how to interpret each balance state for cash flow planning.

How balance snapshots work

Your balance isn't calculated in real-time on every request—that would mean aggregating thousands of transactions every time someone calls the API. Instead, background workflows compute balance snapshots every 12 hours by default, processing all balance transactions up to a specific cutoff time. For applications with specific operational needs, we can configure faster or slower computation cycles—contact support if your use case requires a different schedule.

Each snapshot captures the complete balance state at that moment: available funds, pending settlements, platform reserves, and your refund buffer. The includes_transactions_before timestamp tells you exactly when the snapshot was taken—transactions created after that time won't appear in the balance until the next snapshot runs.

This snapshot architecture trades a small delay for predictable query performance. You get sub-millisecond lookups that scale regardless of transaction volume, with guaranteed consistency up to the cutoff time. For real-time transaction tracking, use the Balance Transactions API—for aggregated financial state, use the Balances API.

Snapshot timing example

Consider this timeline with the default 12-hour computation cycle:

  • 2:00 AM: Snapshot workflow runs, captures all transactions up to 2:00 AM
  • 9:30 AM: Customer completes a $50 payment
  • 10:00 AM: You call the Balances API → doesn't include the $50 yet (snapshot still shows 2:00 AM data)
  • 2:00 PM: Next snapshot runs (12 hours later), now includes the $50 payment
  • 2:05 PM: You call the Balances API → shows the $50 in pending balance

The $50 appears in your balance within 12 hours, which is acceptable for most use cases. If you need to confirm the payment immediately, query the Balance Transactions API or check the payment object directly. For applications requiring faster balance updates (e.g., high-frequency trading platforms, instant payout systems), contact support to discuss configuring a shorter computation cycle.

The four balance states

Funds move through four distinct states as they flow from customer payment to your bank account. Each state represents a different stage in the lifecycle and has different characteristics for availability and control.

Available

Money that has cleared settlement and is ready for payout. These funds have aged past the settlement window (typically 7 days for most payment methods), meaning they're outside the chargeback risk period. When you schedule a payout, funds come from your available balance.

This is your "spendable" money—the number that matters for cash flow planning and payout scheduling. Available balance grows as pending transactions mature and shrinks when you execute payouts or move funds to your refund buffer.

Key characteristics:

  • Ready for immediate payout
  • Outside chargeback risk window
  • Can be moved to refund balance
  • Increases: pending → available transitions
  • Decreases: payouts, transfers to refund balance

Pending

Funds recognized from successful payments but still aging through the settlement window. Pending amounts aren't available for payout yet because they're within the dispute period—if a customer initiates a chargeback, these funds could be reversed.

Pending balances automatically move to available after the aging period completes. The aging duration depends on payment method characteristics and risk profile. Mobile money transactions typically age for 7 days, while card payments may have different aging rules based on issuer policies.

Think of this as "money on the way"—it's yours, but you can't withdraw it yet. Pending balance gives you visibility into upcoming liquidity without prematurely making funds available during the dispute window.

Key characteristics:

  • Aging through settlement window
  • Within dispute/chargeback period
  • Automatically transitions to available
  • Not available for payout yet
  • Increases: successful payments
  • Decreases: maturation to available, chargebacks

Reserved

Funds automatically held by the Commerce platform for potential disputes, chargebacks, or fraud protection. These are platform-managed reserves that Commerce sets aside based on risk assessment, payment method characteristics, or historical dispute patterns.

Reserved amounts aren't available for payout—they're held to cover potential liabilities if customers dispute charges. Once the risk period passes or disputes resolve, reserved funds automatically move back to available balance.

You don't control this directly—Commerce manages reservations to protect both you and the platform. Reserves increase when risk indicators suggest higher dispute likelihood and decrease as risk periods expire without incidents.

Key characteristics:

  • Platform-controlled (automatic)
  • Held for dispute/chargeback coverage
  • Not available for payout
  • Automatically released when risk passes
  • Based on risk assessment algorithms
  • Increases: high-risk transactions, dispute history
  • Decreases: risk period expiration, dispute resolution

Refund

Balance you've set aside for processing customer refunds. Unlike reserved funds which Commerce manages automatically, the refund balance is under your control—you allocate funds here when you anticipate upcoming refunds or want to maintain a buffer for refund requests.

When you actually process a refund, the amount is deducted from this balance. Think of this as your "refund account"—money you're holding specifically to handle returns and cancellations.

You can move funds between available and refund balances based on your refund policies and expected refund volume. Merchants with liberal return policies might keep 10-15% of revenue in refund balance, while those with minimal returns might keep a smaller buffer.

Key characteristics:

  • Merchant-controlled (manual allocation)
  • Set aside for anticipated refunds
  • Not available for payout
  • Source for refund processing
  • You decide allocation strategy
  • Increases: transfers from available balance
  • Decreases: processed refunds, transfers back to available

Balance state transitions

Understanding how funds move between states helps you predict cash flow and plan payout timing:

Automatic transitions (platform-controlled):

  • Pending → Available (after aging period)
  • Available → Reserved (risk-based, automatic)
  • Reserved → Available (when risk period expires)

Manual transitions (merchant-controlled):

  • Available → Refund (you allocate buffer)
  • Refund → Available (you release excess buffer)
  • Refund → Refunded (you process customer refund)

Note: Reserved funds operate on a separate path—Commerce may reserve funds from either pending or available balance depending on when risk indicators appear.

Reading the balance response

When you call the Balances API, you get a multi-currency response with each currency broken into the four states:

{
  "balances": {
    "ghs": {
      "available": { "amount": 145000 },      // GHS 1,450.00 ready for payout
      "pending": { "amount": 32000 },         // GHS 320.00 aging (7 days)
      "reserved": { "amount": 5000 },         // GHS 50.00 held by platform
      "refund": { "amount": 15000 },          // GHS 150.00 you set aside
      "includes_transactions_before": "2024-12-24T14:00:00.000Z"
    }
  }
}

Interpreting the numbers:

  • Available GHS 1,450: You can pay out this amount right now
  • Pending GHS 320: Will become available within the next 7 days (assuming no disputes)
  • Reserved GHS 50: Platform holding this due to risk factors—will release automatically
  • Refund GHS 150: You allocated this for anticipated refunds—can release if not needed
  • Snapshot cutoff: Balance reflects all transactions before 2:00 PM today

Total funds in platform: GHS 1,450 + 320 + 50 + 150 = GHS 1,970
Spendable now: GHS 1,450 (only available balance)
Your control: GHS 1,450 (available) + GHS 150 (refund) = GHS 1,600
Platform control: GHS 320 (pending, automatic) + GHS 50 (reserved, automatic) = GHS 370

Common questions

Why is my balance lower than expected?

Check each state:

  1. Pending too high? Recent payments are still aging—they'll move to available after 7 days
  2. Reserved too high? Platform detected risk factors—contact support if reserves seem excessive
  3. Refund balance too high? You may have allocated too much—transfer excess back to available
  4. Recent payout? Available balance decreases immediately after payout execution

Can I speed up pending → available transitions?

No. The aging period is a risk management requirement that protects against chargebacks. Transactions must age outside the dispute window before becoming available. This is standard in payment processing—even card processors have 60-90 day dispute windows, though payout timing rules vary.

How do I control reserved balance?

You don't—reserves are platform-managed based on risk algorithms. However, you can:

  1. Improve transaction quality to reduce risk indicators
  2. Build positive payment history to lower reserve requirements over time
  3. Contact support if reserves seem disproportionate to actual risk

Should I always maintain a refund balance?

Depends on your refund volume. Merchants with minimal refunds might keep refund balance at zero and transfer from available as needed. High-refund businesses benefit from maintaining a buffer to avoid transferring funds multiple times daily. Your refund policy and return rate should guide the strategy.

What if I need to refund more than my refund balance?

Refunds can be processed from available balance if refund balance is insufficient—the system doesn't block refunds. The refund balance is a financial management tool, not a hard constraint. Think of it as an envelope budgeting system: you can overspend an envelope, but tracking the allocation helps with planning.

Was this page helpful?