Appearance
Credit Scoring Engine
The Credit Scoring Engine provides a configurable, weighted scorecard system for evaluating borrower creditworthiness during loan application processing. Scores are calculated automatically from client data, with manual overrides available.
Navigation: Administration → Products → Loan Products → Credit Score Cards
Overview
The engine follows the industry-standard 5C model (Character, Capacity, Capital, Conditions, Collateral) and supports:
- Weighted criteria — each factor carries a configurable weight
- Point ranges — map raw values to point scores (numeric ranges, categories, booleans)
- Risk grades — translate final scores into approval decisions (A–E)
- Auto-resolve — pull client data automatically from the system (age, tenure, DTI, balances)
- Manual input — officers can enter values for criteria that require judgement
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Score Card │────▶│ Criteria │────▶│ Ranges │
│ (template) │ │ (factors) │ │ (value→pts) │
└──────────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────┐ ┌──────────────┐
│ Grades │────▶│ Decision │
│ (A/B/C/D/E) │ │ (approve/ │
│ │ │ review/ │
│ │ │ reject) │
└──────────────┘ └──────────────┘Key Concepts
| Concept | Description |
|---|---|
| Score Card | A named scorecard template with a score range (e.g. 0–1000) and version |
| Criterion | A single scoring factor (e.g. Client Age, DTI Ratio) with a weight and max points |
| Range | A mapping rule within a criterion: "if value is 26–35, award 70 points" |
| Grade | A risk tier defined by score thresholds: "600–799 = Grade B = Auto Approve" |
| Data Source | Where the raw value comes from — AUTO (system-resolved) or MANUAL (officer input) |
| Evaluation Type | How values are matched: NUMERIC_RANGE, CATEGORY, or BOOLEAN |
Score Cards
Score cards are managed from the Credit Score Cards tab on the Loan Products page.
Score Card Fields
| Field | Description | Required |
|---|---|---|
| Card Name | Descriptive name (e.g. "Standard Risk Card") | Yes |
| Model Version | Version tag (e.g. "v1.0") | Yes |
| Score Min | Minimum possible score (default 0) | No |
| Score Max | Maximum possible score (default 1000) | No |
Actions
- Create — add a new score card
- Edit — modify card name/version/range
- Configure — open the criteria & grades management dialog
- Delete — remove a score card
Configuring a Score Card
Click the Configure (⚙) action on a score card row to open the configuration dialog with two tabs:
Scoring Criteria Tab
Each criterion represents a factor in the credit assessment.
| Field | Description |
|---|---|
| Code | Unique identifier (e.g. CLIENT_AGE, DTI_RATIO) |
| Name | Display name |
| Category (5C) | CHARACTER, CAPACITY, CAPITAL, CONDITIONS, COLLATERAL, or CUSTOM |
| Evaluation Type | NUMERIC_RANGE, CATEGORY, or BOOLEAN |
| Data Source | AUTO (system resolves) or MANUAL (officer enters) |
| Auto Source | When AUTO, which system data point to pull (see Data Sources below) |
| Weight | Relative importance (0.00–1.00). All weights should sum to 1.0 |
| Max Points | Maximum points this criterion can award |
| Default Points | Points when no range matches (fallback) |
| Required | Whether this criterion must have a value to evaluate |
Point Ranges
Each criterion has one or more ranges that map raw values to point scores:
For NUMERIC_RANGE:
| Range Label | Min (≥) | Max (<) | Points |
|---|---|---|---|
| 18–25 | 18 | 25 | 30 |
| 26–35 | 26 | 35 | 70 |
| 36–50 | 36 | 50 | 100 |
| 51+ | 51 | 120 | 60 |
For CATEGORY: Each range specifies a category value (e.g. "MALE", "MARRIED").
For BOOLEAN: Each range specifies true (1) or false (0).
Risk Grades Tab
Grades map final scores to risk tiers and approval decisions.
| Field | Description |
|---|---|
| Code | Grade code (e.g. A, B, C, D, E) |
| Name | Display name (e.g. "Excellent", "Good") |
| Min Score | Lower bound of score range (inclusive) |
| Max Score | Upper bound of score range (inclusive) |
| Decision | AUTO_APPROVE, MANUAL_REVIEW, or AUTO_REJECT |
| Rate Adj (bps) | Interest rate adjustment in basis points (e.g. +50bps for Grade B) |
| Max LTV % | Maximum loan-to-value percentage (optional) |
| Color | Hex color for UI display |
Example Grade Scale (0–1000):
| Grade | Range | Decision | Rate Adjustment |
|---|---|---|---|
| A — Excellent | 800–1000 | Auto Approve | +0 bps |
| B — Good | 600–799 | Auto Approve | +50 bps |
| C — Fair | 400–599 | Manual Review | +150 bps |
| D — Poor | 200–399 | Manual Review | +300 bps |
| E — Very Poor | 0–199 | Auto Reject | +500 bps |
Available Data Sources
When a criterion uses AUTO data source, the engine resolves the value from client/application data at evaluation time. Available sources:
| Code | Label | Category | Type |
|---|---|---|---|
CLIENT_AGE | Client Age (years) | CHARACTER | NUMERIC_RANGE |
CLIENT_GENDER | Client Gender | CHARACTER | CATEGORY |
MARITAL_STATUS | Marital Status | CHARACTER | CATEGORY |
CUSTOMER_TENURE_MONTHS | Customer Tenure (months) | CHARACTER | NUMERIC_RANGE |
EXISTING_LOAN_COUNT | Active Loan Count | CHARACTER | NUMERIC_RANGE |
ARREARS_LOAN_COUNT | Loans in Arrears Count | CHARACTER | NUMERIC_RANGE |
DTI_RATIO | Debt-to-Income Ratio | CAPACITY | NUMERIC_RANGE |
AFFORDABILITY_RATIO | Affordability Ratio | CAPACITY | NUMERIC_RANGE |
MONTHLY_GROSS_INCOME | Monthly Gross Income | CAPACITY | NUMERIC_RANGE |
MONTHLY_NET_INCOME | Monthly Net Income | CAPACITY | NUMERIC_RANGE |
MONTHLY_EXPENSES | Monthly Expenses | CAPACITY | NUMERIC_RANGE |
DISPOSABLE_INCOME | Disposable Income | CAPACITY | NUMERIC_RANGE |
SAVINGS_BALANCE | Savings / Deposit Balance | CAPITAL | NUMERIC_RANGE |
TOTAL_OUTSTANDING_DEBT | Total Outstanding Debt | CAPITAL | NUMERIC_RANGE |
COLLATERAL_COVERAGE | Collateral Coverage Ratio | COLLATERAL | NUMERIC_RANGE |
REQUESTED_AMOUNT | Requested Loan Amount | CONDITIONS | NUMERIC_RANGE |
Evaluating a Loan Application
During loan application processing, the Credit Scoring stage includes the scoring engine:
Workflow
- Select Score Card — choose which scorecard to evaluate against
- Click Evaluate — the engine:
- Loads all active criteria for the selected card
- For each AUTO criterion, resolves the value from client/application data
- Matches each value against configured ranges to determine points
- Calculates weighted score:
Σ(points × weight) / Σ(max_points × weight) × score_max - Looks up the matching grade based on the final score
- Review Breakdown — the evaluator displays:
- Per-criterion results (raw value, matched range, points, weight, weighted score)
- Total score, weighted score, assigned grade, and decision
- Auto-Fill — results automatically populate the form fields:
- Score, Risk Grade, Pass/Fail, Application Score
- Credit Assessment JSON (full breakdown for audit)
- Override — officers can manually adjust any field before submitting
Score Calculation
For each criterion:
weighted_points = points_earned × weight
Total weighted = Σ weighted_points
Maximum weighted = Σ (max_points × weight)
Final score = (Total weighted / Maximum weighted) × score_maxExample:
| Criterion | Points | Weight | Weighted |
|---|---|---|---|
| Client Age (32 yrs → "26–35") | 70 | 0.30 | 21.0 |
| DTI Ratio (0.28 → "Good 20–35%") | 75 | 0.40 | 30.0 |
| Customer Tenure (18 mo → "1–3 years") | 80 | 0.30 | 24.0 |
| Totals | 1.00 | 75.0 / 100.0 |
Final score = 75.0 / 100.0 × 1000 = 750 → Grade B (Good) → Auto Approve
Permissions
| Permission | Description |
|---|---|
CREATE_CREDIT_SCORE_CARD | Create new credit score card templates |
UPDATE_CREDIT_SCORE_CARD | Edit score cards, manage scoring criteria, ranges, and risk grades |
DELETE_CREDIT_SCORE_CARD | Remove score cards and their associated criteria and grades |
VIEW_CREDIT_SCORE_CARD | View score cards, criteria, ranges, grades, and data sources |
EVALUATE_CREDIT_SCORECARD | Run the scoring engine during loan application processing |
VIEW_CREDIT_SCORE_HISTORY | View client credit score history records |
API Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /credit-score-card-criteria | List criteria for a score card |
| POST | /credit-score-card-criteria | Save (upsert) criteria with ranges |
| DELETE | /credit-score-card-criteria | Delete a single criterion (cascades ranges) |
| GET | /credit-score-card-grades | List grades for a score card |
| POST | /credit-score-card-grades | Save (replace all) grades |
| POST | /evaluate-credit-scorecard | Run the evaluation engine |
| GET | /credit-scoring-data-sources | List available auto-resolve data sources |
All endpoints are under the loan application setup base path.
Best Practices
- Weights should sum to 1.0 — while not strictly enforced, the weighted calculation is most meaningful when total weight equals 1.0
- Cover the full score range with grades — ensure no gaps between grade min/max boundaries
- Start with 3–5 criteria — the 5C model provides a natural grouping; avoid over-engineering with too many factors
- Use AUTO sources where possible — reduces manual data entry and ensures consistency
- Version your score cards — create new versions (v1.1, v2.0) rather than modifying active cards, so historical scores remain traceable
- Review grade thresholds periodically — calibrate against actual loan performance data
- Set Default Points conservatively — when no range matches (data unavailable), a low default prevents inflated scores
Troubleshooting
| Issue | Cause | Fix |
|---|---|---|
| Evaluate button disabled | No score card selected | Select a score card from the lookup |
| Score returns 0 | All criteria have no matching ranges | Check that ranges cover the expected value space |
| AUTO source returns NULL | Client data missing (e.g. no date_of_birth) | Ensure client profile is complete, or use MANUAL |
| Grade shows "—" | Final score falls outside all grade ranges | Ensure grades cover the full score_min to score_max |
| Weights don't sum to 1.0 | Criteria weights misconfigured | Edit criteria and adjust weights |
Related Topics
- Loan Products — product configuration
- Loan Operations — disbursement, repayment, write-off
- Loan Accounts — account lifecycle