Manual journal entries in Apache Fineract

Manual journal entries in Apache Fineract: when branch staff need them and what to control

Branch staff need manual journal entries when a correction, a fee adjustment or a donor-funded posting cannot come from a normal loan or savings transaction. The finance lead's task is to let those entries through without losing control of the ledger. In Apache Fineract, the design question is which entries are allowed, against which general ledger accounts, and who must approve them. Four mechanisms shape the answer. Manual journal entries are free-form debits and credits posted directly to the ledger. Accounting rules limit a posting to preselected or restricted accounts, so a branch cannot choose any account it likes. Compound entries group several debit and credit lines into one transaction that must balance. Reversals post an offsetting entry, so the original posting stays visible in the audit trail.

Each mechanism needs an owner and a boundary. Map every accounting rule to a named purpose, such as fee adjustments or donor fund transfers, and list the accounts it can touch. Decide which roles may post manual entries, which may reverse them, and whether any posting needs a second person to approve it. The Fineract documentation at the platform documentation is the starting point for these permissions, and the README states the platform is multi-tenant, with requests carrying a Fineract-Platform-TenantId header. Confirm how office and tenant scope limits posting rights, so a branch user in one office cannot post to another office's books.

Confirm every screen, permission and endpoint against the 1.x release the client will run before writing the control design. The README states that official releases are created quarterly, so a configuration tested on one release should be retested after each upgrade. Ask the implementation team to show, in the target release, whether maker-checker approval exists for journal postings, which roles can reverse entries, and what the audit record captures. Those answers, not general descriptions of the feature, should set the scope of the work and the test cases that the finance team signs off.

Choosing between manual entries, accounting rules and maker-checker

A one-off correction fixes a mistake that nobody expects to repeat, such as a fee posted to the wrong income account or a suspense balance cleared after reconciliation. A manual journal entry is the usual mechanism because it sits outside the portfolio workflow. Because a manual entry can reach any account the role permits, the control has to come from role design, office scoping and period rules rather than from the form itself. Confirm in your version which roles can post manual entries and whether those permissions can be limited by office.

Mechanism: a manual journal entry whose narrative cites the source transaction, ticket or reconciliation item.
Accounts touched: a short list of correction and suspense accounts, enforced through role and account configuration, if your version supports that restriction.
Ledger evidence: the posting date, user, office, amounts and narrative. Confirm whether the reason is stored in a structured field or only in free text.
Period control: whether a closed period blocks the correction. Plan the reopening route before go-live, not during the first month-end.
Reconciliation link: keep the reconciliation record that justified the entry, since the ledger alone may not show why the correction was needed.

Before go-live, check which roles can post, whether a closed period blocks the entry, and what your reconciliation file needs to show for each correction.

Configuration options and when each fits

This table compares six ways branch and finance staff can post to the Fineract ledger, from free-form manual entries to approval-controlled postings. Read each row by its main control and main risk, then match the option to who posts and how often. The main takeaway is that the more discretion a user has, the more the control has to sit in roles, periods and approvals.

Option	Purpose and typical user	Main control	Main risk
Manual journal entry	One-off adjustments or corrections posted by finance or accounting staff at head office	Office-level period closure and user permissions; confirm which roles can post	Unexplained balances posted by someone with broad access
Accounting rule with preselected debit and credit accounts	Repeatable postings where branch staff should not choose accounts; branch operations	Accounts are fixed by the rule, so staff enter only amount and narrative	A wrong account in the rule misposts every transaction until it is corrected
Accounting rule with restricted account list	Staff choose from an approved set of accounts; branch staff with limited discretion	Only listed accounts can be selected; review the list after chart changes	Lists go stale after chart changes or are too wide to prevent misposting
Compound entry	Several debit and credit lines in one transaction, such as a fee split across income and tax; accountants	Lines must balance before posting; confirm validation behavior in your release	Partial or mismatched lines if the entry is prepared outside the system
Reversal	Undo an erroneous entry with a linked offsetting entry; accounting supervisors	Original entry stays visible; confirm who may reverse and whether a reversal can itself be reversed	Reversing into a closed period, or reversing without posting the correction
Maker-checker on postings	A second person approves a posting before it reaches the ledger; control functions and internal audit	Separate maker and checker roles; confirm whether approval covers journal entries in your release	One person holding both roles, or approval queues cleared without review under volume

Setting up rules and approvals in order

This sequence moves from ledger design to live posting controls, so each control rests on one that already works. Each step closes with a check that shows whether it held. Confirm every setting against the documentation for your installed Fineract release before changing production.

