Chart of Accounts

The Chart of Accounts is the foundation of the double-entry accounting system. It defines all accounts used to track financial activity.

Account Structure

Accounts are organized hierarchically using a 4-digit code system:

1000-1999  Assets
2000-2999  Liabilities
3000-3999  Equity
4000-4999  Revenue
5000-5999  Expenses

Standard Accounts

Assets (1000-1999)

Assets represent what the company owns or is owed.

Current Assets (1100-1199)

1110 - User Wallets
  Description: Cash held in user wallet accounts
  Normal Balance: DEBIT
  Increases: When users top up or receive payments
  Decreases: When users make payments or withdraw

1120 - Vendor Wallets
  Description: Cash held in vendor wallet accounts
  Normal Balance: DEBIT
  Increases: When vendors receive payments
  Decreases: When vendors withdraw or pay out

1130 - Cash in Transit
  Description: Funds being transferred between parties
  Normal Balance: DEBIT
  Use: Temporarily holds funds during processing

1140 - Clearing Account
  Description: Temporary holding for unreconciled transactions
  Normal Balance: DEBIT
  Use: Reconciliation and settlement processes

Liabilities (2000-2999)

Liabilities represent what the company owes to others.

Current Liabilities (2100-2199)

2110 - Pending Settlements
  Description: Obligations pending finalization
  Normal Balance: CREDIT
  Increases: When settlements are initiated
  Decreases: When settlements complete

2120 - User Liabilities
  Description: Amounts owed to users
  Normal Balance: CREDIT
  Use: Refunds, corrections, pending payouts

2130 - Vendor Liabilities
  Description: Amounts owed to vendors
  Normal Balance: CREDIT
  Use: Commission payouts, vendor settlements

Equity (3000-3999)

Equity represents the owner's stake in the company.

3100 - Retained Earnings
  Description: Accumulated profits from operations
  Normal Balance: CREDIT
  Increases: When revenue > expenses (profit)
  Decreases: When expenses > revenue (loss)

3200 - Owner's Capital
  Description: Capital invested by owners
  Normal Balance: CREDIT
  Use: Initial funding, additional capital contributions

Revenue (4000-4999)

Revenue accounts track money earned from operations.

Service Revenue (4100-4199)

4110 - Transaction Fee Revenue
  Description: Fees from payment transactions
  Normal Balance: CREDIT
  Example: E5 fee on E95 vendor payment

4120 - Withdrawal Fee Revenue
  Description: Fees from cash withdrawals
  Normal Balance: CREDIT
  Example: E5 fee on E100 withdrawal

4130 - Commission Income
  Description: Commissions earned from vendors
  Normal Balance: CREDIT
  Example: 2% commission on vendor sales

4140 - Subscription Revenue
  Description: Revenue from subscription plans
  Normal Balance: CREDIT
  Example: Monthly premium user fees

4150 - Interest Income
  Description: Interest earned on held funds
  Normal Balance: CREDIT
  Example: Interest from bank accounts

Expenses (5000-5999)

Expense accounts track money spent on operations.

Operating Expenses (5100-5199)

5110 - Processing Costs
  Description: External payment processing fees
  Normal Balance: DEBIT
  Example: Mobile money provider fees

5120 - Refund Expenses
  Description: Cost of processing refunds
  Normal Balance: DEBIT
  Example: Administrative cost of refund processing

5130 - Reversal Expenses
  Description: Cost of reversing transactions
  Normal Balance: DEBIT
  Example: Manual intervention for reversals

5140 - Bad Debt Expense
  Description: Uncollectible amounts
  Normal Balance: DEBIT
  Example: Fraudulent transactions that cannot be recovered

Account Usage Examples

Example 1: User P2P Transfer (E100)

Transaction: User A sends E100 to User B

DEBIT  1110 (User Wallets) - E100 [User A]
CREDIT 1110 (User Wallets) - E100 [User B]

Effect:
- User A's wallet balance decreases by E100
- User B's wallet balance increases by E100
- Total Assets unchanged (internal transfer)

Example 2: Vendor Payment with Fee (E95 + E5)

Transaction: User pays vendor E95, Keshless charges E5 fee

DEBIT  1110 (User Wallets) - E100 [User]
CREDIT 1120 (Vendor Wallets) - E95 [Vendor]
CREDIT 4110 (Transaction Fee Revenue) - E5 [Keshless]

