Cash vs accrual accounting in Apache Fineract

Cash vs accrual accounting in Apache Fineract: which mode each product needs

Finance and operations leads must choose each product's accounting mode before go-live, because it decides when loan and savings income reaches the general ledger. In the design we work from, loan products offer three options: cash based, periodic accrual and upfront accrual. Savings products are cash based. Cash based posting records interest and fees when money moves, while the accrual options recognize income as it is earned over the loan term, with upfront accrual recognizing it earlier. Confirm the exact mode names, the triggering event for each posting and the debit and credit lines for your target release in the Apache Fineract platform documentation before finance signs off the design.

The mode drives three things that finance will check at month end. The first is income timing: the same loan can show interest income in different periods depending on its mode, which changes monthly management reporting and any period-based tax or fee calculation. The second is reconciliation: accrual modes create receivable and deferred balances that must agree with the loan portfolio, so the subledger totals must tie to the control accounts every period. The third is what the external ERP receives. Whatever Fineract posts is what the ERP ingests, so the mode determines the number and type of journal lines the ERP must match. Ask for a trial balance per product for each mode and compare it with the expected entries before the first live disbursement.

Decide the mode with the accounting policy owner, not only with the product team, and record the reason for each product. Test a representative set of loans and savings accounts through a full month, including early repayment, a waiver, a write-off and a reversal, and confirm that each event posts to the accounts you expect. Ask the implementation partner to document the posting behavior of every mode in use and to list what changes if a mode is altered after accounts exist. Confirm with your auditors how the chosen approach will be evidenced, because the mode choice will be one of the first accounting decisions they examine.

Which accounting mode fits which product

This table compares the loan accounting modes (cash based, periodic accrual and upfront accrual) with the savings cash mode, showing what each posts, when it posts, the products it suits and its reconciliation trade-off. Read each row against the Fineract documentation for your target release, and treat every item marked for testing as unconfirmed until you have run it in a non-production environment.

Mode	What posts and when	Products it suits	Reconciliation trade-off
Cash based loans	Interest, fees and penalties post when the borrower pays them. Disbursement and repayments post on the transaction date.	Irregular repayment, short tenors, or income policies that recognize income on receipt.	Simplest tie-out to bank receipts. Schedule income and receivables will not match until payment. Verify overdue presentation in test.
Periodic accrual loans	Interest accrues on a recurring run, so income is in the ledger before cash arrives. Verify the run trigger and frequency in your release.	Amortizing loans where income should follow the schedule, whatever the payment timing.	Accrual and reversal entries must match the schedule and clear on payment. Expect a receivable tie-out each period close.
Upfront accrual loans	Interest and eligible charges for the full term post at disbursement. Verify how later schedule changes adjust the entries.	Short-term products with fixed charges where full income is recognized at origination.	Largest income recognition at origination. Early repayment, restructuring and write-off need reversal entries that must be tested.
Cash based savings	Deposits, withdrawals and interest postings hit the ledger on the transaction date through mapped liability accounts.	Savings and deposit products where balances are customer liabilities and interest is credited on posting.	Ledger liabilities track customer balances at each posting date, which simplifies tie-out. Verify interest and withholding tax timing in test.
Mode per product	Each product carries its own accounting setting, so one general ledger can hold several modes at once.	Organizations running mixed portfolios across short and long tenors.	Confirm each product's mode matches its mappings before go-live, since a mismatch shows up only in the ledger.

What each mode posts over a loan's life

Under cash based accounting, income is recognized when money is received. Disbursement moves principal into the loan portfolio asset against the fund source or cash account. Scheduled interest is shown on the repayment schedule, but the ledger expects interest income to appear when a repayment is collected. Confirm the exact journal lines for each event in your target release before you finalize the mapping.

Disbursement: Principal posts to the loan portfolio account against the fund or cash account. No interest income should post at this point. Confirm with a test loan.
Scheduled interest: Interest due on the schedule should not create a journal entry on its due date. Confirm that the schedule alone produces no ledger postings.
Repayment: Cash received posts to the bank or cash account, with the principal and interest portions posted when the payment is made. Confirm how a partial payment is split between principal, interest, fees and penalties.
Fees and penalties: Fee income should appear when the customer pays, so an outstanding charge should not post to income. Confirm this for each charge type you configure.
Month-end: No accrual entry should run at period end, so monthly income reflects cash collected in that month. Confirm this in the trial balance after a test month-end.

