Holidays and working days in Apache Fineract

Why holidays and working days in Apache Fineract need a design decision

In Apache Fineract, a repayment date that falls on a holiday or non-working day can be moved, and whether it moves depends on branch-level holiday data and global settings. A lender with branches in several regions, each with different public holidays and weekend rules, therefore has to decide these rules before the first loan is booked. Changing them later affects schedules that customers have already accepted, so the decision belongs in the design phase alongside product and ledger design.

Getting this wrong has visible costs. A customer who expects to pay on a Friday and finds the due date has moved to Monday, or has not moved at all, may pay late or dispute the schedule. Collections teams may chase accounts on dates that a branch treats as closed, and staff may see different due dates for the same loan depending on which screen they use. Each of these creates support work and weakens the record of how a repayment was handled. None of these costs can be sized without your own branch calendars, loan volumes and collection process, so model them from your data rather than from assumptions.

Before you finalize the design, confirm the exact setting names, their defaults and their behavior against the Fineract version you plan to run, using the Apache Fineract platform documentation. Ask how the reschedule-to date is stored and shown, how holidays are loaded per office, and whether transactions on holidays are blocked or allowed. Then test the rules with dated loan examples across each region before go-live.

Which holiday and working day options fit which lending model

This table compares the holiday and working day choices in Fineract against common lending models, from single-country lenders to field lending with centers. Read each row as a decision: the option, when it fits, and what it changes for the borrower, the schedule and reporting. The main takeaway is that the calendar scope should match where the loan is serviced, not only where the company is registered.

Option	Best fit	What it changes	Confirm before you build
Single global holiday calendar	Single-country lender with one set of public holidays and one branch network	One set of non-working dates applies to every office, so schedule dates behave the same everywhere	Confirm with the Fineract documentation how holidays are defined and whether offices can override them
Branch-specific holiday calendars	Multi-region lender where regional or local holidays differ between offices	A repayment falling on a holiday in one branch can move there while staying fixed in another	Confirm how a loan is linked to its office and which calendar Fineract applies at schedule generation
Working day rules with weekend days	Countries where the working week differs from Monday to Friday	Non-working weekdays are skipped when dates are generated, which changes installment dates and the count of paydays per month	Confirm the weekend setting and whether it applies per office or globally in your Fineract version
Reschedule-to date behavior	Lenders that must collect on a fixed payday, such as salary-linked or field collection cycles	Moves a repayment to the next valid working day, which can shift interest days and the final maturity date	Test a sample loan on a holiday and check the new due date, interest accrual and the maturity date
Global setting to move repayments	Lenders whose policy is to keep the original due date for recording purposes	Determines whether a holiday due date stays on the schedule or moves, affecting arrears ageing and overdue reports	Confirm the setting name and default in the Fineract documentation and record the choice in your product design
Global setting to allow transactions on holidays	Operations that collect or disburse on public holidays, such as field or agent-based lending	Decides whether a repayment or disbursement can be posted on a non-working day, affecting reconciliation with bank files	Confirm with your bank or payment partner whether they settle on those days before enabling it
Cross-border lending	Lenders with borrowers in several countries and different holiday calendars	Needs calendars and working day rules per country or office, so the same product can produce different schedules by location	Confirm the country-level or office-level behavior in your version and test each market separately
Field lending with centers	Group or center-based microfinance where meetings happen on a fixed day each week	Repayment dates tied to meeting days may move when a center's meeting day is a holiday, which affects collection routes	Confirm how center meeting schedules interact with holiday moves and decide whether moves are shown to field staff

How Fineract applies holiday rules to a repayment date

The schedule date and the actual payment date can differ because Fineract applies holiday and working day inputs at two points: when the schedule is generated and when a repayment is processed. Holidays are defined per office, so a repayment that falls on a branch holiday may move to the reschedule-to date entered against that holiday. Global settings then decide whether repayments move at all and whether transactions are accepted on holidays or non-working days. The exact order of evaluation depends on the version you run and the settings you enable, so confirm it against the Fineract platform documentation rather than assuming it from the setting names.

A moved repayment changes more than one date. Interest accrues on outstanding principal for the days between periods, so a later due date changes the interest component of that installment. Depending on the product's recalculation and amortization settings, later installments can also shift. The first installment is the most exposed, because the disbursement date, the first repayment date and any holiday move can sit close together. The final installment matters because a move past maturity or into a holiday can change the last due date and the closing balance the borrower sees. Model each of these before the product goes live, and agree with the business which cases are acceptable.

