Loan Products

Loan products are the master templates that control how lending works in PinkApple: who qualifies, how interest accrues, how schedules are built, how penalties and taxes behave, and which product-specific accounting mappings the loan domain will use at posting time.

Navigation: Administration → Products → Loan Products

What a Loan Product Controls

When a loan account is created, the account inherits its operational behavior from the selected product. In practice, a loan product controls:

• interest behavior, including flat vs declining balance, accrual mode, repricing, and day-count basis
• schedule behavior, including fixed vs dynamic schedules, due date handling, installment counts, and grace periods
• disbursement and limit rules, including amount ranges, term ranges, tranche limits, and line-of-credit requirements
• repayment behavior, including allocation order, prepayment treatment, rounding, and future-payment acceptance
• penalty and tax treatment
• eligibility rules, including support for individuals, pure groups, hybrid groups, women-only products, and required member counts
• accounting setup through chart of accounts and pricing profiles

Product Types

The product type determines which flags are available and which are required.

Product Type	Typical Use
FIXED_TERM_LOAN	Standard amortizing loans with a fixed schedule definition
DYNAMIC_TERM_LOAN	Loans where installments or schedule values may be recalculated over time
INTEREST_FREE_LOAN	Products that avoid contractual interest but may still use fees and repayment controls
TRANCHED_LOAN	Loans disbursed in multiple tranches
REVOLVING_CREDIT	Reusable credit facilities and line-based lending

Flag-Driven Configuration

Loan product behavior is driven by the loan flag catalog. Each product type exposes a curated set of flags, with:

• a catalog default
• a type-level allowed/required rule
• an optional product-level override

The form shows the flag name plus a short description so users can understand the purpose of each setting before changing it.

Main Flag Groups

Group	What It Covers
INTEREST	Calculation method, interest type, compounding, repricing, accrual, balance base
SCHEDULE	Schedule method, due dates, business day convention, installment defaults
LIMITS	Amount ranges, installment ranges, tranche cap, line-of-credit requirement
GRACE_PERIOD	Grace treatment and allowed grace-period range
FIRST_REPAYMENT	Offset from disbursement to first installment
PENALTY	Penalty method, penalty rates, grace period, capping
PREPAYMENT	Whether early repayment is allowed and how recalculation works
TAX	Inclusive vs exclusive tax and tax enablement by charge type
REPAYMENT	Allocation order, payment method, settlement and future-payment handling
ROUNDING	Rounding rules for schedule totals and repayment elements
ACCOUNT	Initial state, ID generation, arbitrary fees, offset percentage
ELIGIBILITY	Borrower/group targeting and special eligibility restrictions
LINKING	Linked-account repayment and automatic linking behavior

Creating or Editing a Loan Product

1. Open Loan Products
2. Click Create Loan Product or Edit
3. Select the loan product type
4. Complete the product header fields and required accounting links
5. Review the generated flag set and override only the flags that differ from the type defaults
6. Map the required product accounting accounts
7. Save and complete any approval workflow if enabled

Key Configuration Areas

1. Core Product Setup

Field	Purpose
Product Name	Business-facing product name
Description	Operational purpose and internal notes
Currency	Booking currency for loan accounts
Category	Portfolio classification such as personal, SME, or mortgages
Loan Product Type	Determines the flag set and schedule model
Package / Settings	Shared settings for redraw, arrears, principal-payment, and security behavior

2. Interest and Schedule

Important flags in this area include:

• Interest Calculation Method: selects flat, reducing-balance, or fixed-installment reducing-balance logic
• Interest Balance Calc Method: selects the balance base used for interest computation
• Day Count Convention: defines how annual rates are converted into daily or periodic charges
• Amortization Method:
  • STANDARD_PAYMENTS and EQUAL_INSTALLMENTS use the equal-installment path
  • BALLOON_PAYMENTS and EQUAL_PRINCIPAL currently use the non-standard/equal-principal path