Check that a missed repayment leaves no income or receivable entry in the closed period and that the trial balance agrees with the loan portfolio report.

How the mode changes income recognition

Each card is a decision the finance team owns. The accounting mode sets when Fineract posts income, but the lender's policy and the auditor's view decide whether that timing is acceptable, so both must be agreed before configuration.

Timing of interest income

Under periodic accrual, interest is recognized across each schedule period as it is earned, so a month-end close picks up interest the borrower has not yet paid. Under cash based, the same interest is recognized when the borrower pays. Upfront accrual recognizes the expected interest for the full loan term at disbursement. Choose the mode that matches your policy, then run one loan through two month-ends and confirm the postings match your expectation.

Fees and charges timing

Loan fees and penalties follow the accounting mode of their product, which can differ from the timing of the interest they sit beside. Decide whether an upfront fee is income on disbursement, on collection, or spread over the term, and whether penalties are recognized only when paid. Tax on fees adds separate journal lines that must follow the same timing. List every charge type with its expected posting date before configuring any product.

Early repayment and write-off effects

An early repayment under periodic accrual can release interest recognized in earlier periods, which moves income between months. A write-off stops future accrual but must clear the receivable and reverse any income already booked. Upfront accrual can make these adjustments larger because more income sits in the ledger from the start. Agree how reversals will be treated before the first loan closes, and test a full early repayment and a write-off in a non-production environment.

Savings interest recognition

Savings products are cash based, so interest on savings posts when it is credited to the account, typically on a scheduled posting date. The ledger shows nothing for interest until that credit happens. Ask the finance team whether interest owed to depositors must be accrued at period end for their own statements, and whether withholding tax on that interest is posted on the same date. Confirm both before the first savings posting run.

Lender policy and auditor sign-off

The lender's accounting policy and the external auditor's view decide which mode is acceptable, and Fineract applies only the mode you configure. Record the policy on income timing, fee treatment, write-offs and reversals as a signed document, and share it with the auditor for comment. Changing modes after loans are booked becomes a data and accounting migration project, so agree the policy before configuration begins.

Setting the accounting mode per product before go-live

This sequence takes each Fineract product from an agreed accounting mode to a tested ledger, so the team can prove that cash, periodic accrual and upfront accrual postings land in the right accounts before any customer money moves.

Confirm the chart of accounts and mode per product
Finance and the implementation lead agree the general ledger chart and record, for each loan and savings product, whether it uses cash based, periodic accrual or upfront accrual accounting. The output is a signed product matrix listing each product, its mode, the income and receivable accounts it touches, and the owner who approved it. Confirm with your auditors and finance policy owners that the chosen modes match your revenue recognition policy before configuration starts. Designing the chart itself is covered in the sibling pages on financial activity mappings and payment types.
Configure product modes and account mappings on a test tenant
An administrator sets the accounting mode on each loan and savings product in a non-production tenant and maps every product account to a general ledger account, including receivable, income, fee and penalty lines. Financial activity mappings for transfers between savings and loans are configured at the same time, using the detailed guidance in the sibling mappings topic. The output is an exported configuration record that the reviewer can compare with the product matrix. Any mapping that does not match the matrix is corrected before the next step.
Post sample loan and savings transactions
The test team creates clients, then runs representative loans and savings accounts through disbursement, scheduled repayments, a fee, a penalty, an early repayment, interest posting and a withdrawal. Each product mode should be exercised, including loans with upfront accrual and periodic accrual, so the team sees how each mode posts. The output is a list of test accounts with their transaction IDs and expected journal lines written down before posting. Keep the test data labeled as illustrative and separate from any migrated balances.
Check the journal entries against expected postings
A finance tester reviews the journal entries produced by each sample transaction and compares every debit and credit with the expected line written in the previous step. Upfront accrual postings are checked for the full amount at disbursement, and periodic accrual postings are checked for each accrual date. The check passes only when each entry matches the expected accounts, amounts and dates, and any gap is traced to a mapping or product setting. The output is a signed exception log, with zero open differences before the team moves on.
Run end-of-day and month-end routines
The operations lead runs the close of business day routine across several business dates, then runs the month-end routine that accrual and closure processing depends on. Accrual postings for each period should appear in the ledger on the expected dates, and the team confirms that the routines finish without errors in the job log. Period locking and backdated entries are configured and tested using the sibling closures topic. The output is a dated run record for each routine, showing the start, finish and status of each job.
Reconcile the ledger to expected balances
Finance prepares a trial balance for the test tenant and reconciles the receivable, income and fee accounts to the subledger balances for each product, using the expected figures from the test script. Differences caused by rounding, timing or missing mappings are recorded and resolved before sign-off. The output is a reconciliation workbook with a trial balance that agrees to the subledger, and a sign-off from the finance owner and the implementation lead. Only products that reconcile in this test move to the production configuration.
Freeze the configuration and record the sign-off
Once every product reconciles, the team exports the final product and mapping configuration, records the accounting mode of each product in the change record, and requires a second approver before the configuration is promoted to production. The output is an approved configuration baseline and a written decision record that states which mode each product uses and who approved it. Later changes to mode or mapping go through the same approval path, so the baseline stays the reference during audits and upgrades.

