> ## Documentation Index
> Fetch the complete documentation index at: https://afrizon-admin.tunzaa.co.tz/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage vendor loan requests and repayments

> Review and action vendor loan requests end-to-end — from provider registration and product setup through disbursement and repayment tracking.

Meneja's vendor loan feature connects your marketplace vendors with loan providers so vendors can access working capital directly through the platform. As an admin, you register loan providers, configure loan products for each provider, and then oversee the full lifecycle of every loan request — from initial submission by a vendor through to approval, disbursement, and repayment. All operations are available through the dashboard as well as the REST API.

## Loan providers

A loan provider is a financial institution or lending organisation that offers loan products to your vendors. You must register at least one provider before vendors can apply for loans.

| Field           | Description                                             |
| --------------- | ------------------------------------------------------- |
| `business_name` | Legal trading name of the provider                      |
| `contact_email` | Primary contact email                                   |
| `contact_phone` | Primary contact phone number                            |
| `description`   | Description of the provider and their offering          |
| `website`       | Provider's website (optional)                           |
| `address`       | Physical address (optional)                             |
| `is_active`     | Whether the provider is available for new loan products |
| `status`        | Current review status of the provider record            |

Provider statistics — `total_loans`, `loan_growth`, `avg_loan_value`, and `repayment_rate` — are aggregated automatically and visible on the provider's detail page.

### Register a provider

Send a `POST` request to `/v1/loans/providers/` with the provider's details:

```json theme={null}
{
  "tenant_id": "tenant-123",
  "user_id": "user-456",
  "business_name": "Fast Cash Loans",
  "contact_email": "contact@fastcash.com",
  "contact_phone": "+255700000000"
}
```

To list all providers registered to your tenant, send a `GET` request to `/v1/loans/providers/` with the `X-Tenant-ID` header.

## Loan products

Each provider offers one or more loan products. A product defines the financial terms that apply to any loan a vendor takes under that product.

| Field                 | Type    | Description                                                                |
| --------------------- | ------- | -------------------------------------------------------------------------- |
| `name`                | string  | Product display name                                                       |
| `interest_rate`       | number  | Interest rate as a percentage                                              |
| `interest_period`     | enum    | Period the rate applies to: `DAILY`, `WEEKLY`, `MONTHLY`, or `YEARLY`      |
| `interest_rate_type`  | enum    | How interest compounds: `FLAT`, `REDUCING`, or `REDUCING_BALANCE`          |
| `term_duration`       | number  | Length of the loan term                                                    |
| `term_unit`           | enum    | Unit for the term: `DAYS`, `WEEKS`, `MONTHS`, or `YEARS`                   |
| `repayment_frequency` | enum    | How often repayments are due: `DAILY`, `WEEKLY`, `BI_WEEKLY`, or `MONTHLY` |
| `min_amount`          | number  | Minimum loan amount (optional)                                             |
| `max_amount`          | number  | Maximum loan amount (optional)                                             |
| `processing_fee`      | number  | Upfront fee charged on disbursement (optional)                             |
| `charges`             | object  | Additional fees specific to this product                                   |
| `description`         | string  | Product description shown to vendors (optional)                            |
| `terms_conditions`    | string  | Terms and conditions text (optional)                                       |
| `is_active`           | boolean | Whether the product is available for new requests                          |

### Create a loan product

Send a `POST` request to `/v1/loans/products/` with the product definition:

```json theme={null}
{
  "provider_id": "{{provider_id}}",
  "name": "Small Biz Quick Loan",
  "interest_rate": 5.0,
  "interest_period": "MONTHLY",
  "interest_rate_type": "FLAT",
  "term_duration": 3,
  "term_unit": "MONTHS",
  "repayment_frequency": "MONTHLY",
  "charges": {}
}
```

To retrieve all products for a given provider, send a `GET` request to `/v1/loans/products/provider/{provider_id}`.

## Loan requests

When a vendor applies for a loan, Meneja creates a `LoanRequest` record. You review, approve, and disburse loans from the **Vendor Loans** section of the dashboard.

### Loan request fields

| Field               | Description                                                |
| ------------------- | ---------------------------------------------------------- |
| `vendor_id`         | The vendor applying for the loan                           |
| `product_id`        | The loan product selected by the vendor                    |
| `loan_amount`       | The amount approved for the loan                           |
| `amount_requested`  | The amount the vendor originally requested                 |
| `interest_rate`     | Rate inherited from the product at the time of application |
| `payment_frequency` | `weekly`, `bi-weekly`, or `monthly`                        |
| `term_length`       | Loan duration in months                                    |
| `total_payable`     | Total amount due including interest and fees               |
| `remaining_balance` | Outstanding balance on an active loan                      |
| `purpose`           | Vendor-provided reason for the loan                        |
| `status`            | Current lifecycle status (see below)                       |
| `payment_schedule`  | Array of scheduled installments                            |
| `documents`         | Supporting documents submitted with the application        |
| `penalties`         | Any penalties applied for missed or late payments          |

### Loan statuses

