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

# Securities and Guarantors

> Protect loans with guarantors, collateral, and savings liens - understand security blocking, coverage ratios, and automatic enforcement

## Overview

Securities protect the organization against loan default by providing recoverable assets or guarantees. When you add securities to a loan, Agatabo automatically blocks the pledged amounts to prevent double-pledging and enforces recovery during loan defaulting.

## Types of Securities

### Guarantor

**Personal guarantee** from another organization user (member).

**How it works**:

* Guarantor pledges a specific amount from their savings
* Amount is **blocked** - cannot be withdrawn or re-pledged
* If borrower defaults, guarantor's savings are automatically debited
* Multiple guarantors allowed per loan

**Example**: Jane guarantees 200,000 RWF of John's 500,000 RWF loan

* Jane's blocked security: 200,000 RWF
* Jane's available for withdrawal: Savings balance - 200,000 RWF

**Requirements**:

* Guarantor must have sufficient available savings
* Available savings = Total savings - Already blocked amounts
* Guarantor must be an organization user with savings account

### Collateral

**Physical asset** pledged against the loan.

**Common types**:

* Land titles
* Vehicles
* Equipment or inventory
* Livestock
* Property deeds

**How it works**:

* Borrower pledges asset with estimated value
* If borrower defaults, collateral recovery is marked as **pending**
* **Important**: If collateral exists, guarantor savings are NOT charged
* Organization must manually follow up to seize/sell collateral

**Documentation captured**:

* Description of asset
* Estimated value
* Location (optional)
* Condition (optional)

**Example**: Land title #12345, valued at 2,000,000 RWF, located in Kigali District

### Savings Lien

**Borrower's own savings** pledged as security.

**How it works**:

* Specified amount of member's savings is **blocked**
* Cannot be withdrawn until loan is fully repaid
* If borrower defaults, savings are automatically debited
* Reduces organization's risk

**Example**: John borrows 500,000 RWF and pledges 200,000 RWF from his 600,000 RWF savings

* John's blocked security: 200,000 RWF
* John's available for withdrawal: 400,000 RWF (600,000 - 200,000)

## Security Blocking Mechanism

When you add securities to a loan, Agatabo **blocks** the pledged amounts to prevent members from:

* Withdrawing pledged savings
* Using the same savings to guarantee multiple loans
* Over-pledging their available balance

### How Blocking Works

**For Guarantor Securities**:

* Pledged amount is blocked from guarantor's available savings
* Guarantor can still see full balance, but cannot withdraw blocked amount
* Blocked amount cannot be pledged for new loans

**For Savings Securities**:

* Pledged amount is blocked from borrower's available savings
* Borrower cannot withdraw the blocked amount
* Reduces available balance for future loan guarantees

**For Collateral Securities**:

* Does not block savings (physical asset, not cash)
* Captures asset details and estimated value

### Calculating Available Savings

**Formula**: `Available Savings = Total Savings - Blocked Security Amounts`

**Example**:

```
Jane's total savings: 800,000 RWF

Active loans Jane is guaranteeing:
- Loan A: 200,000 RWF guaranteed
- Loan B: 150,000 RWF guaranteed

Jane's blocked amount: 350,000 RWF
Jane's available savings: 450,000 RWF (800,000 - 350,000)

Can Jane guarantee 500,000 RWF? NO (only 450,000 available)
Can Jane withdraw 500,000 RWF? NO (only 450,000 available)
```

### Security Capacities

You can view security capacities to see how much each member has available for pledging:

**Navigate to**: Loans → Security Capacities

**Information shown**:

* Organization User
* Has Active Loan (yes/no)
* Savings Balance
* Blocked Security Amount
* Available Security Amount

**Use this to**:

* Verify guarantors have available capacity
* Check before creating new loans
* Monitor over-pledging risks

## Coverage Ratio

The **coverage ratio** is an organization setting that determines the minimum security required for loans.

**Default**: 100% (security must equal or exceed loan amount)

**How it works**:

* Total security value must be ≥ (Loan Amount × Coverage Ratio)
* System validates during loan creation
* Prevents under-secured loans

