> ## 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.

# Recording Loan Payments

> Step-by-step guide to recording member loan repayments and updating loan balances

## Overview

Recording loan payments is a critical daily operation that updates member loan balances, tracks arrears, and ensures accurate financial reporting. When members make loan repayments, the payment is deducted from their savings balance and allocated between principal, interest, and penalties.

**Use this when**: A member wants to pay toward their loan from their savings balance (full installment, partial payment, or extra payment).

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `loans:write` permission
  * The loan exists and is in active status (not fully repaid or written off)
  * The member has sufficient savings balance to cover the payment amount
  * You know the exact payment amount and date
</Note>

<Note>
  **Finding the loan**: You can search for loans by borrower name, loan ID, or application number in the **Loans** section.
</Note>

## Step-by-Step Instructions

### Step 1: Navigate to the Loan

<Steps>
  <Step title="Open Loans section">
    Click **Loans** in the left sidebar
  </Step>

  <Step title="Find the loan">
    * Use the search bar to find the borrower's name
    * Or browse the active loans list
    * Click on the loan to open details
  </Step>

  <Step title="Open payment dialog">
    Click **"Record Payment"** button (usually near the top of loan details)
  </Step>
</Steps>

### Step 2: Enter Payment Details

The payment recording dialog contains the following fields:

| Field            | Description                                    | Required | Example              |
| ---------------- | ---------------------------------------------- | -------- | -------------------- |
| **Amount**       | Payment amount to deduct from member's savings | Yes      | 50,000 RWF           |
| **Payment Date** | Date of the payment                            | Yes      | 2026-06-08           |
| **Document**     | Upload payment receipt or proof (optional)     | No       | PDF/image of receipt |

<Note>
  **Important**: Payments are deducted from the member's savings balance. The member must have sufficient savings to cover the payment amount. If they don't have enough savings, the payment will be rejected.
</Note>

#### Example: Recording a Full Installment Payment

```
Amount: 44,500 RWF
Payment Date: 2026-06-08
Document: receipt.pdf (optional)
```

### Step 3: Review Payment Allocation

Before submitting, Agatabo displays **how the payment will be allocated**:

**Example allocation for 50,000 RWF payment:**

| Component            | Amount     | New Balance                        |
| -------------------- | ---------- | ---------------------------------- |
| **Interest**         | 12,000 RWF | 0 RWF (interest paid in full)      |
| **Principal**        | 38,000 RWF | 400,000 RWF (reduced from 438,000) |
| **Penalty** (if any) | 0 RWF      | 0 RWF                              |
| **Total Payment**    | 50,000 RWF | -                                  |

<Note>
  The allocation follows the **Payment Allocation Order** set when the loan was created:

  * **INTEREST\_FIRST**: Pays interest fully, then principal
  * **PRINCIPAL\_FIRST**: Pays principal fully, then interest
  * **PROPORTIONAL**: Splits based on ratio of principal to interest

  Most loans use INTEREST\_FIRST to ensure interest revenue is collected.
</Note>

### Step 4: Submit Payment

<Steps>
  <Step title="Verify allocation">
    Review the payment breakdown - ensure it looks correct
  </Step>

  <Step title="Check remaining balance">
    Note the new outstanding balance after this payment
  </Step>

  <Step title="Click 'Save' or 'Record Payment'">
    Submits the transaction
  </Step>
</Steps>

## What Happens Next

When you record a loan payment, Agatabo automatically:

1. **Validates savings balance**: Checks that the member has sufficient savings to cover the payment

2. **Deducts from member's savings**: The payment amount is deducted from their savings balance

3. **Allocates the payment** between interest, principal, and penalties based on the loan's payment allocation order

4. **Updates the loan balance**: Reduces the outstanding principal and marks installments as paid

