Skip to main content

​
What are Ledger Roles?

Ledger roles are system-defined categories that determine how ledger accounts behave in Agatabo. Each account is assigned a role that controls:
  • What types of transactions can affect it
  • How it appears in financial statements
  • Its normal debit or credit balance
  • Its scope (organization-wide, per-member, per-loan, etc.)
System-defined: Ledger roles are built into Agatabo and cannot be modified. They ensure accounting consistency and automation.

​
Why Roles Matter

Roles ensure:
  • Consistency: Same transaction types always use correct accounts
  • Automation: Agatabo knows which accounts to debit/credit for each operation
  • Validation: System prevents invalid account usage (e.g., can’t debit income accounts)
  • Reporting: Accounts grouped correctly in Balance Sheet and Income Statement
  • Scoping: Enables per-member, per-loan, per-reserve accounting

​
Complete Role Reference

​
Asset Roles

Asset roles track what the organization owns or has a right to collect.

​
CASH

Purpose: Cash on hand and bank account balances Account type: ASSET Normal balance: Debit Scope: Organization-wide or per bank account (organization:{orgId} or bankAccount:{id}) Increases (Debit):
  • Member deposits
  • Loan payments received
  • Revenue collection
  • Asset sales
Decreases (Credit):
  • Loan disbursements
  • Expense payments
  • Member withdrawals
  • Asset purchases
Example transactions: 
Member deposits 100,000 RWF:
  DEBIT: Cash +100,000
  CREDIT: Savings +100,000

​
LOAN_RECEIVABLE

Purpose: Outstanding loan principal owed to the organization Account type: ASSET Normal balance: Debit Scope: Per loan (loan:{loanId}) Increases (Debit):
  • Loan disbursements (new loans)
Decreases (Credit):
  • Loan payments (principal portion only)
  • Loan write-offs (bad debt)
Example transactions: 
Disburse 500,000 RWF loan:
  DEBIT: Loan Receivable (loan:abc123) +500,000
  CREDIT: Cash -500,000

Receive 50,000 RWF principal payment:
  DEBIT: Cash +50,000
  CREDIT: Loan Receivable (loan:abc123) -50,000

​
INTEREST_RECEIVABLE

Purpose: Accrued interest on loans not yet paid Account type: ASSET Normal balance: Debit Scope: Per loan (loan:{loanId}) Increases (Debit):
  • Interest accrual over time
  • Interest charged on loans
Decreases (Credit):
  • Interest payments received
Example transactions: 
Charge 10,000 RWF interest:
  DEBIT: Interest Receivable (loan:abc123) +10,000
  CREDIT: Interest Income +10,000

Receive interest payment:
  DEBIT: Cash +10,000
  CREDIT: Interest Receivable (loan:abc123) -10,000

​
PENALTY_RECEIVABLE

Purpose: Late payment penalties and fees owed on loans Account type: ASSET Normal balance: Debit Scope: Per loan (loan:{loanId}) Increases (Debit):
  • Late payment penalties applied
  • Fee charges
Decreases (Credit):
  • Penalty payments received
  • Penalty waivers
Example transactions: 
Charge 5,000 RWF late fee:
  DEBIT: Penalty Receivable (loan:abc123) +5,000
  CREDIT: Penalty Income +5,000

​
FIXED_ASSET

Purpose: Long-term physical assets (equipment, furniture, vehicles, buildings) Account type: ASSET Normal balance: Debit Scope: Per asset (fixedAsset:{assetId}) Increases (Debit):
  • Asset purchases
  • Asset received as collateral
  • Asset received as gift
Decreases (Credit):
  • Asset sales
  • Asset disposal
  • Asset write-offs (damage, loss)
Example transactions: 
Purchase 2,000,000 RWF vehicle:
  DEBIT: Fixed Asset (fixedAsset:vehicle123) +2,000,000
  CREDIT: Cash -2,000,000

​
Liability Roles

Liability roles track what the organization owes to others.

​
SAVINGS

Purpose: Member savings account balances (funds members have deposited) Account type: LIABILITY Normal balance: Credit Scope: Per member (organizationUser:{userId}) Increases (Credit):
  • Member deposits
  • Dividend distributions
  • Interest credited to savings
Decreases (Debit):
  • Member withdrawals
  • Loan disbursements (if from savings)
Example transactions: 
Member deposits 100,000 RWF:
  DEBIT: Cash +100,000
  CREDIT: Savings (organizationUser:alice) +100,000

Member withdraws 50,000 RWF:
  DEBIT: Savings (organizationUser:alice) -50,000
  CREDIT: Cash -50,000

Distribute 10,000 RWF dividend:
  DEBIT: Retained Earnings -10,000
  CREDIT: Savings (organizationUser:alice) +10,000
