Loans

The loan system supports six product types with a multi-level approval workflow. Users apply, upload documents, and track their application through approval levels — from loan officer to board.

Loan Products

Product	Amount Range	Typical Tenure	Approval Speed
Quick Cash	₦5,000 – ₦500,000	1–6 months	24 hours
Personal	₦100,000 – ₦10,000,000	3–36 months	3–5 days
Salary Advance	₦10,000 – ₦200,000	5 days	Same day
Mortgage	₦1,000,000+	60–360 months	2–4 weeks
Asset Finance	Varies	12–60 months	1–2 weeks
Business	₦500,000 – ₦50,000,000	6–60 months	1–2 weeks

List Available Products

GET /api/v1/loan-products

Calculate Repayment

GET /api/v1/loan-products/:id/calculator?amount=500000&tenureMonths=12

{
  "success": true,
  "data": {
    "requestedAmount": 500000.00,
    "tenureMonths": 12,
    "interestRate": 18.5,
    "monthlyRepayment": 45833.33,
    "totalInterest": 50000.00,
    "totalRepayment": 550000.00
  }
}

Application Flow

                    ┌───────────┐
                    │ Eligibility│
                    │   Check   │
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │  Submit    │
                    │Application │
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │  Upload    │
                    │ Documents  │
                    └─────┬─────┘
                          │
              ┌───────────▼───────────┐
              │   Approval Workflow   │
              │  (multi-level review) │
              └───────────┬───────────┘
                          │
                 ┌────────┼────────┐
                 ▼                 ▼
           ┌──────────┐    ┌──────────┐
           │ Approved │    │ Rejected │
           └────┬─────┘    └──────────┘
                │
          ┌─────▼─────┐
          │Disbursement│
          │ (to wallet)│
          └─────┬─────┘
                │
          ┌─────▼─────┐
          │ Repayment  │
          │  Schedule  │
          └───────────┘

Step 1: Check Eligibility

GET /api/v1/loans/eligibility

{
  "success": true,
  "data": {
    "eligible": true,
    "maxAmount": 2000000.00,
    "availableProducts": ["quick_cash", "personal", "salary_advance"],
    "existingLoans": 0,
    "creditScore": 720
  }
}

Step 2: Submit Application

cURL

curl -X POST https://api.korastratum.com/api/v1/banking/loans/apply \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: fmfb" \
  -H "Content-Type: application/json" \
  -d '{
    "productType": "personal",
    "requestedAmount": 500000.00,
    "tenureMonths": 12,
    "loanPurpose": "Business expansion",
    "employmentStatus": "self_employed",
    "monthlyIncome": 200000.00
  }'

Node.js

const res = await fetch(
  "https://api.korastratum.com/api/v1/banking/loans/apply",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "X-Tenant-ID": "fmfb",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      productType: "personal",
      requestedAmount: 500000.0,
      tenureMonths: 12,
      loanPurpose: "Business expansion",
      employmentStatus: "self_employed",
      monthlyIncome: 200000.0,
    }),
  }
);

Python

res = requests.post(
    "https://api.korastratum.com/api/v1/banking/loans/apply",
    headers={"Authorization": f"Bearer {token}", "X-Tenant-ID": "fmfb"},
    json={
        "productType": "personal",
        "requestedAmount": 500000.00,
        "tenureMonths": 12,
        "loanPurpose": "Business expansion",
        "employmentStatus": "self_employed",
        "monthlyIncome": 200000.00,
    },
)

Response:

{
  "success": true,
  "data": {
    "applicationId": "d4c3b2a1-...",
    "applicationNumber": "LN20260227001",
    "status": "submitted",
    "approvalStatus": "pending",
    "requestedAmount": 500000.00,
    "approvedAmount": null,
    "tenure": 12,
    "interestRate": null,
    "approvalLevel": "loan_officer",
    "nextReviewDate": "2026-02-28T00:00:00Z",
    "documents": {
      "required": ["proof_of_income", "bank_statement", "id_document"],
      "uploaded": []
    }
  }
}

Step 3: Upload Documents

POST /api/v1/loans/documents/upload

Submit as multipart/form-data with the loan application ID and document type.

Step 4: Track Approval

GET /api/v1/loans/approval-status

Approval Workflow

The required approval level depends on the loan amount:

Amount Range	Approval Level
≤ ₦500,000	Loan Officer
≤ ₦2,000,000	Senior Loan Officer
≤ ₦10,000,000	Branch Manager
≤ ₦50,000,000	Regional Manager
≤ ₦100,000,000	Credit Committee
> ₦100,000,000	Board

Applications progress through levels automatically. Each level can approve, reject, or escalate.

Disbursement

Once approved, the loan amount is credited directly to the user's primary wallet. The response includes the approved terms:

{
  "success": true,
  "data": {
    "applicationId": "d4c3b2a1-...",
    "status": "disbursed",
    "approvedAmount": 500000.00,
    "interestRate": 18.5,
    "monthlyRepayment": 45833.33,
    "firstPaymentDate": "2026-03-27",
    "disbursementWalletId": "a1b2c3d4-..."
  }
}

Repayment

View Schedule

GET /api/v1/loans/repayment-schedule

{
  "success": true,
  "data": {
    "schedule": [
      {
        "installment": 1,
        "dueDate": "2026-03-27",
        "principal": 41666.67,
        "interest": 4166.67,
        "total": 45833.33,
        "status": "pending"
      }
    ],
    "totalPrincipal": 500000.00,
    "totalInterest": 50000.00,
    "totalAmount": 550000.00
  }
}

Make a Payment

POST /api/v1/loans/repay

{
  "loanId": "d4c3b2a1-...",
  "amount": 45833.33,
  "sourceWalletId": "a1b2c3d4-..."
}

List User's Loans

GET /api/v1/loans

Returns all loans with their current status, outstanding balance, and next payment date.

Next Steps

• Savings — Savings products and interest rates.
• Accounts & Wallets — Wallet management for disbursement.
• Error Codes — Loan-specific error codes.