How do I set up a wallet and balance system for managing worker earnings, tips, and bonuses?

A good way to set this up is to treat it like a ledger-based wallet system instead of just storing a single “balance” field.

1) Core idea

For each worker, maintain:

• wallet account
• ledger entries for every credit/debit
• available balance
• optional pending/locked balance

This gives you an auditable system for:

• worker earnings
• customer tips
• admin bonuses
• withdrawals/payouts
• refunds/reversals

---

2) Recommended structure

Worker wallet

Each worker has one wallet record:

• worker_id
• currency
• available_balance
• pending_balance
• locked_balance
• status

Ledger table

Every money movement becomes a transaction row:

• id
• wallet_id
• type (earning, tip, bonus, payout, refund, adjustment)
• direction (credit or debit)
• amount
• status (pending, posted, reversed)
• reference_type / reference_id
• created_by
• created_at
• metadata

This table is the source of truth.

---

3) Balance rules

Use clear balance states:

• Pending: money earned but not yet confirmed/cleared
• Available: can be withdrawn/spent
• Locked: reserved for payout processing or disputes

Example:

• Job completed: add +$50 as pending
• After approval: move +$50 from pending to available
• Tip given immediately: +$10 to available
• Bonus approved: +$20 to available
• Payout requested: move -$60 from available to locked
• Payout completed: remove from locked

---

4) Transaction types

Typical transaction categories:

Credits

• job_earning
• tip
• bonus
• refund_adjustment
• manual_credit

Debits

• payout
• chargeback
• fee
• manual_debit

Each transaction should include a business reference, like:

• job ID
• tip ID
• bonus ID
• payout request ID

---

5) Workflow examples

Worker completes a job

1. Create ledger entry: pending +100
2. Store job as “awaiting approval”
3. Once approved, create another entry or state transition:
   • pending -100
   • available +100

Customer tips worker

1. Create ledger entry: available +15
2. No pending unless you need anti-fraud review

Admin grants bonus

1. Create ledger entry: available +25
2. Mark as bonus

Worker requests payout

1. Check available balance
2. Create payout record
3. Move amount from available to locked
4. On success, deduct from locked
5. On failure, release back to available

---

6) Important design principles

Use double-entry logic if possible

Best practice is to record both sides of the movement:

• worker wallet credited
• platform liability or expense account debited

This helps with accounting and reconciliation.

Never trust only a balance field

Always be able to recompute balance from ledger if needed.

Make operations atomic

Use database transactions so balance updates and ledger inserts happen together.

Keep idempotency keys

Prevent duplicate credits from retries:

• same job approval
• same payout request
• same webhook event

---

7) Minimal database schema example

wallets

• id
• worker_id
• currency
• available_balance
• pending_balance
• locked_balance
• created_at
• updated_at

wallet_transactions

• id
• wallet_id
• type
• direction
• amount
• status
• reference_type
• reference_id
• idempotency_key
• metadata
• created_at

payout_requests

• id
• worker_id
• amount
• status
• wallet_transaction_id
• created_at

---

8) Best practices

• Store amounts as integers in the smallest currency unit, e.g. cents
• Validate no negative available balance
• Audit every manual adjustment
• Keep timestamps and actor info
• Add reconciliation reports
• Separate worker earnings from platform fees
• Support reversals for refunds/chargebacks

---

9) Simple mental model

Think of it as:

Wallet = current state
Ledger = full history

You update the wallet for fast reads, but the ledger is the truth.

---

If you want, I can also provide:

1. a SQL schema
2. a Node.js/Express implementation
3. a Django model setup
4. a double-entry accounting version