**Example with 100% coverage**:

```
Loan Amount: 500,000 RWF
Required Security: 500,000 RWF (500,000 × 100%)

Valid Security Combinations:
✅ 1 guarantor pledging 500,000 RWF
✅ Collateral valued at 500,000 RWF
✅ Borrower's savings lien of 500,000 RWF
✅ 2 guarantors (300,000 + 200,000)
✅ Mix: 200,000 savings + 300,000 guarantor

Invalid:
❌ 1 guarantor pledging 400,000 RWF (insufficient)
❌ Collateral valued at 300,000 RWF (insufficient)
```

**Example with 80% coverage**:

```
Loan Amount: 500,000 RWF
Required Security: 400,000 RWF (500,000 × 80%)

Valid:
✅ 1 guarantor pledging 400,000 RWF
✅ Collateral valued at 400,000 RWF
```

**Changing coverage ratio**: Settings → Loan Settings → Coverage Ratio

## Adding Securities to Loans

### During Loan Creation Only

**Important**: Securities can ONLY be added during loan creation. You cannot add or modify securities after a loan has been created.

<Steps>
  <Step title="Start loan creation wizard">
    Loans → Create Loan
  </Step>

  <Step title="Complete Steps 1 and 2">
    Basic information and loan rules
  </Step>

  <Step title="Step 3: Add Securities">
    Click "Add Security" button
  </Step>

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

  <Step title="Fill security details">
    **For Guarantor**:

    * Select organization user
    * Enter amount guaranteed

    **For Collateral**:

    * Enter description (required)
    * Enter estimated value
    * Optional: Location, condition

    **For Savings Lien**:

    * Amount to pledge from borrower's savings
  </Step>

  <Step title="Add multiple securities (optional)">
    Click "Add Another Security" to add more
  </Step>

  <Step title="Validation">
    System validates:

    * Guarantor has sufficient available savings
    * Borrower has sufficient savings for lien
    * Total security meets coverage ratio
  </Step>

  <Step title="Complete loan creation">
    Proceed to Step 4 (Bank Details) and finalize
  </Step>
</Steps>

### Validation During Creation

The system performs these checks:

**For Guarantor Securities**:

1. Guarantor exists and has savings account
2. Guarantor's available savings ≥ pledged amount
3. Available = Total savings - Blocked from other loans

**For Savings Securities**:

1. Borrower has sufficient savings
2. Available = Total savings - Blocked - Post-disbursement deductions
3. Post-disbursement deductions: fees + advance interest (if configured)

**For Collateral Securities**:

1. Description is provided
2. Value is specified

**Overall**:

1. Total security value ≥ (Loan amount × Coverage ratio)

<Warning>
  **Common validation failures**:

  * "Insufficient available savings for guarantor" - Guarantor has already pledged too much on other loans
  * "Insufficient savings for borrower" - Borrower doesn't have enough savings after accounting for fees
  * "Total security below required coverage" - Need more security or higher pledged amounts
</Warning>

## Automatic Enforcement During Default

When you default a loan, securities are **automatically enforced** - there is no manual "invoking guarantors" or "seizing collateral" step.

### Automatic Recovery Hierarchy

**Step 1: Borrower's Savings**

* System automatically debits from borrower's savings
* Up to pledged savings lien amount
* Limited to actual available balance

**Step 2: Collateral (if pledged)**

* System marks collateral recovery as **pending**
* Records pledged collateral value as recovered
* **Skips guarantors** (guarantor savings are NOT charged if collateral exists)
* Requires manual follow-up to physically seize/sell collateral

**Step 3: Guarantors' Savings (only if NO collateral)**

* For each guarantor:
  * Automatically debits from guarantor's savings
  * Up to pledged guarantee amount
  * Limited to guarantor's available balance
  * Respects blocked amounts from other loans

**Step 4: Bad Debt Write-off**

* Any remaining unrecovered amount
* Automatically posted as bad debt expense

[Learn more about loan defaulting →](/tontines/loans/loan-defaulting)

