<aside> 💡

Purpose: This document provides a comprehensive explanation of how CANDID calculates Annual Percentage Rate (APR) for mortgage loan scenarios displayed to consumers. It covers all inputs, assumptions, data sources, and methodologies used in the calculation engine.

⚠️ Regulatory Context: APR calculations are governed by the Truth in Lending Act (TILA), Regulation Z (12 CFR Part 1026), and the Homeowners Protection Act (HPA). All methodology described herein is designed to comply with these requirements.

</aside>


🏗️ System Architecture Overview

CANDID's APR calculation uses a three-layer stack:

  1. CANDID (Front End) — Collects loan scenario inputs from the user interface and constructs a structured payload
  2. Middleware — Receives the payload, maps it to a ZMathBuffer input structure, and calls the calculation engine
  3. ZMathEngine (Mathcorp DLL) — A certified third-party Regulation Z APR calculation engine that performs all APR math per Appendix J of Regulation Z

The engine returns tapr2 — the exact APR per Appendix J of Regulation Z.


1️⃣ Amount Financed Calculation

📌 Definition

The Amount Financed (amount_financed2) is calculated by the ZMathEngine as:

Amount Financed = Gross Loan Amount − Total Prepaid Finance Charges

📥 Inputs Used

Input Field Source Description
baseAmount CANDIDUI Purchase price minus down payment. Does not include financed MIP unless explicitly added
totalCostsAddedToLoan CANDID Any closing costs rolled into the loan amount.
totalPrepaidFinanceCharges CANDID Dollar amount of APR-affecting fees paid at closing
prepaidInterestAddedToLoan CANDID Currently always false
mip CANDID Upfront mortgage insurance premium dollar amount. Passed to pmi1 in the engine

🔍 What Is and Is Not Included

Included in Amount Financed calculation:

Excluded from Amount Financed: