Loan Origination

Create new loans from application through disbursement, including borrower setup, term configuration, and approval workflows.

Before You Begin

Gather the following before creating a new loan. Missing any of these items will block the origination process.

  • ✓Borrower in CRM: The borrowing entity must already exist in the CRM module. Navigate to CRM → Entities and create the entity first if needed.
  • ✓Agreed Loan Terms: Principal amount, interest rate, term in months, payment frequency, origination date, first payment date, and maturity date.
  • ✓Role Permissions: You must have ADMIN, TREASURY, or STAFF role. Loans of $50,000 or more require maker-checker approval from a second authorized user.
  • ✓Collateral Details (if applicable): Collateral type, appraised value, and description for secured loans.

Step-by-Step: Create a New Loan

  1. Navigate to Loans: Open the sidebar and click Loans. You will see the loan list with filters for status, borrower, and date range.
  2. Click "+ New Loan": This opens the LoanModal, a multi-section form with 12 collapsible sections.
  3. Fill in Basic Information (required):
    • loan_number -- Unique identifier (e.g., LN-2026-0042)
    • borrower_name / borrower_id -- Select from CRM entities
    • principal_amount -- Loan amount in dollars
    • interest_rate -- Annual rate as a decimal (e.g., 5.25)
    • term_months -- Loan duration in months
    • payment_frequency -- MONTHLY, QUARTERLY, SEMI_ANNUAL, ANNUAL, INTEREST_ONLY, or BALLOON
    • origination_date -- Date the loan is booked
    • first_payment_date -- When the first payment is due
    • maturity_date -- Final payoff date
  4. Configure Optional Sections: Expand any of the collapsible sections to set collateral, late fee rules, rate type (fixed vs. variable), loan purpose, and notes.
  5. Set Loan Status: New loans default to PENDING. Change to ACTIVE once disbursement is confirmed.
  6. Save the Loan: Click Save. The system calls POST /api/v1/loans and returns the new loan record with its UUID.

Important: Loans with a principal amount of $50,000 or more automatically trigger the maker-checker approval workflow. The API returns HTTP 202 with an approval_id instead of creating the loan immediately. A second authorized user must approve the request in the Approvals queue before the loan is created.

Loan Types

CEF Core supports three primary loan structures. Select the appropriate type during origination to configure the correct amortization and draw behavior.

Term Loan (Standard)

The most common loan type for church building projects and capital improvements. A fixed principal disbursed at closing with regular payments over the term.

  • Amortization: FULLY_AMORTIZING or BALLOON
  • Payment frequency: typically MONTHLY
  • Single disbursement at origination

Line of Credit (LOC)

Revolving credit facility that allows the borrower to draw funds up to the approved limit, repay, and re-draw.

  • Amortization: INTEREST_ONLY on drawn balance
  • Multiple draws via the draw management interface
  • Interest accrues only on the outstanding drawn balance

Construction Loan

Draw-based loan for new construction or major renovation projects. Funds are released in stages tied to inspection milestones.

  • Amortization: INTEREST_ONLY during construction, converts to FULLY_AMORTIZING
  • Draws require inspection approval before release
  • Use POST /loans/:id/convert to convert to permanent financing

Interest Rate Configuration

Each loan must be configured as either fixed-rate or variable-rate at origination. Rate type affects how interest is calculated on the amortization schedule.

Fixed Rate

The interest rate remains constant for the life of the loan.

  • Set interest_rate to the annual rate
  • No index or margin fields needed
  • Predictable payments for budgeting

Variable Rate

The rate adjusts periodically based on a reference index plus a margin.

  • rate_index: SOFR, PRIME, or TREASURY
  • rate_margin: spread above index (e.g., 2.50)
  • rate_floor / rate_ceiling: min/max bounds
  • Use rate-reset to apply new index values

API Reference

Loan origination uses the following endpoints. All requests require authentication via JWT bearer token.

MethodEndpointDescription
POST/api/v1/loansCreate a new loan
GET/api/v1/loansList loans (paginated, filterable by status/borrower)
GET/api/v1/loans/:idGet a single loan by UUID

Pro Tip: When calling the API from the frontend, always use the authFetch helper from @/lib/auth-fetch. It handles JWT authentication, token refresh, and error handling automatically.

Maker-Checker Approval Workflow

CEF Core enforces the four-eyes principle for high-value transactions. Any loan with a principal amount of $50,000 or more requires a second user to approve the origination.

  1. Maker submits the loan: The API returns HTTP 202 Accepted with an approval_id.
  2. Approval notification: Authorized approvers receive a notification (checked every 30 minutes by the scheduler).
  3. Checker reviews and approves: Navigate to Admin → Approvals, review the loan details, and click Approve or Reject.
  4. Loan is created: Once approved, the scheduler executes approved requests every 15 minutes and the loan appears in the loan list with PENDING status.

Note: The same user who submitted the loan cannot approve it. The checker must be a different user with ADMIN or TREASURY role.

Next Steps

After originating a loan, learn how to record payments, generate amortization schedules, and configure late fee rules.

Payment Processing Guide
← Previous: Your First LoanNext: Payment Processing →