> ## Documentation Index > Fetch the complete documentation index at: https://help.agatabo.com/llms.txt > Use this file to discover all available pages before exploring further. # Applying Penalties > Calculate, apply, and manage late payment penalties for overdue loans ## 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 Date | Outstanding Amount | Penalty Amount | Status | | ----------------- | ------------------ | -------------- | --------- | | July 1, 2026 | 50,000 | 1,000 | UNAPPLIED | | August 1, 2026 | 50,000 | 1,000 | UNAPPLIED | | September 1, 2026 | 50,000 | 1,000 | UNAPPLIED | **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 Click Loans in sidebar Click on the loan with arrears 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 In the loan details page Locate the specific installment and period Opens apply penalty dialog * Transaction Date: Period due date (auto-filled) * Application Date: When to post the penalty (today or later) Creates journal entry and moves penalty to APPLIED status ### Apply All Penalties for an Installment Find the installment with multiple penalty periods Opens bulk apply dialog When to post all penalties 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 Find the penalty to reverse Opens confirmation dialog Creates reversal journal entry and moves penalty back to UNAPPLIED ### Reverse All Penalties for an Installment Find the installment Opens confirmation dialog 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 | Action | Permission | Scope | | ----------------- | ------------- | ----- | | View penalties | `loans:read` | ANY | | Apply penalties | `loans:write` | ANY | | Reverse penalties | `loans:write` | ANY | ## Related Operations How payments settle penalties Check penalty status Monitor penalty income Configure penalty rate