Important: This role is named SAVINGS, not “MEMBER_SAVINGS” or “MEMBER_EQUITY”. Dividends credit SAVINGS accounts (liability), not a separate equity account.

​
BORROWER_SURPLUS_LIABILITY

Purpose: Amount owed to borrower when seized collateral value exceeds outstanding loan balance Account type: LIABILITY Normal balance: Credit Scope: Per member (organizationUser:{userId}) Increases (Credit):
  • Collateral seizure (excess value over loan balance)
Decreases (Debit):
  • Payment to borrower of surplus
  • Offset against other debts
Example transactions: 
Seize 1,000,000 RWF collateral for 800,000 RWF bad debt:
  DEBIT: Fixed Asset (collateral) +1,000,000
  DEBIT: Bad Debt Expense +800,000
  CREDIT: Loan Receivable -800,000
  CREDIT: Borrower Surplus Liability +200,000

​
Equity Roles

Equity roles track the organization’s net worth and retained funds.

​
RETAINED_EARNINGS

Purpose: Accumulated organizational profits (net income over time) Account type: EQUITY Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Net income transferred at period close
  • Reversals of previous losses
Decreases (Debit):
  • Dividend distributions
  • Reserve allocations
  • Net losses
Example transactions: 
Close period with 5,000,000 RWF net income:
  DEBIT: Income Summary -5,000,000
  CREDIT: Retained Earnings +5,000,000

Distribute 2,000,000 RWF dividend:
  DEBIT: Retained Earnings -2,000,000
  CREDIT: Savings (various members) +2,000,000

Allocate 1,000,000 RWF to reserve:
  DEBIT: Reserve Allocation +1,000,000
  CREDIT: Retained Earnings -1,000,000

​
RESERVE_ALLOCATION

Purpose: Designated retained earnings set aside for specific future purposes (emergency fund, equipment replacement, building fund, etc.) Account type: EQUITY Normal balance: Debit (contra-equity) Scope: Per reserve (reserve:{reserveId}) Increases (Debit):
  • Reserve top-ups (allocations from retained earnings)
Decreases (Credit):
  • Reserve releases (back to retained earnings)
  • Reserve-funded expenses
Example transactions: 
Allocate 1,000,000 RWF to emergency reserve:
  DEBIT: Reserve Allocation (reserve:emergency) +1,000,000
  CREDIT: Retained Earnings -1,000,000

Release 500,000 RWF from reserve:
  DEBIT: Retained Earnings +500,000
  CREDIT: Reserve Allocation (reserve:emergency) -500,000
Reserves are equity: Both RETAINED_EARNINGS and RESERVE_ALLOCATION are equity accounts. Allocating to reserves moves funds within equity (internal reclassification), not between account types.

​
OPENING_EQUITY

Purpose: Initial capital when organization starts or opening balances during system setup Account type: EQUITY Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Initial capital contributions
  • Opening balance entries during migration
Decreases (Debit):
  • Corrections or adjustments
Example transactions: 
Record 5,000,000 RWF opening cash balance:
  DEBIT: Cash +5,000,000
  CREDIT: Opening Equity +5,000,000

​
OTHER_EQUITY

Purpose: Miscellaneous equity items not fitting other categories (donated capital, capital adjustments) Account type: EQUITY Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Donated assets or funds
  • Capital contributions
  • Equity adjustments
Decreases (Debit):
  • Reversals or corrections
Example transactions: 
Receive 500,000 RWF donated equipment:
  DEBIT: Fixed Asset +500,000
  CREDIT: Other Equity +500,000

​
Income Roles

Income roles track revenue earned by the organization.

​
INTEREST_INCOME

Purpose: Interest earned on loans Account type: INCOME Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Interest charged on loans
  • Interest payments received
Decreases (Debit):
  • Reversals or corrections
Example transactions: 
Charge 10,000 RWF interest on loan:
  DEBIT: Interest Receivable +10,000
  CREDIT: Interest Income +10,000

​
PENALTY_INCOME

Purpose: Late payment penalties and fees collected Account type: INCOME Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Late payment penalties
  • Fee charges
Decreases (Debit):
  • Penalty waivers
  • Reversals
Example transactions: 
Charge 5,000 RWF late fee:
  DEBIT: Penalty Receivable +5,000
  CREDIT: Penalty Income +5,000

​
ENTRY_FEE_INCOME

Purpose: Membership fees collected when members join Account type: INCOME Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Entry fee payments
Decreases (Debit):
  • Refunds or reversals
Example transactions: 
Collect 50,000 RWF entry fee:
  DEBIT: Cash +50,000
  CREDIT: Entry Fee Income +50,000

​
DISBURSEMENT_FEE_INCOME

