Skip to main content

Understanding Balances

The wallet balance structure provides detailed accounting:

Endpoint: GET /api/v1/users/:userId/wallet-balance

// Balance structure (all amounts in cents)
{
  available: {     // Ready to spend
    deposit: 5000,   // User deposits
    reward: {
      merchant: 200, // Your rewards
      accrue: 50,    // Platform rewards
      total: 250
    },
    total: 5250      // Combined total
  },
  pending: {       // Being processed
    deposit: 1000,
    reward: { total: 100 },
    total: 1100
  },
  reserved: {      // Held for transactions
    total: 500
  },
  total: {         // Overall totals
    deposit: 6000,
    reward: { total: 350 },
    total: 6350
  }
}

Balance Components​

Available Balance​

Funds ready to spend immediately:

  • Deposit: User's own deposited funds
  • Reward: Combined rewards from merchant and platform
  • Total: Sum of all available funds

Pending Balance​

Funds currently being processed:

  • Deposits in transit
  • Rewards being allocated
  • Typically clears within 1-3 business days

Reserved Balance​

Funds held for active transactions:

  • Payment authorizations
  • Pending purchases
  • Released when transactions complete or expire

Total Balance​

Overall account totals across all categories.

Converting for Display​

Converting for Display:

const displayBalance = {
  available: balance.available.total / 100,  // $52.50
  pending: balance.pending.total / 100,      // $11.00
  reserved: balance.reserved.total / 100,    // $5.00
  total: balance.total.total / 100          // $63.50
};

All amounts are stored in cents, so divide by 100 to display in dollars.

Best Practices​

  • Always show available balance prominently
  • Display pending balance separately with explanation
  • Show reserved balance when transactions are active
  • Use the total balance for account overview

Next Steps​