### Example: Automatic Recovery

```
Loan: 500,000 RWF principal, 100,000 RWF interest outstanding

Securities:
- Borrower's savings lien: 150,000 RWF
- Guarantor A: 200,000 RWF pledged
- Guarantor B: 200,000 RWF pledged

When you click "Default Loan":

1. Borrower's savings: 150,000 RWF recovered
2. Guarantor A savings: 200,000 RWF recovered
3. Guarantor B savings: 200,000 RWF recovered
4. Total recovered: 550,000 RWF
5. Outstanding: 600,000 RWF
6. Written off: 50,000 RWF (600,000 - 550,000)

Result: Automatic journal entry created, loan status changed to DEFAULTED
```

## Automatic Release of Securities

Securities are **automatically released** when a loan is no longer active. No manual action required.

### When Securities Are Released

**Loan Completed**:

* All installments paid
* All penalties paid
* Loan status changes to COMPLETED
* Securities automatically unblocked

**Loan Defaulted**:

* Loan status changes to DEFAULTED
* Securities automatically unblocked
* Recovery amounts already deducted

### How Release Works

**Blocking calculation**:

* System only counts securities from **ACTIVE** loans
* COMPLETED and DEFAULTED loans are excluded
* Blocked amount automatically decreases when loan completes

**Example**:

```
Jane's savings: 1,000,000 RWF

Active loans Jane is guaranteeing:
- Loan A: 300,000 RWF (ACTIVE)
- Loan B: 200,000 RWF (ACTIVE)

Jane's blocked: 500,000 RWF
Jane's available: 500,000 RWF

Loan A is fully repaid → status changes to COMPLETED

Active loans Jane is guaranteeing:
- Loan B: 200,000 RWF (ACTIVE)

Jane's blocked: 200,000 RWF (automatically updated)
Jane's available: 800,000 RWF (automatically increased)
```

## Guarantor Considerations

### Before Agreeing to Guarantee

If someone asks you to guarantee their loan, consider:

**Financial Risk**:

* Your savings will be blocked (unavailable for withdrawal)
* If borrower defaults, you'll lose the pledged amount
* May affect your ability to get your own loans

**Relationship Risk**:

* Can strain friendships or family ties
* Borrower may feel entitled to default ("it's just savings")
* Collection efforts may damage relationship

**Monitoring**:

* You cannot see borrower's payment status
* No notifications when borrower misses payments
* Find out only when loan defaults

<Warning>
  **Guarantor best practices**:

  * Only guarantee if you deeply trust the borrower
  * Understand you may lose the pledged amount
  * Consider it a gift, not a loan
  * Don't guarantee more than you can afford to lose
  * Verify borrower has repayment capacity
</Warning>

### Guarantor Rights

**What you can do**:

* View your own security capacities
* See your blocked amounts
* Check which loans you're guaranteeing

**What you CANNOT do**:

* Remove yourself as guarantor after loan creation
* Reduce pledged amount after loan creation
* View borrower's payment history
* Request release before loan completes

## Organization Settings

Settings that control security requirements and behavior:

### Coverage Ratio

**Path**: Settings → Loan Settings → Coverage Ratio

**Default**: 100% (security must equal loan amount)

**Range**: 0% - 200%

**Purpose**: Controls minimum security required for loans

### Disable Loan Defaulting

**Path**: Settings → Loan Settings → Disable Loan Defaulting

**Default**: false (defaulting enabled)

**Effect**: Prevents loan defaulting organization-wide

### Max Loan Percentage

**Path**: Settings → Loan Settings → Max Loan Percentage

**Default**: 300% (loan can be 3× savings balance)

**Purpose**: Limits loan amount relative to borrower's savings

### Deduct Fees from Savings

**Path**: Settings → Loan Settings

**Options**:

* Deduct Disbursement Fee from Savings
* Deduct Advance Interest from Savings

**Effect**: When enabled, fees/interest are deducted from savings instead of cash disbursement

**Security Impact**: Reduces available savings for pledging

## Viewing Securities

### On Loan Details Page

