Apache Fineract write-off: what it changes for a bad loan
A lender whose delinquent loans keep building up needs a documented way to stop accruing interest, record the loss and collect what remains afterward. Apache Fineract supports write-off and undo write-off, recovery payments after a write-off, charge-off on newer loan types, interest waivers and foreclosure, and each of these posts its own accounting effect. Teams should not treat them as interchangeable labels for "bad debt." Each action changes the loan balance, the income recognized and the ledger entries in a different way, so the choice belongs in the credit policy before the first loan goes into arrears.
The exact behavior depends on the loan type and the Fineract release the client deploys. Write-off and recovery handling are documented per product and per release, and the newer charge-off behavior applies to specific progressive loan types, so a method that works on a standard loan may not carry over. The current stable release is 1.15.0, but the release in production is the one that matters. Confirm each action's preconditions, balance effects and journal postings against the Apache Fineract platform documentation for your version, then test them on a copy of your own product configuration.
Before go-live, ask your team to write down four things: which events trigger each action, who holds the permission to post it, which GL accounts each action debits and credits, and how a finance team would reverse an incorrect write-off. Run a full cycle in a non-production tenant: write off a loan, record a recovery payment, undo the write-off and check the trial balance after each step. Documented outcomes from that test become the evidence your auditors and finance leads will ask for later.
Which write-off, recovery, waiver and foreclosure action fits each bad loan
This table compares six actions for bad or closing loans, from write-off to foreclosure, by trigger, loan type, effect on the balance and schedule, reversal, and permission. Use it to narrow the options, then confirm each behavior against the Fineract version and loan product you run before you rely on it in a process.
| Action | Typical trigger | Loan types and effect on balance and schedule | Reversal and permission |
|---|---|---|---|
| Write-off | Balance judged unrecoverable in the normal course, often after prolonged arrears | Removes the outstanding balance from active reporting and posts accounting entries. Confirm which loan types support it and how the schedule closes. | Can be reversed with undo write-off. Restricted action; confirm the role and approval flow. |
| Undo write-off | Write-off posted in error, or the lender reverses its decision | Returns the balance to the loan so arrears tracking resumes. Confirm which accounting entries reverse with it. | This is the reversal of write-off. Requires the same permission as write-off; confirm in your roles. |
| Recovery payment after write-off | Borrower or guarantor pays part of a written-off balance | Records cash against the written-off amount and posts recovery accounting. Confirm how the payment splits across principal, interest and fees. | Reversal follows your repayment reversal process; confirm. Confirm whether a separate recovery permission applies. |
| Charge-off | Lender stops recognizing income on a progressive loan balance under its policy | Documented for newer loan types such as progressive loans; confirm eligibility, accrual effect and schedule impact in your version. | Confirm whether charge-off can be undone before relying on it. Confirm which loan action and roles apply. |
| Interest waiver | Lender forgives accrued interest, often as part of a hardship or restructuring decision | Reduces accrued interest outstanding. Confirm whether future interest accrual and the schedule change on your loan type. | Confirm whether a waiver can be reversed in your version. Requires the waiver permission; confirm approvals. |
| Foreclosure | Borrower settles the full outstanding balance early, or the lender closes the loan at settlement value | Closes the loan and clears principal, interest and charges. Confirm how interest is calculated to the foreclosure date for your product. | Confirm reversal rules in your version. Requires repayment or foreclosure permission; confirm in your roles. |
What accounting each Apache Fineract write-off action posts
The point of this section is that each write-off action moves a different set of balances, so the journal output differs by action and must be reviewed one action at a time. A write-off in Fineract moves the outstanding principal, interest, fee and penalty amounts that the write-off covers out of the loan's receivable balances and into the write-off accounting, so the loan's outstanding amounts drop to zero while the expense is recognized. An undo write-off reverses that posting, returning the balances to the loan and reversing the entries. A recovery payment after write-off posts cash received against amounts previously written off, which is recorded differently from a normal repayment because the receivable is already cleared. Charge-off on newer loan types and interest waivers and foreclosure each post their own combination of principal, interest, fee and penalty movements, so the reader should map every action to the balances it touches before relying on any summary.
The actual account mappings come from your own chart of accounts and the accounting configuration on each loan product. Fineract posts to the GL accounts you map to the relevant product and transaction types, so the same action can hit different expense, receivable or income accounts depending on how the product is set up and whether accrual or cash accounting mode is in use. Confirm the accounting mode, the mapping for each balance type, and the write-off expense account with your finance team before any loan is moved into production. Do not treat any example entry as the posting your deployment will produce.
Before go-live, run each action on a test loan in a non-production tenant, including a full write-off, an undo, a partial recovery and any waiver or foreclosure path your products allow. Export the journal entries and check that debits and credits balance, that the right accounts move, and that the loan and GL balances agree at each step. Have the finance team sign off on the output for each action, and repeat the test after any change to product accounting or chart of accounts, because the mappings are the part of the setup most likely to drift silently.
Decisions to settle before configuring write-off in Apache Fineract
Write-off changes what the lender reports as loss, what the ledger holds, and what a later recovery can reverse, so these decisions need owners before anyone touches a loan product. The cards below are independent, but they share one question: who decides, and what evidence will an auditor be shown afterward.
Overdue threshold for write-off
Set the number of overdue days after which a loan is eligible for write-off, and document how it relates to your non-performing asset rules. Fineract does not decide this for you, so the threshold is a policy input the product configuration and reporting must match. Confirm whether the threshold is applied per product, per branch or per portfolio, and who reviews exceptions. Credit risk policy should own this number, and finance should confirm the reporting treatment that follows from it.
Approval authority for write-off
Decide which roles may propose a write-off, which may approve it, and whether approval happens inside Fineract or in a case file outside it. Write-off removes a receivable from the active book, so the approver's identity must be traceable in the audit trail. Agree the approval threshold by amount if your policy uses one. The chief credit officer or equivalent should own the approval matrix, with internal audit reviewing it.
Interest accrual after write-off
Decide whether interest keeps accruing on a written-off balance, is suspended, or is waived at the point of write-off. Each choice posts different entries and changes the income figure reported for the period. Check how your chart of accounts separates interest receivable from principal before you map the write-off to ledger accounts. Finance and accounting policy should own this decision, and the controller should confirm the entries with the reporting team.
Recovery allocation rules
Define how money received after write-off is split between principal, interest, fees and penalties, and which of those components is recognized as recovery income. The split affects the recovered amount reported to the board and to any regulator that tracks loss recovery. Confirm the order of allocation with your repayment strategy before recoveries begin. The collections lead and the finance controller should agree the split in writing.
Undo write-off controls
Decide who may reverse a write-off, what evidence must accompany the reversal, and how long after the write-off a reversal is allowed. An undo changes the balance and the ledger position of a closed matter, so an unrestricted undo weakens the audit record. Restrict the permission in the role model and log each reversal with a reason. Internal control or risk should own the undo rule, and the security team should confirm the permission assignment.
Handling progressive and newer loan types
Decide whether progressive loans, and any other newer loan type in your product catalog, follow the same write-off and charge-off path as standard loans or need separate rules. Newer types can carry features such as tranches or contract termination that change which balance is written off. Test each loan type's write-off and recovery sequence in a non-production tenant before approving it. The product owner and the Fineract administrator should own the test sign-off.
How to configure write-off and recovery in a test tenant
This sequence runs each bad-loan action in a non-production Fineract tenant so the team can see the schedule and journal effects before any production configuration is approved. It ends with recorded evidence that the accounting and loan states match the design.
Confirm release and loan types in scope
Record the exact Fineract release the test tenant runs, and list each loan product that will be tested for write-off, charge-off, recovery, interest waiver and foreclosure. Confirm which of these products are standard loans and which are progressive loans, because charge-off and some related actions depend on the loan type. Check the release notes and the platform documentation for the features your version supports. The step is done when the scope list, release identifier and product names are signed off by the business owner and the implementer.
Map the accounting for each action
For every action in scope, write down the expected debit and credit accounts, the GL codes in the chart of accounts, and whether the action posts journal entries or only changes loan status. Include the provision and income reversal effects where your design uses them. Confirm the mapping against the accounting section of the platform documentation and with your finance team. The step is done when a one-page mapping table exists for each action and finance has approved it before any test data is created.
Create a test loan with arrears
In the test tenant, create a client, a loan account on the chosen product, and a disbursement. Then allow or record missed repayments so the loan shows overdue installments and penalty or charge accrual where the product defines it. Export the repayment schedule and the loan summary. The check is that overdue amounts, days in arrears and the outstanding balance match a manual calculation from the schedule before any write-off action is run.
Run write-off and charge-off actions in turn
Run the write-off action on the test loan, then, on a separate loan created for the purpose, run charge-off if the product supports it. Run one action per loan so the effects are isolated. After each action, check the loan status, the transaction list, and the journal entries generated for the office. The check is that the posted entries match the mapping from the earlier step, including any reversal of accrued interest or provisions, and that no unexpected entries appear.
Verify schedule and journal after each action
After every action in the previous steps, reconcile three views: the loan schedule, the loan transaction history, and the general ledger journal entries for the date. Record the balances in each view as a row in a test log. Compare the totals so that debits equal credits and the loan outstanding balance agrees with the written-off or charged-off amount. A discrepancy is a defect to be resolved in configuration or with the vendor, not a reason to adjust the balance by hand.
Test undo write-off and a recovery payment
On the written-off test loan, run the undo write-off action and confirm that the reversal entries mirror the original write-off and that the loan returns to its prior arrears state. Then, on a second written-off loan, post a recovery repayment and check how it is allocated across principal, interest and fees, and which GL accounts receive the cash and the recovery income. The step is done when the undo leaves the ledger in its pre-write-off state and the recovery entries match the mapping for recovery payments.
Record results as acceptance evidence
Compile the mapping tables, the test loan identifiers, the screenshots or exports of each schedule and journal view, and the reconciliation log into one acceptance pack. Include the release identifier and the date of each run, and have the business owner, finance lead and implementer sign each action as passed or failed with notes. Keep the pack with the configuration change record so the same tests can be repeated after an upgrade. The step is done when every action in scope has a signed result and open defects are logged.
Security and control risks in write-off, waiver and foreclosure
Write-off, waiver and foreclosure change what a loan is worth on the books and what a borrower owes, so they need stronger controls than routine repayments. The cards below cover the people, interfaces and reports that carry those risks, and the settings in your own Fineract deployment that you should confirm before go-live.
Separating write-off and approval duties
The officer who waives a charge or writes off a balance should not be the person who approves it. Fineract's permission model lets you grant write-off and approval rights to different roles, so map each step to a separate role and test that one user cannot complete both. Check the role assignments in each tenant, since a single broad administrator role can defeat the split.
Auditing who ran an undo
An undo of a write-off reverses a decision that finance has already reported, so the record of who ran it matters as much as the action itself. Confirm which audit records Fineract keeps for write-off and undo transactions, including the acting user and timestamp, and whether your deployment exports them to a log store you control. Test an undo in a non-production tenant and check that the trail is complete.
Detecting silent interest waivers
A waiver that reduces accrued interest can be entered without any change to the principal or the visible schedule, so it may pass unnoticed. Define which waivers need a second review, and report waiver transactions by officer and amount each period. Confirm with your implementation team how waiver postings appear in the ledger so the report and the journal match.
Securing write-off permissions in the API
The write-off and waiver actions are available through the REST API as well as through the web front end, so a control applied only in the user interface can be bypassed. Restrict the API clients and service accounts that can call these endpoints, and review which OAuth2 clients or basic authentication users hold those permissions. Apply the same role rules to both channels and test them with direct API calls.
Hardening access and changing default logins
A development deployment ships with a default login that must be changed before any real use. Before go-live, replace the default credentials, decide whether OAuth2 or HTTP basic authentication fits your identity setup, and enforce HTTPS only using the SSL settings in the environment configuration. Confirm that no environment variable or test account still exposes the default login on any tenant.
Protecting finance and risk reports
Write-off balances, recoveries and waivers feed the reports that finance and risk rely on, so changes to those figures must be traceable and access must be limited. Decide who may run and export these reports, and confirm that report outputs can be reconciled to the transactions behind them. Review report access on the same schedule as the permission matrix.
What does Apache Fineract write-off setup cost and how long does it take?
What drives the cost and effort of configuring write-off and recovery in Fineract?
The main drivers are how many loan products are in scope, how many of them need write-off, recovery or charge-off behavior, and how much of the accounting setup has to be designed alongside them. Each loan type adds its own test cases, because write-off, undo write-off, recovery payments, interest waivers and foreclosure each post different accounting entries. Effort also rises when the lender has no written rule for when a loan is bad, since someone has to define that before the configuration can be tested. No public figure for effort is supplied here, so ask any provider for a breakdown by product and by transaction type before accepting a quote.
Can our team set up write-off and recovery in Fineract without a partner?
Yes, a team with Fineract experience and access to a test environment can configure and test these features in-house. The work requires someone who understands the loan lifecycle, the chart of accounts mapping and the Fineract REST API, and who can verify postings against finance's expected journal entries. The Fineract README warns that production deployments can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide, so teams without that experience often under-estimate the testing. A partner is most useful when the team lacks that experience or the deadline is fixed.
What does the lender need to provide before setup work starts?
The lender needs to supply a written credit policy that defines when a loan is written off, who approves it and what recovery activity is expected afterward. Finance must confirm the accounting treatment for each transaction type, including which general ledger accounts receive write-off, recovery and interest waiver entries. The work also needs a non-production environment with a copy of the configuration, plus sample loans in each relevant state, such as overdue, written off and partially recovered. Without these inputs, the configuration can be built but cannot be signed off.
How does write-off and recovery work interact with the accounting setup?
Write-off and recovery post journal entries, so they depend on the accounting mode, the GL account mapping and the chart of accounts already configured in Fineract. A mistake in one mapping can make a write-off post to the wrong account, and that error appears in the ledger rather than in the loan screen. For this reason, the accounting design should be settled before loan behavior is tested, and every write-off scenario should be reviewed against the expected journal entries. Confirm the exact postings for your Fineract version in the platform documentation before you agree the design.
Is write-off and recovery setup a one-time task or ongoing work?
The initial configuration and testing is one-time work, but several parts recur. Credit policy and product rules change, so the configuration needs review when they change. Each Fineract release can alter behavior, so regression testing of write-off postings is needed before any upgrade goes live. Finance may also need periodic reconciliation checks of recovery postings against the ledger. Ask any provider whether these recurring checks are included in the fixed-scope work or sold as a separate retainer.
What should we ask for in a fixed-scope quote for this work?
Ask for the scope written as a list of loan products, transaction types and accounting entries, with a test case for each one. The quote should state what the lender must supply, such as the credit policy, the GL mapping and the test loans, and what happens if those inputs arrive late. Confirm the acceptance criteria, who signs off the postings, and whether the fee covers defect fixes after go-live. Also ask how the work handles a later Fineract release, and whether any upgrade testing is included or priced separately.
How are later Fineract releases handled after write-off setup is done?
Fineract publishes official releases quarterly, at the end of each quarter, and archives end-of-life releases, so the configuration will eventually need an upgrade. Each upgrade should run the full set of write-off, undo write-off, recovery, charge-off and foreclosure test cases against a non-production copy before production is touched. Check the release notes for changes to loan transaction handling and accounting postings, since those can change expected results. Agree in the quote who performs upgrade testing and whether it falls under a support retainer.
Limits to confirm in your Fineract version and environment
Write-off, charge-off and recovery behavior depends on the exact Fineract release, the loan types you configure and how your environment runs batch jobs and tenants. The cards below list the items to confirm in the documentation, the source repository or a test tenant before any of the planned behavior is treated as settled.
Charge-off support by loan type
Charge-off and recovery are not available uniformly across every loan type, and newer loan types may behave differently from the classic loan product. Confirm, for the release you deploy, which loan types expose charge-off, which accept recovery payments after write-off and which only support a plain write-off. Record the answer per product, because a product-level gap changes the process your collections team can follow. Ask for the result in writing as part of the design sign-off.
Undo write-off per product
Undo write-off reverses a decision that has already posted accounting entries and changed loan status. Test it on each loan product in a test tenant, including a loan that has received a recovery payment, to see whether the balances, schedule status and accrual entries return to the expected state. A reversal that is possible for one product can leave residual postings on another, so treat each product as a separate test case.
Batch processing of written-off loans
The end-of-day batch job runs for several hours on large deployments, and written-off loans may still be picked up for interest, penalty or status steps. Confirm in a test environment whether the Close of Business job skips, accrues or reprocesses written-off accounts, and how that interacts with your planned accounting run. Measure the job duration with a realistic account count on your own infrastructure, not with a sample database.
Accounting mapping coverage
Every write-off, recovery, waiver and foreclosure transaction must map to a general ledger account, or the posting fails or lands in an unexpected account. Generate each transaction type in a test tenant and compare the journal entries with your chart of accounts. Check the mapping for reversals and for any recovery split between principal, interest and fees, because gaps often appear in those secondary entries.
Recovery records across tenants
Fineract resolves each request to a tenant through the Fineract-Platform-TenantId header, and tenant connections come from a tenants database. Confirm that recovery payments, collection notes and any custom data tables for recovery are scoped to the correct tenant, and that a request under one tenant identifier cannot read or change another tenant's records. Run this check with two test tenants and tokens scoped to each one.
Release and end-of-life effects
Fineract publishes official releases quarterly and archives end-of-life releases, so write-off behavior you validate today may change when you upgrade. Read the release notes for each planned upgrade, rerun your write-off and recovery test cases on the new version, and set a rule for when your deployed release leaves support. Plan the retest as part of each upgrade, not as a separate project.
How DeployOpen works on this
DeployOpen plans, configures and hands over Fineract write-off, charge-off and recovery handling inside infrastructure you control, starting from your written loss policy and accounting model. Each engagement is fixed-scope, so the write-off paths, recovery rules and ledger mappings you need are agreed in writing before any configuration begins.
How we scope
- We map your bad-loan policy to the write-off, undo, recovery, waiver and foreclosure actions Fineract supports on each loan type.
- The written scope lists which loan products, charge-off behavior and recovery flows are covered, and which are excluded.
- We document each accounting entry your ledger must receive, agreed with your finance team before configuration starts.
How we build
- We configure products, GL mappings and permissions in a non-production tenant, then test write-off and undo write-off end to end.
- Recovery payment tests cover allocation after write-off, confirming which ledger accounts each receipt posts to.
- We verify waiver and foreclosure postings against expected journal entries and record the results as test evidence.
How we hand over
- You receive configuration records, a test log, runbooks for write-off approvals and reversals, and the ledger mapping document.
- Operators are trained on the actions that change balances, with the approval steps and who may perform each one.
- Handover is complete when your team has run the agreed test cases and signed off the accounting outputs against the written scope.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- A retainer can cover re-testing of write-off postings after Fineract upgrades or product changes.
- Ask any partner to confirm how changes to accounting mappings are approved, tested and logged before you rely on them.
