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

# Creating Loans

> Complete guide to creating loans with flexible terms, interest rules, and repayment schedules

## Overview

Creating a loan in Agatabo is a structured 5-step process that captures borrower information, loan terms, interest rules, securities, and bank details. Agatabo automatically calculates the installment schedule and disburses funds when the loan is created.

**Use this when**: A member applies for a loan and you need to formalize the loan agreement with specific terms.

## Before You Begin

<Note>
  **Prerequisites:**

  * You have `loans:write` permission
  * The borrower exists as an organization user with a member role
  * You know the loan amount, term, and interest rate
  * You understand which interest calculation type and installment structure to use
  * Organization has sufficient cash to disburse the loan
</Note>

<Warning>
  **Important**: Most loan terms (interest rate, calculation type, installment type, payment allocation) cannot be changed after creation. You can increase principal and extend period via loan modification, modify individual installments, apply penalties, or record payments. Plan carefully before creating the loan.
</Warning>

## The 5-Step Loan Creation Process

### Overview of Steps

| Step                     | What You'll Do                                                     | Time Required |
| ------------------------ | ------------------------------------------------------------------ | ------------- |
| **1. Basic Information** | Select borrower, enter amount, period, and start date              | 2 minutes     |
| **2. Loan Rules**        | Configure interest, installment type, payment allocation, and fees | 3-5 minutes   |
| **3. Securities**        | Add guarantors, collateral, or savings lien                        | 2-3 minutes   |
| **4. Bank Details**      | Select bank account and enter bank charges (if any)                | 1 minute      |
| **5. Review & Submit**   | Review all details and create the loan                             | 1-2 minutes   |

Let's walk through each step in detail.

***

## Step 1: Basic Information

### Navigate to Loan Creation

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

  <Step title="Start loan creation">
    Click **"Create Loan"** button
  </Step>

  <Step title="Step 1 opens">
    The loan creation wizard displays the Basic Information form
  </Step>
</Steps>

### Enter Basic Loan Details

| Field                 | Description                       | Required | Example                |
| --------------------- | --------------------------------- | -------- | ---------------------- |
| **Organization User** | Member receiving the loan         | Yes      | John Mugisha           |
| **Principal Amount**  | Loan amount to disburse           | Yes      | 500,000 RWF            |
| **Period**            | Loan period in months             | Yes      | 12                     |
| **Start Date**        | Date loan starts (funds released) | Yes      | 2026-06-08             |
| **Purpose**           | Reason for the loan               | No       | Small business capital |

<Note>
  **First payment date**: Agatabo automatically calculates the first payment date as one month after the start date. For a loan starting on 2026-06-08, the first payment will be due on 2026-07-08.
</Note>

#### Example: Basic Information for a Business Loan

```
Organization User: Jane Uwase
Principal Amount: 1,000,000 RWF
Period: 24 months
Start Date: 2026-06-08
Purpose: Inventory purchase for retail shop
```

### Understanding Loan Period

**Loan period** = duration in months.

* **12 months** = 12 monthly payments
* **24 months** = 24 monthly payments
* **6 months** = 6 monthly payments

Agatabo generates monthly installments automatically based on the period.

<Steps>
  <Step title="Complete all required fields">
    Fill in organization user, principal amount, period, and start date
  </Step>

  <Step title="Click 'Next'">
    Proceeds to Step 2: Loan Rules
  </Step>
</Steps>

***

## Step 2: Loan Rules (Most Important)

This step defines **how interest is calculated** and **how payments are structured**. Understanding these options is critical to creating the right loan type.

<Warning>
  **These settings cannot be changed** after the loan is created. Take time to select the correct options. If you're unsure, consult [Loan Rules Explained](/tontines/loans/loan-rules-explained) for detailed examples.
</Warning>

### Interest Configuration

