Terminology & terms to change
How product language may evolve for facility-style framing while the system keeps stable technical names.
Why this page exists
In some markets, everyday words like interest or loan can be sensitive for customers, regulators, or internal policy, even when the product economics are standard secured-facility math. This page summarizes the recommended wording strategy so staff and product owners stay aligned.
It does not replace legal, tax, accounting, or Sharia advice. Renaming screens does not change how an arrangement is classified if it is still compensation tied to principal, time, and a rate. Use qualified local counsel (and advisors where applicable) before treating copy as compliance.
How the product behaves today
The application calculates simple, time-based charges on outstanding principal, allocates charges before principal on payments, carries shortfalls in unpaidInterestBalance, and uses fields such as annualRate, interestAccrualStartDate, and interestApplied in the database and APIs. That behaviour is documented in the Software Requirement Specification and in the repository guide TERMS_TO_CHANGE.md (project root).
Two layers (keep both)
- Stable technical names — Database columns, JSON keys, enums, and integration contracts (e.g.
annualRate,interestApplied,unpaidInterestBalance) stay as-is until a planned, versioned migration. Changing them breaks BI, tests, and partners. - Display and customer copy — UI labels, receipts, report headers, notifications, and training materials are where facility, advance, service charge, and settlement language should appear when policy and counsel agree.
Finance may still use statutory or GL labels (e.g. interest income) that differ from customer-facing words; that alignment is for accountants and lawyers, not only engineering.
Glossary — common display replacements
These are suggested customer- or staff-facing terms. Numbers and logic stay the same; only labels and narrative change.
| You may see in the app today (concept) | Preferred customer-facing wording (examples) |
|---|---|
| Interest rate | Annual facility charge rate; annual service charge rate (%) |
| Accrued interest | Accrued service charges; facility charges accrued to date |
| Loan / gold loan | Gold-backed facility; pledged gold advance; facility |
| Loan amount | Advance amount; disbursed amount; facility amount |
| Repayment | Settlement; payment toward account |
| Principal (customer-facing) | Outstanding advance; principal advance outstanding (finance may still say principal) |
| Top-up loan | Facility increase; additional advance; restructure with top-up |
| Foreclosure / auction disposition | Match legal reality: enforcement, realization, auction disposition (status enums may stay AUCTION) |
API and report keys (show differently, do not rename casually)
| Technical key (unchanged in Phase 1) | Example display label |
|---|---|
accruedInterest | Accrued service charges |
interestApplied | Service charge portion (of payment) |
principalApplied | Advance reduction (of payment) |
unpaidInterestBalance | Outstanding accrued charges (carried) |
annualRate | Annual facility charge rate |
defaultInterestRate (branch) | Default annual charge rate |
What not to do
- Do not market as “interest-free” or “not interest” if the same principal × rate × days formula applies.
- Do not claim Sharia-compliant without a proper structure and oversight.
- Do not split one charge into fake fee buckets to disguise time-based percentage economics.
Where to go next
- Operators: follow your branch’s approved glossary once product and legal publish it; until then, use the terms your supervisor confirms for customer conversations.
- Product, legal, and engineering: use the full checklist, surfaces list, and migration notes in
TERMS_TO_CHANGE.mdat the repository root (same monorepo as this docs app).