Purpose: Fees charged for loan processing and disbursement Account type: INCOME Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Loan processing fees
  • Disbursement fees
Decreases (Debit):
  • Fee refunds
Example transactions: 
Charge 10,000 RWF loan processing fee:
  DEBIT: Cash +10,000
  CREDIT: Disbursement Fee Income +10,000

​
OTHER_INCOME

Purpose: Miscellaneous revenue not fitting other categories Account type: INCOME Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Asset rental income
  • Service fees
  • Other revenue sources
Decreases (Debit):
  • Reversals

​
BAD_DEBT_RECOVERY_INCOME

Purpose: Recovery of previously written-off loans (collateral seizure value, unexpected payments) Account type: INCOME Normal balance: Credit Scope: Organization-wide (organization:{orgId}) Increases (Credit):
  • Collateral seizure proceeds
  • Recovered payments on defaulted loans
Decreases (Debit):
  • Reversals
Example transactions: 
Seize 1,000,000 RWF collateral for 800,000 RWF bad debt:
  DEBIT: Fixed Asset +1,000,000
  CREDIT: Bad Debt Recovery Income +800,000
  CREDIT: Borrower Surplus Liability +200,000

​
Expense Roles

Expense roles track costs incurred by the organization.

​
OPERATING_EXPENSE

Purpose: General operational costs (rent, utilities, supplies, salaries, administrative expenses) Account type: EXPENSE Normal balance: Debit Scope: Organization-wide (organization:{orgId}) or per expense category Increases (Debit):
  • Expense payments
  • Accrued expenses
Decreases (Credit):
  • Reversals or refunds
Example transactions: 
Pay 50,000 RWF rent:
  DEBIT: Operating Expense +50,000
  CREDIT: Cash -50,000

​
BANK_CHARGE_EXPENSE

Purpose: Banking fees and charges Account type: EXPENSE Normal balance: Debit Scope: Organization-wide (organization:{orgId}) Increases (Debit):
  • Bank fees
  • Transaction charges
  • Account maintenance fees
Decreases (Credit):
  • Fee reversals or refunds
Example transactions: 
Pay 2,000 RWF bank fee:
  DEBIT: Bank Charge Expense +2,000
  CREDIT: Cash -2,000

​
BAD_DEBT_EXPENSE

Purpose: Loans written off as uncollectible Account type: EXPENSE Normal balance: Debit Scope: Organization-wide (organization:{orgId}) Increases (Debit):
  • Loan defaults and write-offs
Decreases (Credit):
  • Reversals (if loan subsequently recovered)
Example transactions: 
Write off 800,000 RWF defaulted loan:
  DEBIT: Bad Debt Expense +800,000
  CREDIT: Loan Receivable -800,000

​
Account Scoping with Scope Keys

Agatabo uses scope keys to create multiple accounts with the same role for different entities.

​
Scope Key Format

{entity_type}:{entity_id}

​
Organization-Scoped Accounts

Format: organization:{organizationId} Single account for entire organization:
  • CASH (unless separate per bank account)
  • RETAINED_EARNINGS
  • RESERVE_ALLOCATION (per reserve, but using reserve:)
  • All INCOME roles
  • All EXPENSE roles
  • OPENING_EQUITY
  • OTHER_EQUITY
Example: organization:org-123

​
Member-Scoped Accounts

Format: organizationUser:{userId} Individual account per member:
  • SAVINGS: Each member has their own savings account
  • BORROWER_SURPLUS_LIABILITY: Tracked per member
Example: organizationUser:alice-456

​
Loan-Scoped Accounts

Format: loan:{loanId} Separate account per loan:
  • LOAN_RECEIVABLE: Principal balance
  • INTEREST_RECEIVABLE: Accrued interest
  • PENALTY_RECEIVABLE: Accrued penalties
Example: loan:loan-789

​
Reserve-Scoped Accounts

Format: reserve:{reserveId} Separate account per reserve:
  • RESERVE_ALLOCATION: Each reserve has its own equity account
Example: reserve:emergency-fund-123

​
Asset-Scoped Accounts

Format: fixedAsset:{assetId} Separate account per asset:
  • FIXED_ASSET: Each physical asset tracked separately
Example: fixedAsset:vehicle-456

​
Bank Account-Scoped Accounts

Format: bankAccount:{bankAccountId} Separate CASH account per bank account:
  • CASH: One account per bank account
Example: bankAccount:bank-789

​
How Agatabo Uses Roles

​
Example 1: Member Deposit

When you record a deposit for Alice:
  1. System finds Alice’s SAVINGS account via scope key organizationUser:alice-123
  2. System finds organization’s CASH account
  3. Creates journal entry: 
    DEBIT: Cash (organization:org123) +100,000