5. **Creates a journal entry**:
   * **Debit**: Savings (member's account, -50,000 RWF)
   * **Credit**: Loan Receivable (-38,000 RWF)
   * **Credit**: Interest Receivable (-12,000 RWF)

6. **Marks installments as paid**: If the payment covers one or more installments, they're marked as "Paid"

7. **Updates arrears**: If the loan was overdue, arrears are recalculated

8. **Records in audit trail**: Logs payment with user ID, timestamp, and all details

9. **Sends notification** (if enabled): Borrower may receive payment confirmation

### Example Journal Entry Created

For the payment above (50,000 RWF payment with 38,000 principal and 12,000 interest), Agatabo creates:

| Date       | Account                | Debit  | Credit |
| ---------- | ---------------------- | ------ | ------ |
| 2026-06-08 | Savings (John Mugisha) | 50,000 | -      |
| 2026-06-08 | Loan Receivable        | -      | 38,000 |
| 2026-06-08 | Interest Receivable    | -      | 12,000 |

This ensures the accounting equation stays balanced.

## Common Scenarios

### Recording a Full Installment Payment

When a member pays exactly the scheduled installment amount:

<Steps>
  <Step title="Enter the installment amount">
    The amount should match the scheduled installment (shown in loan details)
  </Step>

  <Step title="Verify full allocation">
    Payment should cover the entire installment's principal and interest
  </Step>

  <Step title="Submit">
    The installment is marked as "Paid" with no arrears
  </Step>
</Steps>

### Recording a Partial Payment

When a member pays less than the scheduled installment:

<Steps>
  <Step title="Enter the actual amount received">
    Example: 20,000 RWF when 44,500 RWF is due
  </Step>

  <Step title="Review allocation">
    * If INTEREST\_FIRST: 20,000 goes to interest, leaving 24,500 interest unpaid
    * Principal remains unchanged
  </Step>

  <Step title="Note arrears">
    The unpaid portion becomes arrears and may trigger late fees
  </Step>
</Steps>

<Warning>
  **Partial payments increase arrears**: If a member consistently pays less than the installment amount, arrears accumulate. You may need to apply penalties or restructure the loan.

  [Learn about applying penalties →](/tontines/loans/applying-penalties)
</Warning>

### Recording an Extra Payment (Overpayment)

When a member pays more than the scheduled installment:

<Steps>
  <Step title="Enter the full amount received">
    Example: 100,000 RWF when 44,500 RWF is due
  </Step>

  <Step title="Review allocation">
    * Current installment paid in full (44,500)
    * Excess (55,500) applies to future installments or principal
  </Step>

  <Step title="Check new schedule">
    Future installments may be marked as prepaid, or principal reduces faster
  </Step>
</Steps>

<Note>
  **Encouraging prepayment**: Overpayments reduce the loan balance faster and may reduce total interest paid (depending on interest calculation type). This is beneficial for both member and organization.
</Note>

### Member Needs to Deposit First

If a member wants to make a loan payment but doesn't have sufficient savings:

<Steps>
  <Step title="Member deposits cash">
    Record the deposit to increase their savings balance
  </Step>

  <Step title="Then record loan payment">
    Once savings balance is sufficient, record the loan payment
  </Step>
</Steps>

<Note>
  **Two-step process**: If a member brings cash to pay their loan, first record it as a savings deposit, then immediately record the loan payment. This ensures proper accounting of both the cash receipt and the loan payment.
</Note>

### Backdated Payment (Past Date)

If recording a payment that occurred in the past:

<Steps>
  <Step title="Check period status">
    Ensure the target date is in an **open** period (not closed)
  </Step>

  <Step title="Select correct payment date">
    Change the **Payment Date** field to the actual date payment was received
  </Step>

  <Step title="Add explanatory note">
    Example: "Payment received on 2026-05-28, recorded on 2026-06-08 (late entry)"
  </Step>
</Steps>

<Warning>
  **Period closing restriction**: You cannot record payments in closed accounting periods. If the period is closed, contact your accountant about proper handling (may require adjusting entries).

  [Learn about period closing →](/tontines/advanced/period-closing)
</Warning>

## Viewing Payment History

After recording, you can verify the payment:

<Steps>
  <Step title="Check loan details">
    **Loans → \[Loan]** shows updated balance and payment history table
  </Step>

  <Step title="Check installment schedule">
    Installments are marked as "Paid", "Partially Paid", or "Overdue"
  </Step>

  <Step title="Check journal entries">
    **General Ledger → Journal Entries** → Search by date or reference
  </Step>
</Steps>

## Handling Payment Errors

### Recorded Wrong Amount

<AccordionGroup>
  <Accordion title="Before period closing">
    1. Navigate to **Loans → \[Loan] → Payment History**
    2. Find the incorrect payment
    3. Click **Edit** (if available based on permissions)
    4. Correct the amount
    5. Save changes

    **Note**: Editing capabilities depend on organization settings and period status.
  </Accordion>

  <Accordion title="After period closing">
    Payments in closed periods cannot be modified. You must:

    1. Record a **reversal payment** (negative amount) in the current period to cancel the error
    2. Record the **correct payment** with proper amount
    3. Document both transactions clearly in notes
    4. Consult with accountant to ensure proper handling
  </Accordion>
</AccordionGroup>

### Recorded Payment to Wrong Loan

<AccordionGroup>
  <Accordion title="Before period closing">
    1. **Delete** the incorrect payment (if deletion is enabled)
    2. Navigate to the correct loan
    3. Record the payment properly
    4. If deletion is not enabled, contact your accountant for reversal process
  </Accordion>

  <Accordion title="After period closing">
    Requires accountant assistance:

    1. Reversal entries on the wrong loan
    2. Correcting entries on the right loan
    3. Full documentation of the correction
  </Accordion>
</AccordionGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="'Insufficient savings balance' error">
    **Cause**: Member doesn't have enough savings to cover the payment amount.

    **Solution**:

    * Check member's current savings balance in **Organization Users → User Details**
    * If member is bringing cash, first record a deposit to increase their savings
    * Then record the loan payment
    * Navigate to **Savings → Deposit History → Record Deposit**
  </Accordion>

  <Accordion title="'Loan not found' error">
    **Cause**: Loan ID is invalid or loan has been written off/fully repaid.

    **Solution**:

    * Verify the loan exists in **Loans** section
    * Check loan status - you cannot record payments on closed loans
    * If loan is fully repaid, no additional payments are needed
  </Accordion>

  <Accordion title="'Insufficient permissions' error">
    **Cause**: Your user account doesn't have `loans:write` permission.

    **Solution**:

    * Contact your administrator to request payment recording permissions
    * If you have `loans:write` with SELF scope, you can only record payments for your own loans

    [Learn about permissions →](/reference/permissions-matrix)
  </Accordion>

  <Accordion title="'Invalid payment date' error">
    **Cause**: Payment date is in a closed period or in the future.

    **Solution**:

    * Ensure the date is in the current open period
    * Payment date cannot be after today
    * Check **Advanced → Period Closing** for period status
  </Accordion>

  <Accordion title="Payment allocation looks wrong">
    **Cause**: Payment allocation order (set when loan was created) may not match your expectation.

    **Solution**:

    * Review the loan's **Payment Allocation Order** in loan details
    * INTEREST\_FIRST pays all interest before principal
    * PRINCIPAL\_FIRST pays all principal before interest
    * PROPORTIONAL splits based on ratio
    * This cannot be changed after loan creation
  </Accordion>

  <Accordion title="Payment not reducing arrears">
    **Cause**: Payment amount is too small to cover overdue interest, or allocation order prioritizes current installment over arrears.

    **Solution**:

    * Check the **arrears breakdown** in loan details
    * Larger payment may be needed to clear overdue amounts
    * Contact accountant if arrears calculation seems incorrect
  </Accordion>
</AccordionGroup>

## Best Practices

<Note>
  **Payment recording tips:**

  * Ensure member has sufficient savings balance before recording payment
  * If member brings cash, first record it as a deposit, then record the loan payment
  * Verify the borrower's name and loan ID before submitting
  * For large payments, double-check the amount before submitting
  * Upload payment receipts or proof using the Document field
  * Record payments promptly to keep arrears accurate
  * Check the payment allocation preview before submitting
</Note>

## Understanding Payment Impact

### Effect on Loan Balance

Each payment reduces the outstanding loan balance:

| Payment #        | Payment | Interest | Principal | Balance Before | Balance After |
| ---------------- | ------- | -------- | --------- | -------------- | ------------- |
| 0 (Disbursement) | -       | -        | -         | 0              | 500,000       |
| 1                | 44,500  | 12,000   | 32,500    | 500,000        | 467,500       |
| 2                | 44,500  | 11,200   | 33,300    | 467,500        | 434,200       |
| 3                | 44,500  | 10,400   | 34,100    | 434,200        | 400,100       |

Notice how principal portion increases and interest decreases (for reducing balance loans).

### Effect on Arrears

* **On-time payment**: Clears current installment, no arrears added
* **Partial payment**: Unpaid portion becomes arrears, may trigger late fees
* **Overpayment**: Reduces arrears, may prepay future installments

### Effect on Financial Reports

* **Member savings decreases**: Borrower's savings balance is reduced
* **Loan receivable decreases**: Portfolio outstanding reduces
* **Interest receivable decreases**: Recognized interest revenue is collected

## Related Operations

After recording payments, you may need to:

<CardGroup cols={2}>
  <Card title="View Loan Details" icon="file-lines" href="/tontines/loans/viewing-loan-details">
    Review installment schedule and payment history
  </Card>

  <Card title="Apply Penalties" icon="circle-exclamation" href="/tontines/loans/applying-penalties">
    Charge late fees for overdue payments
  </Card>

  <Card title="Loan Analytics" icon="chart-line" href="/tontines/loans/loan-analytics">
    Monitor portfolio health and arrears
  </Card>

  <Card title="Recording Deposits" icon="plus" href="/tontines/deposits/recording-deposits">
    Add cash deposits to increase member savings
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Understanding Payment Allocation" icon="split" href="/tontines/loans/loan-rules-explained">
    Learn how payments are split between principal and interest
  </Card>

  <Card title="Managing Arrears" icon="triangle-exclamation" href="/tontines/loans/applying-penalties">
    Handle overdue payments and late fees
  </Card>

  <Card title="Viewing Loan Details" icon="file-lines" href="/tontines/loans/viewing-loan-details">
    Check payment history and remaining balance
  </Card>

  <Card title="Common Errors" icon="circle-info" href="/troubleshooting/common-errors">
    Troubleshooting payment recording issues
  </Card>
</CardGroup>