Confirm the chart of accounts and offices
Start by confirming the chart of accounts, the office hierarchy and the currency settings in the tenant you will test first. Export the account list and office tree from Fineract and compare them with the ledger design signed off by finance, so every account a rule can point to already exists and is active. This step is done when finance approves the list in writing and no new accounts are requested during setup. Any account added later in an ad hoc way weakens the control this sequence is meant to build.
Define which roles may post
Map each branch and head office role to the Fineract permissions for creating manual journal entries, reversing them and configuring accounting rules. Keep posting rights separate from rights to change rules, and confirm the role matrix with the people who own the ledger and the people who run the branches. You know this step worked when a test user in each role can perform exactly the actions on the matrix and nothing more. Check this by logging in as each test user and attempting every listed action, including the ones that should fail.
Create rules with fixed accounts
Build the accounting rules that either preselect the debit and credit accounts or limit staff to a short list of allowed accounts. Tie each rule to a specific office or a narrow set of offices where the business needs it, and record the business purpose beside it. The step is complete when every rule has a named owner, a stated purpose and a test entry showing the expected debit and credit lines. Confirm that no rule offers free choice across the full chart of accounts.
Test compound entries and reversals
Post a set of compound entries that touch several accounts in one transaction, then reverse a sample of them and post corrections. Run these tests in a non-production tenant that holds the same account configuration as production, so the tests exercise the actual rules and roles. The step is done when each compound entry produces balanced debits and credits, each reversal restores the starting balances, and the results are saved as a dated test record for the change log.
Enable maker-checker where supported
Check the documentation for your installed release to confirm whether approval workflows for manual journal entries are available and how they are switched on. If the feature is supported, configure a maker role and a separate checker role, then test that a single user cannot both create and approve the same entry. If your release does not offer this control, document a compensating review, such as a periodic listing of manual entries checked by someone outside the posting team. The step is done when the chosen control has been tested with at least one entry that a single user attempts to approve.
Verify journal output against a sample
Select a sample of manual and rule-based entries from the test run and trace each one to its source document, the posting user, the rule applied and the resulting general ledger lines. Compare totals per account and office against an independent extract prepared by finance. The step closes when every sampled entry matches on amount, account, office and date. Log any difference, fix the cause and repeat the sample before the rules go live.

Security controls for branch-level postings

Manual entries are where a single branch user can move money between ledger accounts, so the controls around them need to be designed together. The cards below cover who may post, who must approve, which credentials and transport protect the API, and what the audit record shows afterward.

Maker and checker separation

Maker-checker on postings means one user prepares a journal entry and a different user approves it before it affects the ledger. Confirm that the approval step is enabled for manual journal entries in your Fineract configuration, that the same user cannot both create and approve an entry, and that approvers sit outside the branch teams that originate postings. Test this with two accounts before go-live.

Role-based permissions on posting endpoints

Fineract authorizes API calls by role and permission, so a teller role should not carry the rights to create, approve or reverse journal entries. Review which permissions are granted to each role for manual entries, accounting rule execution and reversal, and remove anything a branch role does not need. Confirm that roles are assigned per office where your structure requires it.

Replace the default development login

The Fineract README documents a default development login of mifos with a password that must be changed for any real deployment. Confirm that the default account is disabled or its credentials are rotated before the environment holds live data, and that no shared administrative credentials are used by branch staff. Store the replacement credentials in your secrets manager, not in deployment files.

HTTPS-only access to the API

Fineract strongly encourages HTTPS only and exposes SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Verify that plain HTTP is refused on every path that reaches the posting endpoints, including through the gateway and any front end, and that certificates are managed and renewed under your control. Check that basic authentication credentials never travel unencrypted.

Audit trail for postings and reversals

Your audit record should show who created, approved and reversed each manual entry, with timestamps and the originating office. Confirm which of these fields Fineract retains in your version, how long your database and logs are kept, and whether reversals appear as new linked entries rather than edits to the original. Export a sample reversal and trace it end to end during testing.

Where manual entries weaken the ledger and how to limit it

Manual journal entries give branch staff a way to post to the ledger outside the portfolio logic that produces most Fineract accounting, and that is the core risk. A manual entry can move money between general ledger accounts without passing through the product accounting rules, financial activity mappings or the transaction flow a loan or savings account would normally follow. The flexibility is useful for corrections and one-off adjustments, but every extra path into the ledger is a path that can skip a control you assumed was in force. Before go-live, decide which roles can post manual entries at all, and which accounts those roles can touch, because the platform's default permissions will not make that decision for you.

The practical limits are restricted accounts, approval thresholds and period closures, and each needs to be tested rather than assumed. Restrict manual posting to a short list of adjustment accounts so that staff cannot reach income, provisioning or liability accounts that portfolio logic should own. Confirm in your own build whether a threshold-based approval step is available for manual entries, and whether it applies to reversals as well as new postings. Closures only help if the period is actually locked for manual entries in your version, so run a backdated test entry after each closure. Confirm the exact behavior of each control against your release and document the result as evidence.