Effect:
- User's wallet decreases by E100
- Vendor's wallet increases by E95
- Keshless earns E5 revenue
- Assets decrease by E5, Revenue increases by E5

Example 3: Wallet Topup (E200)

Transaction: User tops up wallet from mobile money

DEBIT  1110 (User Wallets) - E200 [User]
CREDIT 1130 (Cash in Transit) - E200 [External]

Effect:
- User's wallet increases by E200
- Cash in transit liability increases by E200
- Total Assets increase by E200

Example 4: Cash Withdrawal with Fee (E100 + E5)

Transaction: User withdraws E100 cash, pays E5 fee

DEBIT  1120 (Vendor Wallets) - E100 [Vendor]
DEBIT  4120 (Withdrawal Fee Revenue) - E5 [Keshless]
CREDIT 1110 (User Wallets) - E105 [User]

Wait, that's wrong! Let me fix:

DEBIT  1110 (User Wallets) - E105 [User]
CREDIT 1120 (Vendor Wallets) - E100 [Vendor]
CREDIT 4120 (Withdrawal Fee Revenue) - E5 [Keshless]

Effect:
- User's wallet decreases by E105
- Vendor's wallet increases by E100 (cash dispensed)
- Keshless earns E5 revenue

Actually, let me reconsider this. For a withdrawal:

Transaction: User withdraws E100 cash, pays E5 fee

DEBIT  5110 (Processing Costs) - E105 [Cash out]
CREDIT 1110 (User Wallets) - E105 [User]

Then separately record the fee:

DEBIT  1110 (User Wallets) - E5 [User]
CREDIT 4120 (Withdrawal Fee Revenue) - E5 [Keshless]

Actually, the template handles this correctly. Let me show the proper entry:

Transaction: User withdraws E100 cash at vendor, pays E5 fee

DEBIT  1120 (Vendor Wallets) - E100 [Vendor dispenses cash]
DEBIT  4120 (Withdrawal Fee Revenue) - E5 [Keshless earns fee]
CREDIT 1110 (User Wallets) - E105 [User pays total]

No wait, revenue should be CREDIT. Let me show it correctly:

DEBIT  1110 (User Wallets) - E105 [User]
CREDIT 1120 (Vendor Wallets) - E100 [Vendor]
CREDIT 4120 (Withdrawal Fee Revenue) - E5 [Revenue]

Example 5: Refund (E95)

Transaction: Refund a vendor payment

DEBIT  1120 (Vendor Wallets) - E95 [Vendor]
DEBIT  4110 (Transaction Fee Revenue) - E5 [Reverse fee]
CREDIT 1110 (User Wallets) - E100 [User]

Effect:
- Vendor's wallet decreases by E95
- User's wallet increases by E100
- Fee revenue decreased by E5 (reversed)

Account Balance Tracking

For each account, the system tracks:

{
  accountCode: '1110',
  name: 'User Wallets',
  debitTotal: 50000,      // Total debits to this account
  creditTotal: 45000,     // Total credits to this account
  balance: 5000,          // debitTotal - creditTotal
  lastReconciledAt: Date,
  version: 42             // Optimistic locking
}

Normal Balance Rules

Account Type	Normal Balance	Balance Formula
Asset	DEBIT	Debits - Credits
Liability	CREDIT	Credits - Debits
Equity	CREDIT	Credits - Debits
Revenue	CREDIT	Credits - Debits
Expense	DEBIT	Debits - Credits

Adding Custom Accounts

While the system seeds 25+ standard accounts, you can add custom accounts:

import { chartOfAccountsService } from './services/accounting';

const account = await chartOfAccountsService.createAccount({
  code: '4160',
  name: 'Premium Feature Revenue',
  type: 'REVENUE',
  subtype: 'Service Revenue',
  normalBalance: 'CREDIT',
  currency: 'E',
  description: 'Revenue from premium feature subscriptions',
  isActive: true,
});

Account Hierarchy

Accounts can have parent-child relationships:

1000 - Assets (parent)
  1100 - Current Assets (parent)
    1110 - User Wallets (child)
    1120 - Vendor Wallets (child)

This allows for:

• Sub-total reporting
• Hierarchical financial statements
• Drill-down analysis

Next Steps

• Double-Entry Principles - How transactions work
• Transaction Templates - Pre-built patterns
• API Reference - Account management methods