• Schedule Method: fixed or dynamic schedule generation
• Due Dates Method: interval-based dates or fixed days of month
• Elements Recalculation Method:
  • Keep Principal Fixed recalculates interest while preserving principal expectations
  • Keep Total Installment Fixed rebalances principal and interest while keeping the installment total steady
• Grace Period Type: no grace, interest-only, interest forgiveness, or other supported policies

3. Limits and Eligibility

This area controls both commercial limits and borrower targeting:

• minimum, maximum, and default loan amount
• minimum, maximum, and default installment count
• line-of-credit requirement
• support for individuals, pure groups, and hybrid groups
• Women Only Eligibility
• Required Group Member Count

4. Repayment, Penalty, and Tax Behavior

These flags affect servicing after disbursement:

• repayment allocation order
• payment method and settlement options
• prepayment acceptance and recalculation
• penalty method, penalty rate bounds, and capping
• taxes on interest, fees, and penalties

Product Accounting Mappings

Loan products now contribute accounts first, not a large list of rule bindings. The loan domain reads the mapped product accounts at posting time, while only the small remaining product-bound rule surface is configured separately.

Required Core Mappings

Field	Purpose
COA (coa_id)	Loan principal/control account
Interest Receivable Account	Accrued and billed interest control
Interest Income Account	Interest income recognition
Pricing Profile	Pricing-driven fees, penalties, and scheduled interest

Operational / Lifecycle Mappings

Field	Purpose
Write-off Debit Account	Optional fallback debit when write-off should not consume product provision liability
Provision Expense Account	Product-specific provisioning expense
Provision Liability Account	Product-specific provisioning liability and preferred write-off debit
Recovery Income Account	Income recognition for recovered written-off balances

What Still Uses Rules

Loan products should no longer be treated as needing only a disbursement binding.

Minimum binding set for an active product:

• DISBURSE
• REPAYMENT
• repayment reversal coverage through the *_REV loan tags

Additional bindings depend on behavior:

• INT_ACCRUE for accrual products
• INT_SUSPEND and INT_SUSPEND_RELEASE for interest-bearing products that can move into suspense/NPL handling
• INT_CAPITALIZE for capitalized or compound-interest products
• PROVISION, WRITEOFF, RECOVERY, LOAN_WAIVER, RESTRUCTURE, and their reversals when those lifecycle operations are enabled in the tenant

That means:

• the product must have the required COA mappings
• the product should be checked for the bindings required by its runtime behavior, not only for Loan Disbursement
• repayment settlement is still driven by the repayment channel handler, not by separate per-product cash/bank manual rule variants
• waiver uses the LOAN_WAIVER tag alias because WAIVER is reserved elsewhere in the platform
• restructure currently has a forward GL rule only; there is no separate RESTRUCTURE_REV operation in source today

See GL Posting Rules and Loan GL Setup.

Pricing Profile

Attach a pricing profile when the product uses configurable fees or pricing items. Typical items include:

• origination or processing fees
• insurance premiums
• recurring service charges
• early-settlement fees
• penalty-related pricing triggers

Minimum Valid Loan Pricing Profile

For a pricing profile to work safely on a loan product, the engine expects at least one active scheduled interest-style pricing item.

This is not optional when the account relies on pricing-driven interest resolution. During loan-account creation, the backend stops schedule generation if the resolved pricing profile has no active SCHEDULED items and no manual custom_interest_rate override was supplied.

The exact backend failure is:

No active SCHEDULED pricing items found for pricing_profile_id <id>. Either configure pricing items or provide custom_interest_rate parameter.

Practical rule:

• if the product should use pricing-driven loan interest, attach a pricing profile with at least one active SCHEDULED loan-interest item
• if the business wants to bypass pricing for one account, pass a custom_interest_rate during account creation instead

Required vs Optional Loan Pricing Items