Test these rules on a non-production tenant before relying on them. Create one loan per scenario: a repayment on a branch holiday, a repayment on a holiday with a reschedule-to date, and a first and final installment that land on non-working days. Post a repayment on a moved date, then run the Close of Business batch job. The project notes that this job can run for several hours on deployments with millions of accounts, so test with a realistic data volume. Compare the schedule, accrued interest and transaction dates before and after each step, and record the settings that produced each result so the configuration can be signed off.

Setting up holiday calendars and working day rules in order

This sequence turns a lender's holiday and working day policy into Fineract configuration that generates valid repayment dates, and proves each layer with a test loan before any real account uses it. Each step ends with a check so that errors are caught while the calendar is still cheap to correct.

Collect the calendar for each region and branch
Operations and compliance staff list every branch, its region, and the public holidays and closure days that apply to it, using the lender's credit policy and the published calendars of the relevant national or local authorities. Record which days are non-working for lending purposes, and note any branch that observes a different calendar from its region. The output is a signed-off calendar register with one row per branch and holiday date. Check: every active branch appears in the register and has an owner who confirmed its dates.
Confirm the configuration path for your release
Before entering anything, the platform team checks the Fineract documentation for the exact release in use, since holiday, working day and global configuration screens and API resources can differ between 1.x releases. Record the endpoints or settings the team will use, and note the release version in the change record. The output is a short configuration runbook tied to that version. Check: a team member who did not write the runbook can locate each setting in a test environment running the same release.
Load branch holidays into the calendar
The platform team enters each branch's holidays in Fineract, using the register from the first step as the only source. Entries should be created in a non-production tenant first, with the holiday name, date and the branch it applies to. Where a holiday recurs, confirm whether the release requires one entry per year or supports a recurring rule. The output is a loaded holiday set for each branch. Check: an export or API read of the holiday set matches the register line for line.
Set working day rules and global settings
The platform owner sets the working day definition, including which weekdays and weekend days are working days, and the global settings that decide whether a repayment due on a non-working day moves to the next working day, and whether transactions are allowed on holidays. Each setting is recorded with the business reason and the approver. Settings that change how dates are generated should be agreed with credit and operations before they are switched on. The output is a documented settings baseline. Check: the baseline matches the approved policy table, and a second person has reviewed each value.
Create a test loan product with a schedule across known holidays
The implementation team creates a test loan product and a test client at a branch with holidays in the coming months. They choose a disbursement date and repayment frequency so that at least one scheduled due date falls on a holiday and one falls on a weekend, then generate the repayment schedule. Keep the product configuration identical to the production design so the test result carries over. The output is a generated schedule for the test loan. Check: every due date in the schedule is compared with the calendar, and each date that moved is explained by the settings from the previous step.
Test posting on a holiday and a moved due date
The team records repayments against the test loan on a due date that moved, and on a holiday where transactions are blocked or allowed under the global setting, and checks the posted transaction date and the schedule status after each action. Repeat the test for a second branch that observes a different calendar. The output is a test log showing the posted date, the effective due date and any rejected transactions. Check: the posted date and the schedule agree with the expected result in the policy table, and any mismatch is logged as a defect before go-live.
Run the schedule review with operations
Operations leads and the implementation team walk through a sample of schedules across regions, including loans disbursed close to a holiday cluster and loans with a reschedule-to date. The review focuses on whether the dates would be accepted by branch staff and by customers, and whether any exception needs a manual process. The output is a signed review record with open issues and owners. Check: no open issue remains for a schedule rule that applies to live loans, and the calendar owner has agreed a process for updating holidays each year.

How the setup differs for single-country and multi-region lenders

A single-country lender usually works from one national holiday calendar and one set of repayment rules. The main decisions are simpler, but they still need a named owner. Someone in operations or product must decide which holidays apply, whether repayments move to the next working day, and whether branches can take transactions on public holidays. Even with one calendar, branch-level exceptions such as local festivals or closures can appear, so the design should say whether those are handled in Fineract or outside it.

Calendar ownership: Assign one business owner for the national calendar and record who signs off each annual update.
Change approval: Agree in advance when a calendar change takes effect and whether existing schedules are reviewed after it.
Tenant boundary: A single operating entity usually maps to one tenant, so holiday data and global settings are shared by all branches.
Branch exceptions: Decide whether a closure at one branch is recorded as a branch holiday or handled operationally, and test how it affects due dates.
Reporting: Confirm that collection and arrears reports can filter by date basis, so a moved due date is not mistaken for a late payment.

