Accounting Setup

Apache Fineract uses double-entry accounting. Every financial transaction - a loan disbursement, a repayment, a savings deposit, a fee payment - automatically generates the corresponding journal entries in the general ledger based on the accounting rules you configure for each product. Getting accounting right before going live is critical: retrospective corrections to journal entries are complex, and incorrect mappings produce misleading financial statements from day one.

This guide walks through the setup sequence: chart of accounts first, then product mappings.

Account Types

Fineract uses five standard account types, each serving a distinct accounting purpose:

Type	Usage
Asset	What the institution owns or is owed: loan portfolios, cash, bank accounts, interest receivable
Liability	What the institution owes: savings balances, deposits, borrowings
Equity	Retained earnings, paid-up capital, reserves
Income	Revenue: interest income, fee income, penalty income
Expense	Costs: provisioning, write-off losses, operating expenses

Setting Up the Chart of Accounts

A default chart of accounts is seeded when your Fineract instance is provisioned. Review it before creating any loan or savings products - the default accounts may not match your institution's GL structure or regulatory requirements.

View Existing Accounts

curl https://your-instance.finecko.com/fineract-provider/api/v1/glaccounts \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:password' | base64)"

Each account has a GL code (your institution's internal code), a name, and a type.

Create an Account

curl -X POST \
  https://your-instance.finecko.com/fineract-provider/api/v1/glaccounts \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loan Portfolio - Personal Loans",
    "glCode": "1100",
    "type": 1,
    "manualEntriesAllowed": false,
    "usage": 1
  }'

Account type codes: 1 = Asset, 2 = Liability, 3 = Equity, 4 = Income, 5 = Expense.

Usage codes: 1 = Detail (used in postings), 2 = Header (for grouping only, not used in postings).

Set manualEntriesAllowed: false for accounts that should only receive system-generated entries (loan portfolio accounts, interest income accounts). This prevents accidental manual postings that corrupt the GL.

Account Hierarchy

Accounts can be organised into a parent-child hierarchy for reporting purposes. A header account (e.g. "Total Loan Portfolio") can have detail accounts beneath it (e.g. "Personal Loans", "Group Loans", "SME Loans"). The header account shows the aggregate in balance sheet reports; postings only go to detail accounts.

Set the parent when creating a child account:

-d '{
  "name": "Personal Loans",
  "glCode": "1101",
  "type": 1,
  "parentId": 10,
  "usage": 1,
  "manualEntriesAllowed": false
}'

Minimum Required Accounts

Before you can create a loan product, you need at minimum these GL accounts:

Account	Type	Used for
Loan portfolio account	Asset	Outstanding principal balance
Interest receivable	Asset	Accrued but uncollected interest (for accrual-based products)
Fund source	Asset or Liability	Source of disbursed funds (cash, bank, or donor funds)
Loan income account (interest)	Income	Interest revenue recognised on repayment or accrual
Fee income account	Income	Fee revenue
Penalty income account	Income	Penalty/overdue charge revenue
Overpayment liability	Liability	Customer overpayments held pending refund

Before you can create a savings product:

Account	Type	Used for
Savings reference	Liability	Customer savings balances
Savings control	Liability	Clearing account for savings transactions
Interest on savings	Expense	Interest paid to savers
Savings transfers in suspense	Liability	Funds in transit

Loan Product Accounting Mappings

Every loan product has an accounting configuration section. When you create or edit a loan product, you map each event to a GL account:

Mapping	What it does
Fund source	Where disbursed funds come from (debit this, credit loan portfolio)
Loan portfolio	The outstanding principal balance account
Interest receivable	Accrued interest not yet collected (accrual-based products only)
Income from interest	Interest revenue account
Income from fees	Fee revenue account
Income from penalties	Penalty/overdue charge revenue
Losses written off	Expense account for write-offs
Goodwill credit	Expense account for goodwill credits
Overpayment liability	Liability account for customer overpayments

