Skip to main content

​
Overview

Loan modification in Agatabo allows you to adjust the loan’s overall terms - increasing the principal amount, extending the period, or changing the interest rate. The system regenerates the repayment schedule from the modification date forward while keeping past installments unchanged.
Important: This is a term-level modification system, not an installment-level system. You cannot modify individual installment amounts or due dates. Instead, you modify the loan’s global terms, and the system recalculates the entire schedule.

​
What Can Be Modified

​
Principal Amount (Top-up)

Increase the loan principal amount:
  • Add funds to an existing loan
  • Member receives additional cash disbursement
  • New schedule calculated from modification date forward
  • Restriction: Cannot reduce principal (increase only)
Example: 500,000 RWF loan → modify to 700,000 RWF
  • Additional 200,000 RWF disbursed to member
  • Schedule recalculated for remaining period with new principal

​
Loan Period (Extension)

Extend the loan duration:
  • Add more months to the repayment period
  • Reduces monthly payment burden
  • Increases total interest paid
  • Restriction: Cannot shorten period (extend only)
Example: 12-month loan → extend to 18 months
  • 6 additional months added
  • Monthly payments recalculated with new period

​
Interest Rate

Change the interest rate:
  • Adjust up or down
  • New rate applies from modification date forward
  • Optional: Can keep the same rate
Example: 5% monthly → modify to 3% monthly
  • New installments calculated with 3% rate

​
What Cannot Be Modified

Restrictions on modifications:
  • Cannot reduce principal amount (increase only)
  • Cannot shorten loan period (extend only)
  • Cannot modify interest calculation type (SIMPLE, REDUCING_BALANCE, COMPOUND)
  • Cannot modify installment type (EQUAL_PRINCIPAL vs EQUAL_TOTAL)
  • Cannot modify payment allocation order
  • Cannot modify individual installment amounts or due dates
  • Cannot modify COMPLETED or DEFAULTED loans (active only)
  • Cannot modify if later payments or penalties exist (must reverse those first)

​
When to Modify Loans

Modify loans when:
  • Top-up request: Member needs additional funds
  • Financial hardship: Member needs lower payments (extend period)
  • Interest rate adjustment: Market conditions or policy changes
  • Loan restructuring: Prevent default with better terms
Prerequisites:
  • Loan must be ACTIVE
  • Both parties agree to new terms
  • Committee approval (per your organization’s policy)

​
The 3-Step Modification Process

​
Step 1: Enter New Terms

1

Navigate to loan details

Loans → Select the loan → Open details
2

Click 'Modify Loan' button

Located in the Loan Overview card (if you have permission)
3

Enter new terms

Fill in the modification form:
  • New Principal: Must be ≥ current principal
  • New Period: Must be ≥ current period (in months)
  • New Interest Rate: Optional, enter new percentage
  • Modification Date: When the change takes effect
  • Bank Account: Required if increasing principal (for disbursement)
4

Click 'Next'

Proceeds to preview step

​
Step 2: Preview Changes

The preview shows the financial impact of the modification: Comparison display:
  • Old vs New principal amounts
  • Old vs New loan periods
  • Old vs New interest rates
  • Cash Disbursed: Additional amount to be disbursed (if principal increased)
  • Interest Adjustment: Change in total interest
Schedule preview:
  • Installments before modification date (unchanged)
  • Installments after modification date (new calculations)
1

Review the impact

Verify the changes are correct
2

Check disbursement amount

If increasing principal, confirm cash amount
3

Click 'Next'

Proceeds to confirmation

​
Step 3: Confirm and Submit

1

Add reason (optional)

Document why the modification is being made
2

Acknowledge terms

Confirm you understand the changes
3

Click 'Confirm Modification'

Submits the modification

​
What Happens When You Modify

  1. Validation checks:
    • Confirms loan is ACTIVE
    • Verifies new principal ≥ current principal
    • Verifies new period ≥ current period
    • Checks no later payments/penalties exist
  2. Journal entries created:
    • Dr BANK_ACCOUNT: Cash disbursed (if principal increased)
    • Cr LOAN_RECEIVABLE: Principal increase
    • Additional entries for interest (if interest paid in advance)
  3. LoanModificationMeta record created:
    • Stores old vs new terms
    • Links to journal entry
    • Records modification date, reason, and creator
  4. Loan schedule regenerated:
    • Installments before modification date: unchanged
    • Installments after modification date: recalculated with new terms
  5. Cash disbursed (if principal increased):
    • Additional funds released to member
    • From selected bank account
  6. Modification history updated:
    • Appears in loan details
    • Shows in modification history table