<Steps>
  <Step title="Navigate to loan">
    Loans → Select loan
  </Step>

  <Step title="View Securities section">
    Shows all securities attached to the loan
  </Step>

  <Step title="Information displayed">
    * Type (Guarantor, Collateral, Savings)
    * Organization User (for guarantor/savings)
    * Amount/Value
    * Description (for collateral)
  </Step>
</Steps>

### Security Capacities Report

<Steps>
  <Step title="Navigate to capacities">
    Loans → Security Capacities
  </Step>

  <Step title="View all members">
    Table shows:

    * Organization User
    * Savings Balance
    * Blocked Security Amount
    * Available Security Amount
  </Step>

  <Step title="Use for planning">
    Check before asking someone to guarantee
  </Step>
</Steps>

## Common Scenarios

### Scenario 1: Member Wants to Guarantee Multiple Loans

```
John's savings: 600,000 RWF

Request 1: Guarantee Jane's 300,000 RWF loan
✅ Available: 600,000 RWF → Can guarantee

After guaranteeing Jane:
Blocked: 300,000 RWF
Available: 300,000 RWF

Request 2: Guarantee Peter's 400,000 RWF loan
❌ Available: 300,000 RWF → CANNOT guarantee (insufficient)

Solution: John needs to increase savings or Jane must repay first
```

### Scenario 2: Loan with Mixed Securities

```
Loan Amount: 1,000,000 RWF
Coverage Ratio: 100%
Required Security: 1,000,000 RWF

Securities added:
- Borrower's savings: 200,000 RWF
- Guarantor A: 300,000 RWF
- Guarantor B: 300,000 RWF
- Collateral (vehicle): 200,000 RWF

Total: 1,000,000 RWF ✅ Meets requirement

If borrower defaults:
1. Recover 200,000 from borrower
2. Mark 200,000 collateral as pending (skips guarantors)
3. Write off remaining 600,000
```

### Scenario 3: Guarantor Has Active Loan

```
Jane's savings: 500,000 RWF

Jane's own loan:
- Borrowed: 300,000 RWF
- Pledged savings: 100,000 RWF

Jane's blocked: 100,000 RWF
Jane's available: 400,000 RWF

Request: Guarantee Peter's 500,000 RWF loan
❌ Available: 400,000 RWF → CANNOT guarantee full amount
✅ Can guarantee up to 400,000 RWF

Option: Peter finds second guarantor for remaining 100,000 RWF
```

## Best Practices

<Note>
  **Security management tips:**

  * Require securities for all loans (coverage ratio ≥ 100%)
  * Verify guarantor capacity before loan approval
  * Use Security Capacities report during loan committee meetings
  * Mix security types (savings + guarantor + collateral) for large loans
  * Conservative collateral valuation (80% of market value)
  * Document collateral thoroughly (photos, ownership proof)
  * Communicate security requirements clearly to borrowers
  * Don't allow same savings to be pledged multiple times (system prevents this)
  * Monitor guarantor concentration (one member guaranteeing too many loans)
</Note>

## Permissions Required

| Action                      | Permission       | Scope |
| --------------------------- | ---------------- | ----- |
| View loan securities        | `loans:read`     | ANY   |
| Create loan with securities | `loans:write`    | ANY   |
| View security capacities    | `loans:read`     | ANY   |
| Change coverage ratio       | `settings:write` | ANY   |

## Related Operations

<CardGroup cols={2}>
  <Card title="Creating Loans" icon="plus" href="/tontines/loans/creating-loans">
    Add securities during loan setup
  </Card>

  <Card title="Loan Defaulting" icon="triangle-exclamation" href="/tontines/loans/loan-defaulting">
    How securities are automatically enforced
  </Card>

  <Card title="Viewing Loan Details" icon="file-lines" href="/tontines/loans/viewing-loan-details">
    Check securities on existing loans
  </Card>

  <Card title="Loan Analytics" icon="chart-line" href="/tontines/loans/loan-analytics">
    Monitor security coverage metrics
  </Card>
</CardGroup>