Accounting Method: Cash vs Accrual

Each loan product uses either cash-basis or accrual-basis accounting. This choice drives which accounts are required and how journal entries are posted.

Cash basis: Interest income is recognised when the repayment is received. No interest receivable account is required. Simpler to set up; does not show a full picture of earned-but-uncollected income on the balance sheet.

Accrual basis: Interest income is recognised each day it is earned, regardless of whether it has been collected. COB posts daily accrual entries to the interest receivable and income accounts. Requires an interest receivable account. Provides accurate income recognition for financial reporting.

Most regulated financial institutions are required to use accrual-basis accounting.

Example: Simple Accrual Loan Product Mappings

Assuming this chart of accounts:

GL Code	Name	Type
1100	Loan Portfolio	Asset
1200	Interest Receivable	Asset
1300	Cash at Bank	Asset
4100	Interest Income	Income
4200	Fee Income	Income
4300	Penalty Income	Income
5100	Loan Write-Off Loss	Expense
2100	Customer Overpayments	Liability

Product mapping:

Field	GL Account
Fund source	1300 - Cash at Bank
Loan portfolio	1100 - Loan Portfolio
Interest receivable	1200 - Interest Receivable
Income from interest	4100 - Interest Income
Income from fees	4200 - Fee Income
Income from penalties	4300 - Penalty Income
Losses written off	5100 - Loan Write-Off Loss
Overpayment liability	2100 - Customer Overpayments

When a loan is disbursed: debit 1100 (Loan Portfolio), credit 1300 (Cash at Bank). When COB runs accruals: debit 1200 (Interest Receivable), credit 4100 (Interest Income). When a repayment is received: debit 1300 (Cash at Bank), credit 1100 (principal portion) and 1200 (interest portion).

Charge-off and Write-off Accounting

Charging off and writing off a loan post their own journal entries, and they are distinct events. A charge-off recognises the loan as a loss while keeping it on the books - it can still be recovered, and the charge-off can be undone. A write-off removes the receivable entirely. A loan is often charged off first and written off later, and the write-off entries differ depending on whether a charge-off came first.

The accounts involved

Beyond the basic mappings above, charge-off and write-off use these GL accounts, configured on the loan product under its advanced accounting rules:

Mapping	Type	Used for
Charge-off expense	Expense	Principal of a charged-off loan (the loss)
Charge-off fraud expense	Expense	Principal when the loan is flagged as fraud, used instead of charge-off expense
Income from charge-off (interest)	Income	Absorbs the interest cleared at charge-off
Income from charge-off (fees)	Income	Absorbs the fees cleared at charge-off
Income from charge-off (penalties)	Income	Absorbs the penalties cleared at charge-off
Losses written off	Expense	The loss account for write-offs

Charge-off journal entries

On accrual basis, charging off a loan posts four entries:

Component	Debit	Credit
Principal	Charge-off expense	Loan portfolio
Interest	Income from charge-off (interest)	Interest receivable
Fees	Income from charge-off (fees)	Fees receivable
Penalties	Income from charge-off (penalties)	Penalties receivable

On cash basis there are no receivable accounts to clear, so only the principal moves to the charge-off expense account. The interest, fees, and penalties lines instead reverse the income accounts that were recognised on collection.

If the loan uses capitalized income or buy-down fees, charge-off posts additional entries to unwind the related deferred income, on top of the entries above.

Charge-off by reason, and the fraud flag

The principal debit account is configurable per charge-off reason. Map a reason to a specific expense GL account in the product's charge-off-reason mappings, and the principal of a charge-off recorded with that reason is debited there. If no reason mapping applies, the principal falls back to the product's charge-off expense account - or to the charge-off fraud expense account when the loan is flagged as fraud.

Write-off journal entries

A write-off posts differently depending on whether the loan was already charged off:

• Never charged off: debit losses written off (or a mapped write-off-reason account), and credit the loan portfolio, the receivables, and any overpayment.
• Already charged off: the receivables were cleared and the principal already sits in the charge-off expense account, so the write-off debits losses written off and credits the charge-off expense and charge-off income accounts. It must not re-credit the receivables a second time.

Like charge-off, write-off supports per-reason GL mapping: map a write-off reason to an expense account and the loss is debited there instead of the default losses-written-off account.

Interest accrual after charge-off

What happens to interest after a charge-off depends on the loan's charge-off behaviour (see Progressive Loans): ZERO_INTEREST stops accruing interest after charge-off, ACCELERATE_MATURITY makes all future installments due immediately, and REGULAR continues normal accrual. Interest that had already accrued but was not paid is recognised as charge-off income at the charge-off itself (the interest line above). Accruals are posted by the nightly Close of Business job.

Verifying

A reversal - undoing a charge-off, reversing a write-off, or a reverse-and-replay after an earlier transaction is undone - posts the exact inverse of the original entry. After configuring these mappings, run a charge-off and a write-off on a test loan, then reverse each, and confirm every reversal journal entry mirrors the original in account, amount, and number of legs before you go live.

Savings Product Accounting Mappings

Mapping	What it does
Savings reference	The primary customer liability account (savings balance)
Savings control	Clearing account for in-progress transfers
Transfers in suspense	Funds in transit during inter-account transfers
Interest on savings	Expense account for interest paid to savers
Income from fees	Revenue from savings account fees
Overdraft portfolio control	If overdraft is enabled: liability for overdraft balances
Income from interest	For overdraft products: interest income on overdraft balances
Write-off	Overdraft write-offs

Verifying Accounting After Setup

After creating a product and running a test loan or savings account end-to-end, verify the journal entries:

# List recent journal entries
curl "https://your-instance.finecko.com/fineract-provider/api/v1/journalentries?dateFormat=yyyy-MM-dd&fromDate=2024-01-01&toDate=2024-12-31&offset=0&limit=50" \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:password' | base64)"

Check that:

• A disbursement produces a debit to the loan portfolio account and a credit to the fund source
• A repayment produces debits to cash and credits to the loan portfolio and income accounts in the expected proportions
• Running an accrual (via COB or manual trigger) produces debits to interest receivable and credits to interest income

If entries appear in unexpected accounts, re-check the product's accounting mappings. There is no automatic way to correct historical journal entries - fix the product mapping and re-run any test transactions.

Manual Journal Entries

Some adjustments cannot be handled through product mappings and require direct journal entries: write-backs of over-provisioned amounts, adjustments after data migration, opening balances when migrating from a previous system.

Manual entries require the CREATE_JOURNALENTRY permission and can only be posted to accounts with manualEntriesAllowed: true.

curl -X POST \
  https://your-instance.finecko.com/fineract-provider/api/v1/journalentries \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "officeId": 1,
    "transactionDate": "15 March 2024",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en",
    "currencyCode": "KES",
    "comments": "Opening balance adjustment",
    "debits": [
      { "glAccountId": 10, "amount": 500000.00 }
    ],
    "credits": [
      { "glAccountId": 25, "amount": 500000.00 }
    ]
  }'

Every manual entry requires a comment explaining why it was posted. Manual entries are audited and should be reviewed by a second authoriser in your institution's workflow.

Chart of Accounts Import

For institutions migrating from another system with an established GL structure, the chart of accounts can be imported in bulk via the Mifos Web UI (Administration - Accounting - Chart of Accounts - Import). Prepare a spreadsheet following the Mifos import template format and upload it to create all accounts at once rather than one by one through the API.

Trial Balance and Financial Statements

Once accounting is configured and transactions are flowing, verify the trial balance is in balance:

GET /fineract-provider/api/v1/runreports/Trial Balance Report?locale=en&dateFormat=yyyy-MM-dd

A balanced trial balance (total debits equal total credits) confirms the accounting engine is posting entries correctly. Run this after your first end-to-end test transactions before going live.