Holidays & Working Days

Working day and holiday configuration determines what happens to loan repayments and meeting dates when they fall on a day the institution is closed. This affects every loan in the portfolio and must be set up before loans are created.

---

Working Days

Working days define which days of the week are operational. Fineract uses this to determine valid repayment dates.

Configure working days

PUT /fineract-provider/api/v1/workingdays
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

{
  "recurrence": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR",
  "repaymentReschedulingType": 1,
  "extendTermForDailyRepayments": false,
  "locale": "en"
}

The recurrence field uses iCalendar (RFC 5545) RRULE format. BYDAY specifies working days:

Day code	Day
MO	Monday
TU	Tuesday
WE	Wednesday
TH	Thursday
FR	Friday
SA	Saturday
SU	Sunday

A Monday-to-Saturday schedule: FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR,SA

Reading current working days

GET /fineract-provider/api/v1/workingdays

---

Repayment Rescheduling Types

When a loan repayment falls on a non-working day, Fineract reschedules it according to the configured strategy:

Code	Name	Behaviour
1	Same day	Repayment stays on the non-working day (no rescheduling)
2	Move to next repayment date	Move to the next scheduled repayment date
3	Move to next working day	Move to the next calendar working day
4	Move to previous working day	Move to the nearest working day before the due date

Common choice

3 (Move to next working day) is the most common setting. It ensures clients always pay on a day the institution is open, without compressing the repayment schedule.

extendTermForDailyRepayments applies when loans with daily repayment frequency encounter non-working days - if true, the loan term is extended by the number of skipped days rather than compressing the schedule.

---

Holidays

Holidays are specific calendar dates when the institution is closed - distinct from the weekly working days schedule. They can apply to all offices or to specific offices only.

Creating a holiday

POST /fineract-provider/api/v1/holidays
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: application/json

{
  "name": "Independence Day",
  "fromDate": "04 July 2025",
  "toDate": "04 July 2025",
  "reschedulingType": 2,
  "repaymentsRescheduledTo": "07 July 2025",
  "offices": [
    { "officeId": 1 }
  ],
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

For multi-day holidays:

{
  "name": "New Year Break",
  "fromDate": "25 December 2025",
  "toDate": "02 January 2026",
  "reschedulingType": 2,
  "repaymentsRescheduledTo": "05 January 2026"
}

Holiday rescheduling types

Code	Behaviour
1	Move repayments to next repayment date
2	Move repayments to a specific date (requires repaymentsRescheduledTo)
3	Move repayments to the next working day after the holiday ends

When reschedulingType: 2, specify the exact date all repayments falling during the holiday period should be moved to via repaymentsRescheduledTo.

Activating a holiday

Holidays must be explicitly activated before they take effect:

POST /fineract-provider/api/v1/holidays/{holidayId}?command=activate

Activate before the holiday date

Holidays that are not activated before the COB run that covers the holiday date will not be applied. Set up and activate holidays well in advance.

Applying holidays to specific offices

Leave the offices array empty or omit it to apply the holiday to all offices. To apply only to certain branches:

{
  "offices": [
    { "officeId": 2 },
    { "officeId": 5 }
  ]
}

Listing holidays

# All upcoming holidays
GET /fineract-provider/api/v1/holidays?officeId=1

# Holidays in a date range
GET /fineract-provider/api/v1/holidays?officeId=1&fromDate=01 January 2025&toDate=31 December 2025&dateFormat=dd MMMM yyyy&locale=en

---

Global Configuration Flags

Three global configuration flags interact with holidays and working days. Find them via:

GET /fineract-provider/api/v1/configurations

Config name	Default	Effect when enabled
reschedule-repayments-on-holidays	Enabled	Repayments falling on holidays are rescheduled per the holiday rule
reschedule-future-repayments	Enabled	Future repayments are moved when a holiday is added after loan creation
allow-transactions-on-non_workingday	Disabled	Staff can record transactions (repayments, disbursements) on non-working days
allow-transactions-on-holiday	Disabled	Staff can record transactions on holiday dates

To update a configuration:

PUT /fineract-provider/api/v1/configurations/{configId}

{
  "enabled": true
}

---

How Rescheduling Affects Existing Loans

When a holiday is created and activated after loans have already been disbursed:

• If reschedule-future-repayments is enabled, Fineract re-evaluates all active loans and moves any repayments falling in the holiday window
• The loan repayment schedule is updated in-place - no manual action is required
• COB reflects the updated schedule from the next run

When a working days change is applied:

• Future repayments on loans already disbursed are recalculated
• Historical (already-due) repayments are not affected

---

End-to-End Example

Setting up a system for a Monday-to-Friday institution with no Saturday operations:

# 1. Configure working days (Mon-Fri, reschedule to next working day)
PUT /fineract-provider/api/v1/workingdays
{
  "recurrence": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR",
  "repaymentReschedulingType": 3,
  "locale": "en"
}

# 2. Create Easter holiday
POST /fineract-provider/api/v1/holidays
{
  "name": "Easter",
  "fromDate": "18 April 2025",
  "toDate": "21 April 2025",
  "reschedulingType": 3,
  "offices": [{ "officeId": 1 }],
  "dateFormat": "dd MMMM yyyy",
  "locale": "en"
}

# 3. Activate the holiday
POST /fineract-provider/api/v1/holidays/{holidayId}?command=activate

Any loan repayments due on 18-21 April 2025 will automatically move to 22 April 2025 (the next working day after Easter).

---

Common Mistakes

Mistake	Effect	Fix
Forgetting to activate a holiday	Holiday has no effect on repayment schedules	Always call ?command=activate after creating a holiday
Creating a holiday after it has already started	Loans already processed through COB are not rescheduled	Create holidays well in advance
Not setting repaymentsRescheduledTo with type 2	API returns 400	Include the target date when using rescheduling type 2
Configuring working days after loans are disbursed	Existing loans may not be retroactively rescheduled	Set up working days before disbursing any loans