CREDIT: Savings (organizationUser:alice123) +100,000

​
Example 2: Loan Disbursement

When you disburse a loan to Bob:
  1. System creates new LOAN_RECEIVABLE account with scope loan:bob-loan-456
  2. System finds CASH account
  3. Creates journal entry: 
    DEBIT: Loan Receivable (loan:bob-loan-456) +500,000
CREDIT: Cash (organization:org123) -500,000

​
Example 3: Dividend Distribution

When you distribute dividends:
  1. System finds organization’s RETAINED_EARNINGS account
  2. System finds each member’s SAVINGS account
  3. Creates journal entry: 
    DEBIT: Retained Earnings (organization:org123) -5,000,000
CREDIT: Savings (organizationUser:alice) +100,000
CREDIT: Savings (organizationUser:bob) +100,000
CREDIT: Savings (organizationUser:carol) +100,000
... (50 members total)

​
Example 4: Reserve Allocation

When you allocate to a reserve:
  1. System finds specific RESERVE_ALLOCATION account via scope reserve:emergency-fund
  2. System finds organization’s RETAINED_EARNINGS account
  3. Creates journal entry: 
    DEBIT: Reserve Allocation (reserve:emergency-fund) +1,000,000
CREDIT: Retained Earnings (organization:org123) -1,000,000

​
Role Summary Table

RoleTypeNormal BalanceScope PatternExample Scope Key
CASHASSETDebitorganization or bankAccountorganization:org123
LOAN_RECEIVABLEASSETDebitloanloan:loan123
INTEREST_RECEIVABLEASSETDebitloanloan:loan123
PENALTY_RECEIVABLEASSETDebitloanloan:loan123
FIXED_ASSETASSETDebitfixedAssetfixedAsset:car456
SAVINGSLIABILITYCreditorganizationUserorganizationUser:alice
BORROWER_SURPLUS_LIABILITYLIABILITYCreditorganizationUserorganizationUser:bob
RETAINED_EARNINGSEQUITYCreditorganizationorganization:org123
RESERVE_ALLOCATIONEQUITYDebitreservereserve:emergency
OPENING_EQUITYEQUITYCreditorganizationorganization:org123
OTHER_EQUITYEQUITYCreditorganizationorganization:org123
INTEREST_INCOMEINCOMECreditorganizationorganization:org123
PENALTY_INCOMEINCOMECreditorganizationorganization:org123
ENTRY_FEE_INCOMEINCOMECreditorganizationorganization:org123
DISBURSEMENT_FEE_INCOMEINCOMECreditorganizationorganization:org123
OTHER_INCOMEINCOMECreditorganizationorganization:org123
BAD_DEBT_RECOVERY_INCOMEINCOMECreditorganizationorganization:org123
OPERATING_EXPENSEEXPENSEDebitorganizationorganization:org123
BANK_CHARGE_EXPENSEEXPENSEDebitorganizationorganization:org123
BAD_DEBT_EXPENSEEXPENSEDebitorganizationorganization:org123

​
Roles Cannot Be Changed

System-defined roles: Ledger roles are built into Agatabo and cannot be modified, renamed, or deleted. They are set when accounts are created and determine how Agatabo processes all transactions.
Why roles are fixed:
  • Ensures accounting consistency across all organizations
  • Enables automation of journal entries
  • Maintains financial statement accuracy
  • Prevents accounting errors from misconfigured accounts
If you need different functionality:
  • Use existing roles creatively (e.g., OPERATING_EXPENSE for various expense types)
  • Contact support for custom requirements
  • May require platform enhancement

​
Best Practices

Working with ledger roles:Understanding:
  • Learn the roles relevant to your work (treasurers focus on CASH, SAVINGS; loan officers on LOAN_RECEIVABLE)
  • Review this reference when creating manual journal entries
  • Understand scope keys for per-member, per-loan accounting
Usage:
  • Trust automatic role assignment (Agatabo selects correctly)
  • Verify roles when reviewing journal entries
  • Report if transactions use unexpected roles (may indicate bug)
  • Use correct scope keys when querying accounts
Manual Entries:
  • Consult this guide before creating manual entries
  • Verify you’re using the right role for your purpose
  • Match role types correctly (ASSET with ASSET, LIABILITY with INCOME, etc.)
  • Include proper scope keys
Auditing:
  • Review role assignments during financial audits
  • Verify scope keys are correct for entity-specific accounts
  • Check that all accounts follow role typing rules
  • Report anomalies to accountant or support

​
Need Help?

General Ledger Overview

Understand the accounting system

Understanding Double-Entry

Learn accounting basics

Viewing Journal Entries

See how roles are used in transactions

Manual Journal Entries

Create entries using specific roles

Balance Sheet

See how roles appear in financial statements