| Status      | Meaning                                         |
| ----------- | ----------------------------------------------- |
| `pending`   | Submitted by the vendor, awaiting admin review  |
| `approved`  | Approved by the admin, awaiting disbursement    |
| `rejected`  | Declined — `rejection_reason` is populated      |
| `disbursed` | Funds have been released to the vendor          |
| `active`    | Loan is live and repayments are being collected |
| `completed` | All repayments received, loan closed            |
| `defaulted` | Vendor has failed to meet repayment obligations |

## The loan lifecycle

<Steps>
  <Step title="Vendor submits a loan request">
    The vendor selects a product and submits a request via the marketplace. Meneja sends a `POST` to `/v1/loans/requests` with the following payload:

    ```json theme={null}
    {
      "product_id": "{{product_id}}",
      "borrower_id": "user-789",
      "amount_requested": 10000.0
    }
    ```

    The request is created with `status: pending`. You can retrieve it at any time with a `GET` to `/v1/loans/requests/{request_id}`.
  </Step>

  <Step title="Admin reviews the request">
    Open **Growth Tools → Vendor Loans → Requests** in the dashboard. Click the request to view the vendor's profile, the loan product terms, the requested amount, the stated purpose, and any supporting documents.

    The vendor details panel shows business registration information, KYC documents, bank details, transaction statistics, outstanding payments, and current orders — giving you the context needed to assess creditworthiness.
  </Step>

  <Step title="Approve or reject the request">
    To approve, send a `POST` to `/v1/loans/requests/{request_id}/approve`. This moves the status to `approved` and stamps `approved_at` and `approved_by`.

    To reject, update the status to `rejected` and provide a `rejection_reason` so the vendor understands why their application was declined.
  </Step>

  <Step title="Disburse the loan">
    Once approved, disburse funds by sending a `POST` to `/v1/loans/{loan_id}/disburse`. This moves the status to `disbursed` and stamps `disbursed_at` and `disbursed_by`. The loan then transitions to `active` once the payment schedule begins.

    The loan record is created at this point, containing the `principal_amount`, `total_expected_interest`, `total_fees`, `outstanding_balance`, the full `schedules` array, and a `repayments` array.
  </Step>

  <Step title="Track repayments">
    Each installment in the payment schedule has a status of `pending`, `upcoming`, `paid`, `overdue`, or `partial`. As the vendor makes payments, record each repayment with a `POST` to `/v1/loans/{loan_id}/repayments`:

    ```json theme={null}
    {
      "amount": 3500.0,
      "method": "m-pesa"
    }
    ```

    Each repayment record captures the `amount_paid`, `payment_method`, `payment_date`, optional `reference_number`, and a status of `COMPLETED`, `PENDING`, `FAILED`, or `SUCCESS`.
  </Step>

  <Step title="Close or flag the loan">
    When all scheduled payments are received, the loan status moves to `completed`. If a vendor misses payments beyond the allowed threshold, update the status to `defaulted` and record a penalty with the `amount`, `reason`, and `applied_at` timestamp.
  </Step>
</Steps>

## Payment schedules

Each active loan has a payment schedule — one entry per installment — generated at disbursement.

| Field                | Description                                                  |
| -------------------- | ------------------------------------------------------------ |
| `installment_number` | Sequence number of this payment                              |
| `principal_due`      | Principal portion of this installment                        |
| `interest_due`       | Interest portion of this installment                         |
| `fees_due`           | Any fees due with this installment                           |
| `amount_due`         | Total amount due (`principal_due + interest_due + fees_due`) |
| `due_date`           | Date the payment is expected                                 |
| `status`             | `PAID`, `PENDING`, or `OVERDUE`                              |

<Note>
  You can retrieve the full schedule and repayment history for any active loan with a `GET` request to `/v1/loans/{loan_id}`.
</Note>

## Penalties

If a vendor misses or underpays an installment, you can apply a penalty:

| Field        | Description                                          |
| ------------ | ---------------------------------------------------- |
| `amount`     | Penalty amount in the local currency                 |
| `reason`     | Description of the breach that triggered the penalty |
| `applied_at` | When the penalty was recorded                        |
| `status`     | `pending`, `paid`, or `waived`                       |
| `paid_at`    | Populated when the penalty is settled                |

<AccordionGroup>
  <Accordion title="Can I offer products from multiple providers?">
    Yes. Register each provider separately under `/v1/loans/providers/` and then create products under each provider. Vendors see all active products when they apply.
  </Accordion>

  <Accordion title="How do I filter loan requests by status?">
    The loan requests list can be filtered by `status`, `vendor_id`, `product_id`, `provider_id`, amount range (`min_amount`, `max_amount`), and date range (`start_date`, `end_date`).
  </Accordion>

  <Accordion title="What vendor information is available during review?">
    The vendor details panel on a loan request shows KYC documents (business license, business certificate, TRA certificate), bank details, business registration information, and transaction statistics such as total transaction count, total value, and last transaction date.
  </Accordion>
</AccordionGroup>