Reversal-based correction is usually the safer pattern. A reversing entry leaves the original posting visible, carries its own date and author, and shows the correction as a separate event that an auditor or reconciler can follow. Editing or deleting a posted entry erases the history that reconciliation depends on, and it can put the ledger out of step with the external system that received earlier exports. Write a short correction procedure that tells branch staff to reverse and repost, names who approves the reversal, and says where the reason is recorded. Ask your implementation partner or the project documentation to confirm which entries can be reversed and how the reversal appears in the journal.

Limits to confirm before you design the posting model

Several Fineract accounting behaviors depend on the release and configuration you run, so the posting model should not be designed until these answers are in writing. Each card below is a question to put to the vendor documentation, a test environment or your implementation partner, and each answer changes who can post what and how the ledger reads back.

Does maker-checker cover journal entries?

Fineract's approval workflow has historically been applied to client and loan transactions, so you cannot assume it also gates manual journal entries. Ask whether a manual entry can be created in a pending state, who can approve it, and whether the approver can edit the amount or accounts before approving. Test this with a branch user and a checker account before you write the control narrative. If journal entries bypass approval, the compensating control has to sit elsewhere in your process.

How accounting rules meet office hierarchy

Accounting rules can be scoped to offices, and the question is whether a rule defined at a parent office applies to entries posted from child offices, and whether a branch user can see or override accounts from outside their own office. Ask for the exact visibility and inheritance behavior in your release, and test it with two sibling branches and one parent. Document the result, because restricted account lists are only as strong as this scoping.

Whether compound entries validate balance

A compound entry groups several debit and credit lines into one posting. Ask whether the system rejects a compound entry whose debits and credits do not equal each other, whether it validates per currency when several currencies are in use, and whether it refuses a line that references a closed or inactive GL account. Try an unbalanced entry in a test tenant. If validation is missing, your procedures need a second check before posting.

How reversals appear in exports

A reversal can be modeled as a new offsetting entry or as a status change on the original, and the two look different to anyone reading an export. Ask which pattern your release uses, whether the reversed entry keeps its original transaction reference, and whether a reversal carries its own date or the original date. Confirm this before you build the ERP feed, since a double-count in the external ledger is hard to unwind.

Performance under high volume

Manual entries add rows to the same journal tables that portfolio postings write to, so reporting and the end-of-day batch can slow as volume grows. Ask the vendor or your partner for the reporting and batch behavior at your expected transaction volume, and whether aggregation or indexing features are required. Load test with production-like data volumes, because test databases with a few thousand rows do not show these effects.

Questions buyers ask about manual journal entries in Fineract

What drives the cost of a manual journal entry setup in Fineract?

The cost is driven by how many roles, accounting rules and approval steps the design needs, and by how much testing the ledger requires before branch staff use it. Each rule that preselects or restricts accounts adds design and test work, because every rule must be checked against the chart of accounts and the financial activity mappings. Maker-checker adds workflow design, role configuration and negative testing. Each external ERP feed adds reconciliation work that has to be scoped separately. A fixed-scope quote is built from these items in writing, so ask for each one to be listed as its own line with its deliverables.

How long does configuring manual journal entries in Fineract take?

Duration depends on the number of roles, the complexity of the accounting rules, the size of the approval matrix and the number of environments that must be tested before go-live. A simple setup with few roles and no external feed takes far less time than one with restricted rules per branch, maker-checker across several levels and a reconciled ERP feed. Your chart of accounts being final before the work starts is the single largest factor in keeping the schedule stable. Ask for a timeline that lists the design, build, test and sign-off phases separately, and confirm which of them depend on your own reviewers.

What do we need to supply before a Fineract journal entry project starts?

Three inputs shape almost every design decision. The first is a finalized chart of accounts with account codes, types and the offices that may post to each account. The second is an approval matrix that states who may create, approve and reverse entries, by amount, account type and office. The third is a set of sample entries covering routine postings, compound entries, fee and tax lines and reversals, with the expected debit and credit lines written out. Your finance team should also confirm the closure and period-locking rules, because they decide which backdated entries are blocked. Missing any of these usually leads to rework during testing.

Can our internal team configure manual journal entries in Fineract without a partner?

Yes, a team with Fineract administration experience and finance staff who own the chart of accounts can configure manual entries and accounting rules without an external partner. The work requires knowledge of the Fineract API, the role and permission model, the accounting mode of each product and the testing discipline needed for ledger changes. Teams without that experience often underestimate the negative testing for restricted accounts and the reversal scenarios. A partner is useful when you need an independent design review, a documented control set for audit readiness or a faster route to a tested configuration. DeployOpen plans and implements these configurations within your own infrastructure.