Reconciling loan subledgers and the ledger when modes differ

When products use different accounting modes, the month-end reconciliation stops being one comparison. Loan portfolio balances, accrued receivables, income postings and savings liabilities no longer move on the same recognition timing, so a single ledger total can agree while individual products are out of step. Plan the reconciliation per product and per office, and treat each mode as its own set of expected balances. A cash-based loan product, a periodic accrual product and an upfront accrual product will show different relationships between the loan subledger, the receivable accounts and the income accounts at the same date.

Start by mapping each balance the close must prove: outstanding principal and interest in the loan portfolio, accrued interest receivable, deferred or recognized fee income, and savings liabilities for cash-based deposit products. For each one, record which product mode produces it, which financial activity mapping and GL accounts it posts to, and at what point in the period the posting occurs. Ask the implementation team to write this down as a reconciliation matrix before go-live, because the matrix is what the reviewer will test against. If a product changes mode later, the matrix must show how balances from before and after the change will be explained.

An external ERP or a batch close job may depend on the mode in ways that are easy to miss. A consumer that sums postings by GL account and office will see timing differences that are correct under the configured mode but look like errors to someone who expects cash-basis figures. Confirm with the vendor and in your own test environment which reports, trial balance views and journal entry extracts the target release provides, how they filter by office and product, and whether any of them are affected by backdated entries after a close. Do not assume a report shows what your reconciliation needs until you have compared its totals with a hand-built expected figure.

Controls that protect the accounting mode settings

Accounting mode decisions sit behind product configuration, so the controls that protect them are the same ones that protect the ledger: who can edit products, how changes are reviewed, what is logged, and how changes are tested first. Each control below addresses a different way a mode change can reach live books.

Restrict who can edit product accounting

Accounting mode and account mappings are set on each loan and savings product, so anyone with permission to edit those products can change how income is recognized. Confirm which Fineract roles can create or update products, and keep that list short and separate from roles that process transactions. Ask the vendor or your own environment team to confirm exactly which permissions cover product accounting fields, since role granularity should be verified in your deployment before you rely on it.

Review before changing live products

A second approver should review every mode change before it is applied to a product that already has active accounts. The review should state the current mode, the proposed mode, the GL accounts affected and the expected effect on income and receivable balances for existing and new accounts. Keep the review record with the change request so auditors can trace who proposed and who approved the change.

Audit trails for configuration and postings

Export and retain the record of product configuration changes and the postings they generate, so you can show which mode applied on any given date. Check that the audit data covers the product, the user, the timestamp and the before and after values. Confirm with the vendor how long audit records are retained in your version and whether they can be exported without database access.

Test mode changes in a non-production tenant

Fineract is multi-tenant, so a separate non-production tenant lets you apply a proposed mode to a copy of a product and run representative loans through disbursement, accrual, repayment and close of business. Compare the journal entries against the expected postings for each mode before the change reaches production. Keep test data realistic in structure but free of client personal data.