Ask a partner to scope the annual calendar update procedure, the test cases for weekend and holiday due dates, and the change record needed for audit review.

Controls that protect holiday data and repayment dates

Holiday calendars and global settings decide when repayments fall due and whether transactions are allowed on a given day. The controls below decide who can change that data, how changes are reviewed and recorded, and how a bad calendar is caught before borrowers and collections teams act on it.

Limit who can edit calendars

Holiday definitions and working day settings are configuration that changes every loan schedule built after the change. Restrict edit rights to a small operations or product group, and remove those rights from general branch and tellers roles. Review the role assignments that include holiday and configuration permissions, and confirm the exact permission names in your Fineract version and your own role model, since the mapping is defined by your deployment.

Approve and log calendar changes

Fineract records who created or changed a holiday, but it does not replace a sign-off step. Require a written request that names the branch, the dates and the affected products, then a second person to approve it before the change is entered. Keep the approval record alongside the audit trail you retain, and confirm where your deployment stores audit data and for how long.

Isolate regional calendars by tenant

Fineract is multi-tenant, and each API request carries a tenant identifier. If several regions or legal entities share an instance, a holiday entered for one tenant must not reach another. Test that a calendar change in one tenant leaves the others unchanged, and confirm with your deployment team how tenant connections and access are configured in your environment.

Measure the cost of a wrong calendar

A wrong holiday can move due dates for many borrowers at once. Those dates feed payment reminders, SMS and email notices, arrears ageing and collections worklists. Before a calendar change goes live, run a sample of affected schedules and list the notices and collections actions that will change, so the business can stop a bad release before it reaches borrowers.

Back up and restore configuration

Holiday records and global settings are part of your configuration, not just loan data. Include them in your backup scope and test a restore to a non-production environment, then compare calendar entries and settings with the source. Confirm with your database and backup team how configuration tables are captured, since backup coverage depends on your own setup.

Separate test and production calendars

Build and test holiday calendars in a non-production tenant or environment that mirrors production configuration, then promote only approved entries. Mixing test holidays into production is a common route to unexpected schedule moves. Document the promotion steps, who performs them, and how you confirm that production matches the approved list after each change.

What holiday configuration costs and what the work needs from you

How much effort does holiday and working day configuration take in Fineract?

The effort depends mainly on how many branches, regions and calendars you run, and on how clean your holiday data is. A single-region lender with one national holiday list is a small configuration task. A multi-region lender with branch-specific holidays, several products and inconsistent source calendars is a much larger one, because each calendar combination needs its own validation. Effort also rises when repayment rules differ by product, since each product's behavior on a holiday has to be checked separately. No effort figure is given here. A quote should show the number of calendars, products and branches in scope, and the review steps that go with them.

What drives the cost of a holiday calendar project?

The main cost drivers are the number of branches and regions, the number of loan products that must respect those calendars, the quality of the holiday data you provide, and how many policy decisions remain open. Each open decision, such as whether a repayment moves forward or backward, adds review time because it changes the schedule logic for every affected loan. A quote follows from a written scope, so ask for the assumptions behind each line: which calendars are included, which products are covered, and whether testing and sign-off are part of the price or a separate phase.

How long does testing holiday rules take, and what does it depend on?

Testing takes as long as it takes to cover your calendar combinations and sample loans, and that depends on the number of regions, products and reschedule scenarios you need to prove. A useful test set includes loans whose due dates fall on a branch holiday, on a national holiday, on a weekend, and on the last day of a month, for each product that uses different rules. Testing also depends on how quickly your business owners review the results. Ask any partner to show the test matrix and the expected duration in the written scope, and confirm which environment the tests run in before production data is involved.

What must the lender supply before configuration starts?

The lender needs to supply four things: the holiday calendars for every branch and region, written policy decisions on how repayments move and whether transactions are allowed on holidays, sample loans that represent real cases, and named sign-off owners for operations, credit and compliance. Without the policy decisions, configuration stalls, because the global settings that control rescheduling cannot be chosen by the implementer. Sample loans let the team check actual schedules rather than theoretical ones. Confirm who owns each item before the work starts, and record the owners in the scope document.

Can our internal team configure holidays and working days ourselves?

Yes, a team that already runs Fineract in its own infrastructure can configure holidays and working days, provided it has someone who understands the product settings and the repayment schedule logic. The harder part is validating the results across branches and products, and checking that changes do not affect existing loans. Teams without that experience often configure the calendar but skip the regression checks on active schedules. Decide early whether your team will own the configuration, the testing, or both, and whether an outside partner will review the design before go-live.

What should a quote for holiday configuration include?

A quote should list the scope in writing: the calendars and branches covered, the loan products affected, the global settings to be decided and documented, the test cases and sample loans, the deliverables such as configuration records and a runbook, and the sign-off steps. It should also state what is out of scope, such as data migration or changes to other products, and what the lender must provide. DeployOpen quotes follow from a written scope, so the scope document is the basis for any price. Ask whether support for later calendar changes is a separate retainer.

Who maintains holiday calendars after go-live?

After go-live, someone in the lender must own each calendar update, usually when a new public holiday is announced or a branch changes its opening days. Ask the implementer to document the update procedure, including who approves a change, how it is tested against a sample of loans, and when it takes effect. Calendar changes that are not tested can move installment dates for loans already in progress, so treat them as controlled changes. Ongoing support can be scoped as a retainer if your team prefers not to carry this work internally.

Limits to confirm for your Fineract version and environment

Holiday and working day behavior in Fineract touches interest, batch jobs, reporting and regional rules at once, and the exact settings depend on the release you run. The cards below list the points to settle with vendor documentation or a proof-of-concept test before the calendar design is locked. Each one is a question to answer in your own environment, not a behavior to assume.

Exact settings in your release

Confirm the names, defaults and effect of every holiday, working day and reschedule setting in the version you will run. The project website lists 1.15.0 as the current stable release, but configuration keys and global settings can change between releases. Ask for the documentation for your exact version and test each toggle in a non-production tenant before you rely on it.

Holidays and interest recalculation

Check how a moved repayment date changes the interest accrued for the days it shifts, and whether recalculation on a moved schedule produces the installment amounts your product terms promise. Test a loan with an early payment and a holiday-shifted due date in the same period. Confirm which day-count basis applies to the shifted period so the schedule matches your contract.

Holidays and batch processing

Ask how the Close of Business Day job treats holidays and whether a holiday in one branch affects loans in another. Batch jobs run over every account, so a calendar error can cascade. Confirm the timing of the job relative to the business date, and test a close of business run on a holiday that falls on a repayment due date.

Moved dates in reports and notifications

Confirm whether reports, statements, due-date reminders and any external notifications use the moved repayment date or the original contractual date. A mismatch between the schedule and the customer letter is a common complaint source. Ask which timestamps your event consumers receive and whether they can distinguish the original from the rescheduled date.

Calendar loading across branches

Ask how branch-specific holiday calendars are created, updated and loaded when you have many offices and regions. Confirm whether bulk loading is supported, how a calendar change applies to loans already in progress, and who approves it. Measure the load time and the effect on API responses in a proof of concept sized to your branch count.

Regional rules needing custom code

Identify any holiday rule your markets need that standard settings cannot express, such as a weekend pattern that differs by region or a rule that depends on a government announcement. Ask the vendor or your team whether the platform supports it without custom development. Any gap that requires an extension should be scoped, tested and maintained as part of your upgrade plan.

How DeployOpen works on this

DeployOpen scopes holiday and working day configuration for Apache Fineract as a written, fixed-scope piece of work inside your own infrastructure. We turn your branch calendars, regional rules and repayment policy into tested settings, then hand over the configuration and the procedures your operations team needs to keep it current.

How we scope

Inventory every branch, region and product that needs its own holiday calendar and working day rules
Document the policy for moving repayments that fall on non-working days, including the reschedule-to date
Confirm whether transactions such as disbursements and repayments are allowed on holidays for each channel
Agree in writing which Fineract settings, data and tests are in scope before work starts

How we build

Load holiday calendars and working day definitions into a non-production Fineract environment first
Test repayment schedules across weekend, holiday and reschedule-to cases using agreed sample loans
Verify how the global settings for moving repayments and holiday transactions behave in each region
Check configuration changes against the environment that will run production, not only a development instance

How we hand over

Deliver a configuration record listing every calendar, rule, global setting and the reason for each value
Provide test scripts and expected schedule outcomes so your team can repeat the checks after changes
Document the change procedure for adding a holiday, a new branch or a new region
Walk your operations and product teams through the process and record who approves calendar changes

How we support

Ongoing support, upgrades and continuous testing are available as retainers
A retainer can cover annual calendar updates and regression checks after Fineract upgrades
Ask any provider to confirm how calendar changes are tested before they reach production
Confirm with your team which holiday sources are official for each region before a quote is finalized

Holidays and working days in Apache Fineract repayment schedules