| Field                         | Description                 | Options                             | Example            |
| ----------------------------- | --------------------------- | ----------------------------------- | ------------------ |
| **Interest Rate**             | Percentage rate charged     | Any positive number                 | 5                  |
| **Interest Rate Type**        | How the rate is interpreted | MONTHLY, YEARLY                     | MONTHLY            |
| **Interest Calculation Type** | How interest is computed    | SIMPLE, COMPOUND, REDUCING\_BALANCE | REDUCING\_BALANCE  |
| **Interest Payment Timing**   | When interest is paid       | IN\_ADVANCE, WITH\_INSTALLMENTS     | WITH\_INSTALLMENTS |

#### Interest Rate Type

* **MONTHLY**: Rate applies each month (5% monthly = 5% × 12 = 60% annual effective)
* **YEARLY**: Annual rate divided across installments (12% yearly = 1% per month)

<Note>
  **Common practice**: Most tontines use MONTHLY rates for simplicity. Members understand "5% per month" more easily than annual percentage rates.
</Note>

#### Interest Calculation Type

<Tabs>
  <Tab title="SIMPLE">
    Interest calculated on original principal only, doesn't compound.

    **Formula**: `Total Interest = Principal × Rate × Term`

    **Example**: 100,000 RWF at 5% monthly for 12 months

    * Interest = 100,000 × 0.05 × 12 = 60,000 RWF
    * Total repayment = 160,000 RWF

    **Best for**: Short-term loans, small amounts, simple member understanding
  </Tab>

  <Tab title="COMPOUND">
    Interest calculated on principal + accumulated interest (compounds each period).

    **Formula**: `Amount = Principal × (1 + Rate)^Term`

    **Example**: 100,000 RWF at 5% monthly for 12 months

    * Total = 100,000 × (1.05)^12 = 179,586 RWF
    * Interest = 79,586 RWF

    **Best for**: Long-term loans, investment-focused lending
  </Tab>

  <Tab title="REDUCING_BALANCE (Most Common)">
    Interest calculated on the **outstanding balance** after each payment (principal reduces each month).

    **Example**: 100,000 RWF at 5% monthly for 12 months

    * Month 1 interest: 100,000 × 0.05 = 5,000 RWF
    * Month 2 interest: 91,667 × 0.05 = 4,583 RWF (less because principal reduced)
    * Total interest: \~32,000 RWF (varies based on installment type)

    **Best for**: Standard commercial-style loans, fair interest calculation
  </Tab>
</Tabs>

[See detailed examples with tables →](/tontines/loans/loan-rules-explained)

#### Interest Payment Timing

* **IN\_ADVANCE**: Interest deducted upfront (from savings or disbursement)
  * Example: 100,000 RWF loan with 12,000 RWF interest → interest paid from member's savings before disbursement
  * Installments repay principal only
  * Common in microfinance

* **WITH\_INSTALLMENTS** (default): Interest included in each payment
  * Example: 100,000 RWF loan → member receives full 100,000 RWF
  * Each installment includes principal + interest
  * Standard commercial loan structure

### Installment Configuration

| Field                        | Description                 | Options                                         | Example         |
| ---------------------------- | --------------------------- | ----------------------------------------------- | --------------- |
| **Installment Type**         | How payments are structured | EQUAL\_PRINCIPAL, EQUAL\_TOTAL                  | EQUAL\_TOTAL    |
| **Payment Allocation Order** | How payments are split      | INTEREST\_FIRST, PRINCIPAL\_FIRST, PROPORTIONAL | INTEREST\_FIRST |

#### Installment Type

<Tabs>
  <Tab title="EQUAL_PRINCIPAL">
    Each payment has the **same principal amount**, but interest decreases over time.

    **Example**: 120,000 RWF loan for 12 months at 5% reducing balance

    * Principal per payment: 120,000 ÷ 12 = 10,000 RWF
    * Month 1: 10,000 principal + 6,000 interest = 16,000 total
    * Month 2: 10,000 principal + 5,500 interest = 15,500 total
    * Month 12: 10,000 principal + 500 interest = 10,500 total

    **Payment pattern**: Starts high, decreases each month

    **Best for**: Members who want declining payment amounts
  </Tab>

  <Tab title="EQUAL_TOTAL (Most Common)">
    Each payment is the **same total amount** (amortized).

    **Example**: 120,000 RWF loan for 12 months at 5% reducing balance

    * All payments: \~13,000 RWF (calculated using amortization formula)
    * Month 1: 7,000 principal + 6,000 interest
    * Month 6: 9,500 principal + 3,500 interest
    * Month 12: 12,300 principal + 700 interest

    **Payment pattern**: Consistent payment amount

    **Best for**: Budgeting, predictable cash flow, standard loans
  </Tab>