Pricing Item Purpose	Required?	Application Mode	Trigger Event	Preferred Handler Codes	Typical Line Codes	Notes
Scheduled loan interest	Required for pricing-driven loan products	SCHEDULED	Not tied to a transaction trigger	LOAN_DAILY_INTEREST_AMOUNT, DAILY_INTEREST_AMOUNT	INTEREST_LOAN_BASE, INTEREST_LOAN_VARIABLE, INTEREST_LOAN_FIXED	This is the item family the loan engine needs to resolve interest and generate schedules.
Disbursement fee / origination fee	Optional	Usually MANUAL or ARBITRARY	LOAN_DISBURSEMENT	LOAN_FEE_AMOUNT, DISBURSEMENT_FEE, PROCESSING_FEE, INSURANCE_FEE	FEE_LOAN_ORIGINATION, FEE_LOAN_PROCESSING, loan insurance lines	Use when the product charges up-front fees at disbursement.
Prepayment interest / settlement charge	Optional	Usually MANUAL or ARBITRARY	LOAN_PREPAYMENT_INTEREST	LOAN_PREPAYMENT_INTEREST	FEE_LOAN_PREPAYMENT, settlement-related fee lines	Use only if the product charges early-payment or early-settlement interest.
Overdue penalty	Optional	Usually MANUAL or ARBITRARY	LOAN_PENALTY	LOAN_PENALTY_AMOUNT	PENALTY_LATE_PAYMENT	Needed only when penalty charging is enabled on the product.
Tax on fee / interest / penalty	Optional dependent item	Usually follows the parent item timing	Same as parent item event	TAX_AMOUNT	Tax-oriented dependent lines	Use as a dependent item when the product enables taxes on fees, interest, or penalties.
Parent-based surcharge / discount / percentage item	Optional dependent item	Follows the parent item timing	Same as parent item event	PARENT_DEPENDENT_AMOUNT	Discount, surcharge, or dependent line codes	Use when a child item should be calculated from another pricing item instead of directly from the loan account.

Preferred Handlers for New Loan Pricing Setup

Some older loan procedures still recognize compatibility aliases such as CALC_FEE_AMOUNT, CALC_PENALTY_AMOUNT, and CALC_TAX_AMOUNT.

For new pricing item setup, prefer these handler codes:

• LOAN_DAILY_INTEREST_AMOUNT or DAILY_INTEREST_AMOUNT for scheduled loan interest
• LOAN_FEE_AMOUNT, DISBURSEMENT_FEE, PROCESSING_FEE, or INSURANCE_FEE for fees
• LOAN_PENALTY_AMOUNT for overdue penalties
• LOAN_PREPAYMENT_INTEREST for early-payment interest
• TAX_AMOUNT for tax child items
• PARENT_DEPENDENT_AMOUNT for parent/child dependent pricing math

Loan Pricing Trigger Coverage

The loan pricing runtime currently uses these trigger events in active loan flows:

Trigger Event	Typical Use
LOAN_DISBURSEMENT	Disbursement-time fees and charges
LOAN_INT_ACCRUE	Daily or periodic interest accrual
LOAN_LATE_INTEREST	Late-interest charging
LOAN_PREPAYMENT_INTEREST	Early-payment interest charging
LOAN_PENALTY	Overdue penalty charging
LOAN_WAIVER	Waiver runtime effects
LOAN_INT_APPLY	Interest application and reversals
LOAN_WRITE_OFF	Write-off pricing transactions and reversals
LOAN_RECOVERY	Recovery pricing transactions and reversals

The trigger seed catalog also contains LOAN_REPAYMENT, LOAN_FEE_DEDUCTION, and LOAN_AUTO_COLLECT, but those are not the primary “must have” pricing-item triggers for attaching a pricing profile to a standard loan product.

Operational Notes

• Product-level flag overrides are persisted separately from the core loan product record.
• If a product is edited, the detail payload should include both the standard fields and the product_flag_configs overrides.
• Type defaults are starting points, not mandatory final values, unless the flag is marked required and non-editable for that type.

Related Guides

• Loan Accounts
• Variable Rate Repricing
• Interest in Suspense
• Loan Collections