What ongoing effort does a manual journal entry setup require after go-live?

After go-live, the recurring effort comes from role changes, new accounting rules when products change, month-end reviews of manual entries and testing of each Fineract upgrade. Staff turnover in branches means approval roles must be reviewed on a schedule, and any change to the chart of accounts requires re-testing of the rules that reference the changed accounts. Plan for a named owner who signs off changes and keeps the test cases current. Ask any provider to state whether this support is quoted as a retainer or as a separate change request, and what is included in each.

Which testing effort should a quote for Fineract journal entries include?

A credible quote includes testing of each rule against valid and invalid inputs, negative tests for restricted accounts, tests of the maker-checker flow with rejected and approved entries, and reversal tests that confirm the original and offsetting lines post correctly. Where an external ERP is fed, the quote should include reconciliation tests comparing ledger totals by GL account and office. Ask for the test plan, the test data and the evidence retained for each test cycle. Effort rises with the number of offices, currencies and account types in scope.

How do ERP feeds and approval rules affect the scope of the work?

Each ERP feed adds scope because journal entries must be pulled through the API or consumed as business events, summarized by GL account and office, and reconciled to the ERP ledger. Approval rules add scope because every maker-checker path, escalation and delegation must be designed, configured and tested. Both items often surface late if they were not listed in the initial scope. Confirm with the provider whether the ERP feed and the approval workflow are included in the fixed scope or priced as additional deliverables, and ask which side owns the reconciliation exceptions after go-live.

Does Fineract provide a user interface for manual journal entries?

Fineract is a headless application that exposes REST APIs and does not provide its own user interface. The Fineract README points to the Mifos X web application as a front end used in its Kubernetes example, so branch staff typically use a front end built on those APIs. Confirm with your front-end provider that the screens expose the journal entry and reversal functions you need, and that the maker-checker steps appear in the user flow. Budget for front-end work separately if the existing screens do not cover your approval matrix.

How DeployOpen scopes manual posting controls in a fixed-scope engagement

A fixed-scope engagement for manual posting controls starts with a written scope that pins down six things before any configuration changes: the Fineract release, the posting roles, the accounting rule set, the approval matrix, the test plan and the handover documentation. The release comes first because the behavior of manual journal entries, accounting rules and maker-checker features is tied to the version in use, and the project publishes new stable releases quarterly. The scope should name the exact version, the database platform (PostgreSQL is the project's recommended choice) and the environments in which the controls will be tested and then promoted.

The posting roles, rule set and approval matrix are where most of the agreement effort goes. The scope should list each role that can post manually, which accounts each role can touch, which accounting rules will preselect or restrict accounts, and which entry types require a second person to approve. The test plan should cover normal postings, rejected postings, compound entries, reversals and attempts to post into a closed period, with expected results written down for each case. Handover documentation should describe the configured roles, rules and approvals, the reasons behind them, and the steps an operator follows when a posting is queued or rejected.

DeployOpen prepares these controls and the evidence that shows they work, which can support a compliance assessment, but DeployOpen does not issue audit reports, attestations or certifications. Your internal audit or an independent auditor decides whether the controls are sufficient for your framework. Ask the auditor early which evidence they expect, such as role exports, approval logs and test records, so the scope includes it. Confirm with your own compliance team which framework applies and who signs off the approval matrix before the quote is finalized.

How DeployOpen works on this

DeployOpen plans, builds, documents and supports Fineract posting controls inside infrastructure you control, including your cloud accounts, data centers or air-gapped networks. We start from a written scope that defines which roles can post, which accounts are restricted and how approvals and reversals must behave before any configuration changes are made.

How we scope

Agree in writing which branch roles may post manual journal entries and which accounts each role can touch.
Map every accounting rule that preselects or restricts accounts, with the owner who signs off each mapping.
Define maker-checker, reversal and period-closure expectations for postings before the build starts.
Engagements are fixed-scope, so deliverables and timelines are agreed in writing before work begins.

How we build

Configure manual journal entry roles, office access and account lists in a non-production Fineract tenant first.
Build accounting rules and compound entry templates against your approved chart of accounts.
Test reversals, backdated entries and maker-checker paths with scripted cases that your finance team reviews.
Document each configured control so the test evidence and the design can be traced to one another.

How we hand over

Deliver the configuration record, role matrix, account mapping sheet and test results as written handover documents.
Walk your finance and operations staff through the posting procedure and the exception path for rejected entries.
Confirm with your auditors and compliance team which evidence they need, since DeployOpen prepares evidence but does not issue audit reports.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
Re-test posting controls when Fineract releases are upgraded, using the release notes from the project to scope the regression work.
Review role and account changes against the approved matrix whenever branches, products or staff roles change.

Manual journal entries and accounting rules in Apache Fineract