</Tabs>

#### Payment Allocation Order

When a member makes a payment, how should it be split between principal and interest?

* **INTEREST\_FIRST**: Pay interest fully, then principal
  * Most common, ensures interest revenue is collected
  * Example: 10,000 RWF payment with 3,000 interest due → 3,000 to interest, 7,000 to principal

* **PRINCIPAL\_FIRST**: Pay principal fully, then interest
  * Reduces outstanding balance faster
  * Example: 10,000 RWF payment with 7,000 principal due → 7,000 to principal, 3,000 to interest

* **PROPORTIONAL**: Split payment based on the ratio of principal to interest
  * Fair allocation for partial payments
  * Example: 10,000 RWF payment with 7,000 principal + 3,000 interest due → 7,000 to principal, 3,000 to interest (70/30 split)

<Note>
  **Recommended for most loans**: Use REDUCING\_BALANCE interest calculation with EQUAL\_TOTAL installments and INTEREST\_FIRST payment allocation. This creates standard amortized loans that members understand.
</Note>

### Disbursement Fees (Optional)

Configure if your organization charges a loan disbursement fee:

| Field                     | Description                | Options                   |
| ------------------------- | -------------------------- | ------------------------- |
| **Disbursement Fee Type** | How the fee is calculated  | PERCENTAGE, FIXED\_AMOUNT |
| **Fee Amount/Percentage** | Fee value                  | 2% or 5,000 RWF           |
| **Deduct from Savings**   | Where fee is deducted from | Checked/Unchecked         |

**Fee Deduction Options:**

* **Deduct from cash**: Fee deducted from loan disbursement amount (member receives less cash)
* **Deduct from savings**: Fee deducted from member's savings balance (full disbursement amount released)

<Steps>
  <Step title="Configure all loan rules">
    Select interest calculation, installment type, payment allocation, and disbursement fees
  </Step>

  <Step title="Click 'Next'">
    Proceeds to Step 3: Securities
  </Step>
</Steps>

***

## Step 3: Securities

Securities protect the organization in case of default. Add one or more securities to meet the coverage requirement (total security value must cover the loan amount minus any deductions).

### Types of Securities

<Tabs>
  <Tab title="Guarantors">
    **Personal guarantees** from other organization users.

    * Select one or more guarantors from the member list
    * Guarantors commit to repaying if borrower defaults
    * Typically family members, friends, or business partners

    **Example**: Jane Uwase guarantees 100% of John Mugisha's 500,000 RWF loan
  </Tab>

  <Tab title="Collateral">
    **Physical assets** pledged against the loan.

    * Describe the asset (land title, vehicle, equipment)
    * Estimate collateral value
    * Note location and condition

    **Example**: Land title #12345, valued at 2,000,000 RWF, located in Kigali
  </Tab>

  <Tab title="Savings Lien">
    **Member's own savings** held as security.

    * Specify amount of member's savings frozen
    * Savings cannot be withdrawn until loan repaid
    * Automatic coverage if default occurs

    **Example**: 200,000 RWF of borrower's savings held until loan fully repaid
  </Tab>
</Tabs>

### Adding Securities

<Steps>
  <Step title="Select security type">
    Choose Guarantor, Collateral, or Savings
  </Step>

  <Step title="Enter details">
    * Guarantor: Select organization user and enter guaranteed amount
    * Collateral: Enter description, value, and upload documents
    * Savings: Enter amount of borrower's savings to pledge
  </Step>

  <Step title="Add multiple securities">
    Click "Add Security" to add more
  </Step>

  <Step title="Verify coverage">
    Ensure total security value meets requirement
  </Step>

  <Step title="Click 'Next'">
    Proceeds to Step 4: Bank Details
  </Step>