Effect of changing a mode after accounts exist

A mode change usually applies to new postings, not to history, so accounts opened under the old mode keep their earlier entries and may carry balances that the new mode would treat differently. Decide in advance whether existing accounts keep the old mode, move to the new mode, or are closed and reopened. Confirm with the vendor how the platform handles an in-flight accrual when a mode changes, and reconcile both ledgers before and after the change.

Supporting authentication and HTTPS controls

Product changes travel over the API, so authentication and transport protection matter. Replace the development default login before any real use, and serve Fineract over HTTPS only, using the SSL settings such as FINERACT_SERVER_SSL_ENABLED. Segregation of duties between configuration, approval and posting roles is set by your own governance, not by the platform, so document it in your control framework.

Questions teams ask about cash and accrual modes in Fineract

Can we change the cash or accrual mode after go-live?

Treat the mode as a decision to make before go-live, because changing it on products that already hold accounts affects how existing balances and income were recognized. Ask DeployOpen or your own Fineract team to test the product setting on a copy of production-like data, and check how the platform handles accounts opened under the old setting. The Fineract platform documentation is the starting point for the configuration options, but it does not replace a test. Any change after go-live needs a written cutover plan, a period close that your controller signs off, and your accounting firm's view on whether prior periods need adjustment. Confirm the exact behavior for the release you deploy, since settings can differ between versions.

What makes an accrual setup take more effort than cash based?

Effort rises with the number of products that use accrual, the number of modes running side by side, the number of ledger accounts each product posts to, and whether the general ledger feeds an external ERP. Each accrual product needs mapped income, receivable and suspense accounts, test cases for every schedule event that posts, and reconciliation checks showing that accrued and received amounts agree. Mixed modes add test combinations because products in different modes can share accounts, charges and fund sources. Historical data adds more work, since opening balances must move into the new mode without double counting interest already recognized. An ERP feed adds mapping and reconciliation work on the other side. Ask any provider to break its estimate down by these drivers.

What must our team provide before a Fineract accounting build starts?

Your team should supply a finished chart of accounts, a written accounting policy that states the income recognition choice for each product, and test cases tied to real scenarios such as a repayment, a late payment, a waiver and a write-off. You also need named owners who can approve mappings, a test environment with representative data, and a decision on who signs off the trial balance. Gaps in the chart of accounts or policy usually surface during testing, when rework is most expensive. DeployOpen plans most engagements as fixed scope, so these inputs should be agreed in writing before work starts. Ask the partner to list every input it depends on and what happens if one arrives late.

Can our internal finance or IT team configure cash and accrual modes themselves?

Often yes for simple setups, but the work spans configuration, ledger mapping, testing and close operations, so the team needs skills in all four. Product settings are the easiest part. The harder work is verifying every posting against the policy, running the close of business day job and troubleshooting it, and reconciling the ledger to the ERP each month. Fineract does not provide its own user interface, so the team also needs to plan how staff and reports reach the platform through its APIs. The project's README notes that production deployments can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. Assess the team against the test plan before deciding.

How long does a Fineract accounting implementation take?

The timeline depends on scope, so no fixed duration applies across projects. The main variables are the number of products and modes, the ERP integration, the volume of historical data, and how quickly your team approves mappings and test results. Testing often takes the longest, especially when month-end and year-end routines must be rehearsed. Large deployments add run time: the README notes that the Close of Business Day job can run for several hours on deployments with millions of accounts, so test cycles on production-scale data need planning. Ask for a written schedule tied to the agreed scope, with dependencies on your team's reviews and sign-offs, and confirm what the stated timeline includes.

What must an accounting firm or auditor confirm about our accrual setup?

The accounting firm or auditor confirms that the accounting policy and posted entries match the reporting framework you follow, and that income recognition follows the stated policy. They will examine mappings, period treatment, reconciliations, and evidence of testing and approvals. DeployOpen prepares systems, controls and evidence for assessments, but it does not issue audit reports, attestations or certifications. An independent auditor must reach its own conclusions. Ask your auditor early which framework applies, which journal entries it will sample, and what evidence of maker-checker approvals and period locks it expects. Agree on the evidence format before the build so the records are kept during testing.

