Skip to main content

​
Overview

The penalty system in Agatabo uses a two-stage process: penalties are first computed automatically based on overdue installments, then must be explicitly applied to affect the loan balance. This gives you control over when to formally charge penalties while still tracking what is owed.

​
How Penalties Work

​
Penalty Calculation

Penalties are calculated using:
  • Penalty Rate: Configured in Settings → Rates (e.g., 2% monthly)
  • Outstanding Amount: Unpaid portion of the overdue installment
  • Monthly Compounding: New penalty period created each month installment remains unpaid
Formula: Penalty Amount = Penalty Rate × Outstanding Amount Example: 
Installment due: June 1, 2026 (50,000 RWF)
Penalty rate: 2% per month
Member hasn't paid by July 1

July penalty period: 2% × 50,000 = 1,000 RWF
August penalty period: 2% × 50,000 = 1,000 RWF (if still unpaid)
September penalty period: 2% × 50,000 = 1,000 RWF (if still unpaid)

​
Penalty Periods

Starting 1 month after an installment’s due date, a new penalty period is created each month:
Period Due DateOutstanding AmountPenalty AmountStatus
July 1, 202650,0001,000UNAPPLIED
August 1, 202650,0001,000UNAPPLIED
September 1, 202650,0001,000UNAPPLIED
Notes:
  • Penalty periods are computed automatically
  • Each month overdue creates a new period
  • Partial payments reduce the outstanding amount for future periods

​
Two-Stage Process

Stage 1: UNAPPLIED (Computed)
  • Penalty is calculated but not yet charged
  • Does NOT affect loan balance
  • Visible in penalty periods list
  • Member is not yet obligated to pay
Stage 2: APPLIED (Charged)
  • Penalty is formally applied via journal entry
  • DOES affect loan balance
  • Creates PENALTY_RECEIVABLE in ledger
  • Member must pay this amount
Important: You must explicitly apply penalties for them to affect the loan balance. Simply having overdue installments doesn’t automatically charge penalties.

​
Viewing Penalties

​
Access Penalty Periods

1

Navigate to Loans

Click Loans in sidebar
2

Open loan details

Click on the loan with arrears
3

View Penalty Periods section

Shows summary stats and tabs

​
Penalty Summary Stats

Three cards showing:
  • Unapplied Penalties: Count of computed but not applied penalties
  • Applied Penalties: Count of formally charged penalties
  • Outstanding Amount: Total penalty amount owed

​
Unapplied Penalties Tab

Shows penalties that have been computed but not yet applied: Columns:
  • Installment number
  • Due date
  • Penalty amount
  • Period due date
  • Actions (Apply button)
Actions available:
  • Apply - Apply individual penalty period
  • Apply All - Apply all penalty periods for an installment at once

​
Applied Penalties Tab

Shows penalties that have been formally charged: Columns:
  • Installment number
  • Due date
  • Penalty amount
  • Applied date
  • Journal Entry ID
Actions available:
  • Delete - Reverse individual applied penalty (if not paid)
  • Delete All - Reverse all applied penalties for an installment

​
Applying Penalties

​
Apply Single Penalty Period

1

Go to Unapplied Penalties tab

In the loan details page
2

Find the penalty period

Locate the specific installment and period
3

Click 'Apply' button

Opens apply penalty dialog
4

Select dates

  • Transaction Date: Period due date (auto-filled)
  • Application Date: When to post the penalty (today or later)
5

Click 'Apply Penalty'

Creates journal entry and moves penalty to APPLIED status

​
Apply All Penalties for an Installment

1

Go to Unapplied Penalties tab

Find the installment with multiple penalty periods
2

Click 'Apply All'

Opens bulk apply dialog
3

Select application date

When to post all penalties
4

Confirm

Applies all penalty periods for that installment at once

​
What Happens When You Apply a Penalty

  1. Journal entry created: 
    Dr PENALTY_RECEIVABLE (linked to loan)    1,000 RWF
   Cr PENALTY_INCOME                       1,000 RWF
  2. LoanPenaltyMeta record created: Links installment, period, and journal entry
  3. Loan balance increases: Outstanding penalty receivable increases
  4. Status changes: Penalty moves from UNAPPLIED to APPLIED
  5. Member notification (if enabled): Borrower notified of penalty charge
  6. Shows in loan details: Applied penalties visible in the Applied Penalties tab

​
Reversing (Waiving) Penalties

You can reverse applied penalties as long as they haven’t been paid.

​
Reverse Single Penalty

1

Go to Applied Penalties tab

Find the penalty to reverse
2

Click 'Delete' button

Opens confirmation dialog
3

Confirm

Creates reversal journal entry and moves penalty back to UNAPPLIED

​
Reverse All Penalties for an Installment

1

Go to Applied Penalties tab

Find the installment
2

Click 'Delete All'

Opens confirmation dialog
3

Confirm

Reverses all applied penalties for that installment
Cannot reverse paid penalties: If a penalty has been fully or partially paid, you cannot reverse it. You must reverse the payment first, then reverse the penalty.

​
How Penalties Affect Payments

When a member makes a loan payment:
  1. First priority: Payment settles scheduled installments (principal + interest)
  2. Second priority: Remaining payment settles applied penalties
  3. Order: Oldest penalties are paid first
Example: 
Payment received: 60,000 RWF
Scheduled installment due: 50,000 RWF
Applied penalties: 3,000 RWF

Allocation:
- 50,000 → Installment (fully paid)
- 10,000 → Penalties (partially paid, 3,000 outstanding)

​
Loan Completion

A loan is only marked COMPLETED when:
  • ✅ All scheduled installments are paid
  • ✅ All applied penalties are paid
Unapplied penalties do not block loan completion. Only applied penalties must be paid for the loan to be marked complete.

​
Best Practices

Penalty management tips:
  • Apply penalties consistently (same rules for all members)
  • Communicate penalty policy clearly before disbursement
  • Review unapplied penalties weekly
  • Consider grace periods (e.g., don’t apply penalties for first late payment)
  • Apply penalties in batches (monthly review)
  • Reverse penalties for members with valid reasons (illness, emergency)
  • Monitor penalty income trends - excessive penalties indicate collection issues
  • Use penalties to encourage timely payment, not punish members

​
Common Scenarios

​
Late Payment with Partial Amount

Member was supposed to pay 50,000 on June 1 but paid 30,000 on June 15:
  1. Installment has 20,000 outstanding
  2. July 1: Penalty period created on 20,000 (not the original 50,000)
  3. July penalty: 2% × 20,000 = 400 RWF

​
Member Catches Up

Member pays overdue amount before you apply penalties:
  1. Unapplied penalties remain in the system
  2. You can choose to waive them (don’t apply)
  3. Once installment is paid, outstanding amount for penalty calculation becomes 0

​
Excessive Penalties

Loan has accumulated many penalty periods:
  1. Review each period individually
  2. Apply only reasonable penalties (e.g., most recent 3 months)
  3. Waive older penalties if member commits to payment plan
  4. Apply all at once using “Apply All” feature

​
Permissions Required

ActionPermissionScope
View penaltiesloans:readANY
Apply penaltiesloans:writeANY
Reverse penaltiesloans:writeANY

Recording Loan Payments

How payments settle penalties

Viewing Loan Details

Check penalty status

Loan Analytics

Monitor penalty income

Settings

Configure penalty rate