​
Understanding Schedule Regeneration

The modification creates a “before and after” schedule: Example: Loan started June 1, 2026 (12 months, 500,000 RWF) Modified on September 1, 2026 (extend to 18 months, increase to 700,000 RWF) Installments 1-3 (June, July, August):
  • Unchanged - calculated with original terms
  • Already paid or in progress
Installments 4-18 (September onward):
  • Recalculated - uses new principal (700,000 RWF) and new period (18 months)
  • New monthly amounts based on remaining principal and remaining months
Important: The system doesn’t “restart” the loan. It calculates what the remaining balance is at the modification date and spreads it over the new remaining period with the new terms.

​
Modification History

All modifications are tracked and displayed in the loan details: History shows:
  • Modification date
  • Old → New principal
  • Old → New period
  • Old → New interest rate
  • Cash disbursed
  • Reason (if provided)
  • Who made the modification
  • When it was created
Actions available:
  • View full details
  • Undo the latest modification (if no later events exist)

​
Undoing a Modification

You can reverse the most recent modification if needed:
1

Go to loan details

Find the loan with the modification
2

View Modification History

In the Loan Overview card
3

Click 'Undo' (trash icon)

Only available for the latest modification
4

Confirm

Reverses the modification
What happens:
  • Reverses all journal entries
  • Deletes the modification record
  • Schedule reverts to previous state
  • Cash disbursement is reversed (if applicable)
Cannot undo if:
  • Any loan payments were made after the modification date
  • Any penalties were applied after the modification date
  • You must reverse those events first, then undo the modification

​
Common Modification Scenarios

​
Top-up (Additional Funds)

Member needs more money: 
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 800,000 RWF, 12 months, 5% monthly (same period and rate)

Result:
- Additional 300,000 RWF disbursed
- Remaining installments recalculated with higher principal
- Monthly payments increase

​
Period Extension (Lower Payments)

Member needs lower monthly payments: 
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 500,000 RWF, 18 months, 5% monthly (same principal and rate)

Result:
- No additional cash disbursed
- Remaining installments spread over more months
- Monthly payments decrease
- Total interest increases

​
Top-up with Extension

Combination modification: 
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 700,000 RWF, 18 months, 4% monthly

Result:
- Additional 200,000 RWF disbursed
- Extended period for more flexibility
- Reduced rate to help member

​
Interest Rate Adjustment

Policy change: 
Original: 500,000 RWF, 12 months, 5% monthly
Modified: 500,000 RWF, 12 months, 3% monthly (rate reduction)

Result:
- No cash disbursement
- Future installments use new 3% rate
- Total interest decreases

​
Best Practices

Modification tips:
  • Get written request from member
  • Obtain committee approval per policy
  • Document reason clearly
  • Preview changes before confirming
  • Keep modification history for audit
  • Use top-ups strategically (don’t over-lend)
  • Consider member’s repayment capacity
  • Communicate new schedule to member
  • Print/send updated schedule to member

​
Important Restrictions

​
Modification Date Constraints

The modification date must be:
  • ✅ After the loan start date
  • ✅ On or before today (not in future)
  • ✅ On or before the last installment due date
  • ✅ At a date with no existing modification (one per date)

​
Interest Refund Prevention

The system blocks modifications that would require refunding interest to the borrower:
  • For IN_ADVANCE loans: Cannot reduce principal or period in ways requiring refund
  • For WITH_INSTALLMENTS loans: Cannot reduce interest below outstanding receivable

​
Event Ordering

Cannot modify if:
  • ❌ Payments were made after the modification date (reverse payments first)
  • ❌ Penalties were applied after the modification date (reverse penalties first)
  • ❌ Any other loan events exist after the modification date

​
Permissions Required

ActionPermissionScope
View loan detailsloans:readANY
Modify loanloans:modifyANY
Undo modificationloans:modifyANY

Creating Loans

Understand initial loan setup

Viewing Loan Details

Check modification history

Recording Payments

Handle payments on modified loans

Loan Analytics

Monitor modified loan performance