</Steps>

<Note>
  Securities are informational in Agatabo - they document the agreement but don't automatically enforce collection. Your organization's policies determine how securities are used in case of default.
</Note>

***

## Step 4: Bank Details

Select which bank account will disburse the loan and enter any bank charges:

| Field                  | Description                                   | Required |
| ---------------------- | --------------------------------------------- | -------- |
| **Bank Account**       | Account from which funds will be disbursed    | Yes      |
| **Bank Charge Amount** | Transaction fees charged by the bank (if any) | No       |

<Note>
  **Bank charges**: If your bank charges a fee for the transfer (e.g., mobile money fees, wire transfer fees), enter that amount here. It will be recorded as a bank charge expense.
</Note>

**Total bank outflow** = Loan amount - Disbursement fee (if deducted from cash) + Bank charge

<Steps>
  <Step title="Select bank account">
    Choose the account that will release the funds
  </Step>

  <Step title="Enter bank charges">
    If applicable, enter the transaction fee amount
  </Step>

  <Step title="Click 'Next'">
    Proceeds to Step 5: Review & Submit
  </Step>
</Steps>

***

## Step 5: Review & Submit

The final step displays a comprehensive summary of the loan for your review.

### What's Displayed

The review page shows:

* **Borrower details**: Name, email, account number, current savings balance
* **Loan terms**: Principal, period, start date, purpose
* **Interest configuration**: Rate, calculation type, installment type, payment allocation
* **Disbursement fees**: Fee type and amount (if configured)
* **Securities**: All added guarantors, collateral, and savings liens
* **Bank details**: Selected account and bank charges
* **Calculated totals**:
  * Total interest
  * Total repayment amount
  * Amount member will receive (after fees)

<Steps>
  <Step title="Review all details carefully">
    **This is your last chance to catch errors** - most settings cannot be changed after creation
  </Step>

  <Step title="Go back if needed">
    Use the back button to return to previous steps and make corrections
  </Step>

  <Step title="Click 'Submit Loan Application'">
    Creates the loan and disburses funds automatically
  </Step>
</Steps>

## What Happens Next

When you create the loan, Agatabo automatically:

1. **Generates installment schedule**: Calculates all monthly payment amounts and due dates

2. **Creates journal entries**:
   * **Dr LOAN\_RECEIVABLE**: Principal amount (asset)
   * **Dr INTEREST\_RECEIVABLE**: Total interest (if paid with installments)
   * **Cr CASH**: Principal amount minus fees (if deducted from cash)
   * **Cr INTEREST\_INCOME**: Total interest recognized
   * **Cr DISBURSEMENT\_FEE\_INCOME**: Fee amount (if charged)
   * **Dr BANK\_CHARGE\_EXPENSE / Cr CASH**: Bank charges (if applicable)

3. **Deducts from savings** (if configured):
   * Disbursement fee (if "deduct from savings" enabled)
   * Advance interest (if interest paid IN\_ADVANCE)

4. **Creates member's loan ledger account**: Tracks the outstanding balance

5. **Records in audit trail**: Logs all loan details with timestamp and user

6. **Sends notification** (if enabled): Borrower receives loan confirmation

7. **Updates analytics**: Dashboard shows updated Portfolio Outstanding

### Viewing the Created Loan

<Steps>
  <Step title="Navigate to Loans">
    **Loans** section shows all active loans
  </Step>

  <Step title="Find the loan">
    Search by borrower name or loan ID
  </Step>

  <Step title="View details">
    Click the loan to see installment schedule, payment history, and balance
  </Step>
</Steps>

[Learn how to view loan details →](/tontines/loans/viewing-loan-details)

## Common Scenarios

### Creating a Loan Larger Than Member's Savings

Some tontines have rules like "maximum loan = 3× member's savings balance."