How do accrual entries reconcile with an ERP general ledger?

Reconcile by GL account and office for each period, comparing Fineract ledger totals with ERP totals and explaining every difference. Accrued income that has not been received sits in receivable accounts, so the ERP needs the same accounts and timing as Fineract. Check that accrual and reversal entries pair up, that charges and waivers post once, and that backdated transactions appear correctly after a period close. Feeding the ERP can happen by pulling journal entries through the API or by consuming business events, which Fineract can publish to ActiveMQ or Kafka but has disabled by default. Each method needs its own tested reconciliation. Keep a difference log with owners and dates so the controller can explain open items before close.

Limits to confirm in your environment

Cash and accrual behavior in Fineract depends on the exact release, the product configuration and how your ledger is used downstream. The cards below list the items to confirm with the vendor documentation, a test tenant or your lender's accounting team before any product goes live.

Accounting mode names and behavior

Confirm the exact accounting mode options offered for loans and savings, and what each one posts, in the Fineract release you will run. Mode names and posting rules can differ between releases, so do not rely on older tutorials or forum posts. Ask the team that owns your accounting design to sign off the posting table for each product type. Confirm this against the release documentation for your version and a test tenant.

Changing mode on live products

Confirm whether an accounting mode can be changed on a product that already has accounts, and what happens to balances, pending accruals and open schedules if it is. Many teams assume a mode switch is a configuration edit, but the effect on existing loans and savings can be material. Ask the lender's accounting team to define the rule they will accept before any change, and test the change on a copy of production data.

Backdated transaction posting

Confirm how a backdated repayment, interest run or reversal posts under each mode, including whether it reopens earlier periods or lands in the current one. The answer decides whether your reconciliation holds after a close. Check this with a test tenant, using a transaction dated before a closed period, and record the journal lines produced. Ask your accounting team which result they require.

Multi-currency and tax interaction

Confirm how the chosen mode interacts with product currency settings, rounding and tax components on fees, penalties and withholding tax on savings interest. Accrual lines for tax can post separately from the principal and interest lines, which changes what reconciles to what. Test a product in each currency you run with a tax component attached, and confirm the resulting journal lines with your tax and finance owners.

Reporting outputs for reconciliation

Confirm which reports and API outputs show accrued income, received income and receivable balances by product and office, and whether they can be matched to the subledger totals. Without this, the reconciliation between the loan book and the general ledger cannot be evidenced. Ask the vendor documentation which endpoints and reports exist in your release, then run a month-end test on a test tenant and compare totals with the lender's accounting team.

How DeployOpen works on this

DeployOpen treats accounting mode as a design decision that is settled per product before any loan or savings product is configured in Apache Fineract. We scope the mode, map every posting it produces to general ledger accounts, and build and test the configuration inside infrastructure you control, then document it so your finance and operations teams can run it.

How we scope

We list every loan and savings product and record the accounting mode each one needs, with the reason.
We agree which income events, such as interest, fees and penalties, must be recognized on which dates.
We confirm the reconciliation owner and the external ERP or reporting figures each mode must tie to.
Engagements are fixed-scope, so the written scope names the products, GL accounts and tests covered.

How we build

We configure accounting mode per product in a non-production tenant and record each setting in a change log.
We build the financial activity and product-to-GL mappings that each chosen mode depends on.
We test sample loan and savings lifecycles end to end, including repayments, write-offs and reversals.
We check that journal entries from each mode balance and that trial balances match the expected postings.

How we hand over

You receive a per-product accounting mode register with posting timing, GL mappings and the rationale for each choice.
Your finance team receives a reconciliation runbook covering subledger, GL and ERP tie-out steps.
We walk your operations and finance staff through test cases so they can repeat them after go-live.
Configuration and documentation are stored in your own repositories and environments, not ours.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer when mode changes are needed.
We can review accounting mode changes before they reach production, so posting impacts are assessed first.
Fineract release upgrades are planned against the project's quarterly release and end-of-life policy.
Confirm with your auditors which evidence they expect from accounting configuration before the build starts.