<Note>
  **Loan eligibility validation:**

  * Agatabo enforces the max loan percentage rule (if configured in Settings → Rates)
  * If you try to create a loan exceeding the maximum, you'll get an error
  * Check member's current savings balance in **Organization Users → User Details**
  * Example: If max loan = 3× savings and member has 100,000 saved, maximum loan is 300,000
</Note>

### Creating a Loan with Irregular Payment Schedule

If the member needs to skip certain months or has a custom schedule:

1. Create the loan with standard monthly installments
2. After creation, modify individual installment due dates or amounts
3. Navigate to the loan details page and adjust the schedule

[Learn about modifying loans →](/tontines/loans/modifying-loans)

### Creating a Grace Period Loan

If the member should not pay for the first N months:

1. Create the loan normally (first payment will be 1 month after start date)
2. After creation, modify the first N installments by pushing their due dates forward
3. Example: For 3-month grace, move installments 1-3 to months 4-6
4. Interest will still accrue during grace period (depending on calculation type)

## Common Issues

<AccordionGroup>
  <Accordion title="'Insufficient cash to disburse' error">
    **Cause**: Organization doesn't have enough cash to release the loan amount.

    **Solution**:

    * Check **Bank Accounts** for current cash balance
    * Ensure recent deposits have been recorded
    * Verify no pending disbursements that haven't cleared
    * Consider reducing the loan amount
  </Accordion>

  <Accordion title="'Borrower not eligible' error">
    **Cause**: The organization user doesn't have member role or doesn't meet lending criteria.

    **Solution**:

    * Verify the user has been assigned a member role in **Organization Users**
    * Check if the member has any delinquent loans (some orgs block new loans until existing loans are current)
    * Consult lending policy requirements
  </Accordion>

  <Accordion title="Installment schedule looks wrong">
    **Cause**: Incorrect loan rules (interest type, calculation method, or installment structure).

    **Solution**:

    * **Before creating**: Go back to Step 2 and review all settings
    * **After creating**: Loans cannot be deleted, only modified. Contact accountant for guidance.
    * Consult [Loan Rules Explained](/tontines/loans/loan-rules-explained) for expected outcomes
  </Accordion>

  <Accordion title="Cannot select disbursement date in the past">
    **Cause**: Disbursement date falls in a closed accounting period.

    **Solution**:

    * Use today's date or a date in the current open period
    * If backdating is absolutely necessary, contact your accountant about period reopening (not recommended)

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

## Best Practices

<Note>
  **Loan creation tips:**

  * Use **REDUCING\_BALANCE** with **EQUAL\_TOTAL** for standard commercial-style loans
  * Use **INTEREST\_FIRST** allocation to ensure interest revenue is prioritized
  * Set **First Payment Date** exactly one month after disbursement for monthly loans
  * Always add at least one security (guarantor or collateral) for loans over a threshold
  * Document unusual terms or special agreements in the **Notes** field
  * Print or export the installment schedule to give to the borrower
  * Verify member's phone number and email for automatic payment reminders
</Note>

## Related Operations

After creating a loan, you may need to:

<CardGroup cols={2}>
  <Card title="Record Loan Payments" icon="money-bill-transfer" href="/loans/recording-loan-payments">
    Track member repayments and update balances
  </Card>

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

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

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

## Need Help?

<CardGroup cols={2}>
  <Card title="Loan Rules Explained" icon="book-open" href="/tontines/loans/loan-rules-explained">
    Detailed examples of interest calculations and installment types
  </Card>

  <Card title="Understanding Loan Terms" icon="spell-check" href="/reference/glossary">
    Definitions of all loan-related terminology
  </Card>

  <Card title="Loan Disbursement Workflow" icon="list-check" href="/workflows/loan-disbursement-workflow">
    Complete checklist for loan processing
  </Card>

  <Card title="Common Errors" icon="triangle-exclamation" href="/troubleshooting/common-errors">
    Troubleshooting guide for loan creation issues
  </Card>
</CardGroup>