Loan GL Setup

Guide to the actual loan GL rule model used by the current loan runtime.

Navigation: Administration → Accounting → GL Posting Rules

Overview

Loan accounting now depends on three layers working together:

1. loan-product account mappings
2. loan-product GL rule bindings
3. global LOAN_GL_RULE system-tag bindings

The runtime resolves a loan posting operation by tag key first, then prefers a matching product-bound rule header, then executes the detail handlers.

Required LOAN_GL_RULE Operations

Operation	Tag Key	Product Bind?	Notes
Disbursement	DISBURSE	Yes	Always
Disbursement reversal	DISBURSE_REV	Yes	If disbursement reversal is allowed
Repayment	REPAYMENT	Yes	Always
Repayment reversal family	REPAY_CASH_REV, REPAY_CASH_EXCESS_REV, REPAY_DEPOSIT_ACCOUNT_REV, REPAY_DEPOSIT_ACCOUNT_EXCESS_REV, REPAY_BANK_REV, REPAY_BANK_EXCESS_REV, REPAY_SPLIT_REV	Yes	All point to one repayment-reversal header
Interest accrual	INT_ACCRUE	Yes	Accrual products only
Interest accrual reversal	INT_ACCRUE_REV	Yes	Accrual products only
Interest capitalization	INT_CAPITALIZE	Yes	Capitalized / compound products only
Interest capitalization reversal	INT_CAPITALIZE_REV	Yes	Capitalized / compound products only
Interest suspense	INT_SUSPEND	Yes	Interest-bearing products with suspense handling
Interest suspense release	INT_SUSPEND_RELEASE	Yes	Interest-bearing products with suspense handling
Provision	PROVISION	Yes	If provisioning is enabled
Provision reversal	PROVISION_REV	Yes	If provision reversal is supported
Write-off	WRITEOFF	Yes	If write-off is allowed
Write-off reversal	WRITEOFF_REV	Yes	If write-off reversal is supported
Recovery	RECOVERY	Yes	If written-off recovery is allowed
Recovery reversal	RECOVERY_REV	Yes	If recovery reversal is supported
Waiver	LOAN_WAIVER	Yes	WAIVER is aliased to LOAN_WAIVER in tags
Waiver reversal	WAIVER_REV	Yes	If waiver reversal is supported
Restructure	RESTRUCTURE	Yes	If restructure has GL impact
Collateral-funded repayment	REPAY_COLLATERAL	Only if used	Special collateral-disposal flow, not standard repayment

Product Account Mappings

These product mappings are the primary source of truth for core loan accounts:

• coa_id
• interest_receivable_coa_id
• interest_income_coa_id
• provision_expense_coa_id
• provision_liability_coa_id
• recovery_income_coa_id
• writeoff_expense_coa_id

For fee and penalty income, runtime currently falls back to pricing-item account resolution because there are no dedicated product-level fee/penalty mappings yet.

Rule Headers, Detail Lines, and Handlers

All headers below should be posting_mode = SYSTEM.

1. LOAN.DISBURSE.SYSTEM via DISBURSE

Detail Name	Line Type	Nature	Handler / Source	Amount
DISBURSE DR	DEBIT	DOMAIN_RESOLVED	LOAN_RECEIVABLE_RESOLVE	SYSTEM
DISBURSE CR	CREDIT	DOMAIN_RESOLVED	CASH_BANK_RESOLVE	SYSTEM

2. LOAN.DISBURSE.REVERSAL.SYSTEM via DISBURSE_REV

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.DISBURSE.REV.DR.FUND	DEBIT	DOMAIN_RESOLVED	CASH_BANK_RESOLVE	SYSTEM
LOAN.DISBURSE.REV.CR.RECV	CREDIT	DOMAIN_RESOLVED	LOAN_RECEIVABLE_RESOLVE	SYSTEM

3. LOAN.REPAYMENT.SYSTEM via REPAYMENT

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN_REPAYMENT_SOURCE_DEBIT	DEBIT	DOMAIN_RESOLVED	LOAN_REPAYMENT_SOURCE_RESOLVE	SYSTEM
LOAN_REPAYMENT_SPLIT_CREDIT	CREDIT	DOMAIN_RESOLVED	LOAN_REPAYMENT_SPLIT	SYSTEM

4. LOAN.REPAYMENT.REVERSAL.SYSTEM via repayment-reversal tags

Bound to:

• REPAY_CASH_REV
• REPAY_CASH_EXCESS_REV
• REPAY_DEPOSIT_ACCOUNT_REV
• REPAY_DEPOSIT_ACCOUNT_EXCESS_REV
• REPAY_BANK_REV
• REPAY_BANK_EXCESS_REV
• REPAY_SPLIT_REV

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN_REPAYMENT_REVERSAL_SPLIT_DEBIT	DEBIT	DOMAIN_RESOLVED	LOAN_REPAYMENT_SPLIT	SYSTEM
LOAN_REPAYMENT_REVERSAL_SOURCE_CREDIT	CREDIT	DOMAIN_RESOLVED	LOAN_REPAYMENT_SOURCE_RESOLVE	SYSTEM

5. LOAN.INT.ACCRUAL.SYSTEM via INT_ACCRUE

Detail Name	Line Type	Nature	Handler / Source	Amount
Interest Accrual Dr	DEBIT	DOMAIN_RESOLVED	INTEREST_RECEIVABLE_RESOLVE	SYSTEM
Interest accrual cr	CREDIT	DOMAIN_RESOLVED	INTEREST_INCOME_RESOLVE	SYSTEM

6. LOAN.INT.ACCRUE.REVERSAL.SYSTEM via INT_ACCRUE_REV

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.INT.ACCRUE.REV.DR.INC	DEBIT	DOMAIN_RESOLVED	INTEREST_INCOME_RESOLVE	SYSTEM
LOAN.INT.ACCRUE.REV.CR.RECV	CREDIT	DOMAIN_RESOLVED	INTEREST_RECEIVABLE_RESOLVE	SYSTEM

7. LOAN.INT.CAPITALIZE.SYSTEM via INT_CAPITALIZE

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.INT.CAP.DR.PRINCIPAL	DEBIT	DOMAIN_RESOLVED	INTEREST_CAPITALIZATION_RESOLVE	SYSTEM
LOAN.INT.CAP.CR.RECV	CREDIT	DOMAIN_RESOLVED	INTEREST_CAPITALIZATION_RESOLVE	SYSTEM

8. LOAN.INT.CAPITALIZE.REVERSAL.SYSTEM via INT_CAPITALIZE_REV

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.INT.CAP.REV.DR.RECV	DEBIT	DOMAIN_RESOLVED	INTEREST_CAPITALIZATION_RESOLVE	SYSTEM
LOAN.INT.CAP.REV.CR.PRINCIPAL	CREDIT	DOMAIN_RESOLVED	INTEREST_CAPITALIZATION_RESOLVE	SYSTEM

9. LOAN.INT.SUSPEND via INT_SUSPEND

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.INT.SUSP.DR.INC	DEBIT	DOMAIN_RESOLVED	INTEREST_INCOME_RESOLVE	SYSTEM
LOAN.INT.SUSP.CR.RECV	CREDIT	TAG_RESOLVED	Suspense receivable target configured on the rule/tag side	SYSTEM

10. LOAN.INT.SUSPEND.RELEASE via INT_SUSPEND_RELEASE

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.INT.SUSP.REL.DR.SUSP	DEBIT	TAG_RESOLVED	Suspense receivable target configured on the rule/tag side	SYSTEM
LOAN.INT.SUSP.REL.CR.INC	CREDIT	DOMAIN_RESOLVED	INTEREST_INCOME_RESOLVE	SYSTEM

11. LOAN.PROVISION.SYSTEM via PROVISION

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.PROVISION.DR.EXP	DEBIT	DOMAIN_RESOLVED	LOAN_PROVISION_RESOLVE	SYSTEM
LOAN.PROVISION.CR.LIAB	CREDIT	DOMAIN_RESOLVED	LOAN_PROVISION_RESOLVE	SYSTEM

12. LOAN.PROVISION.REVERSAL.SYSTEM via PROVISION_REV

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.PROVISION.REV.DR.LIAB	DEBIT	DOMAIN_RESOLVED	LOAN_PROVISION_RESOLVE	SYSTEM
LOAN.PROVISION.REV.CR.EXP	CREDIT	DOMAIN_RESOLVED	LOAN_PROVISION_RESOLVE	SYSTEM

13. LOAN.WRITEOFF.SYSTEM via WRITEOFF

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.WRITEOFF.DR.EXP	DEBIT	DOMAIN_RESOLVED	LOAN_WRITEOFF_RESOLVE	SYSTEM
LOAN.WRITEOFF.CR.RECV	CREDIT	DOMAIN_RESOLVED	LOAN_WRITEOFF_RESOLVE	SYSTEM

14. LOAN.WRITEOFF.REVERSAL.SYSTEM via WRITEOFF_REV

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.WRITEOFF.REV.DR.RECV	DEBIT	DOMAIN_RESOLVED	LOAN_WRITEOFF_RESOLVE	SYSTEM
LOAN.WRITEOFF.REV.CR.EXP	CREDIT	DOMAIN_RESOLVED	LOAN_WRITEOFF_RESOLVE	SYSTEM

15. LOAN.RECOVERY.SYSTEM via RECOVERY

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.RECOVERY.DR.SETTLEMENT	DEBIT	DOMAIN_RESOLVED	LOAN_RECOVERY_RESOLVE	SYSTEM
LOAN.RECOVERY.CR.INCOME	CREDIT	DOMAIN_RESOLVED	LOAN_RECOVERY_RESOLVE	SYSTEM

16. LOAN.RECOVERY.REVERSAL.SYSTEM via RECOVERY_REV

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.RECOVERY.REV.DR.INCOME	DEBIT	DOMAIN_RESOLVED	LOAN_RECOVERY_RESOLVE	SYSTEM
LOAN.RECOVERY.REV.CR.SETTLEMENT	CREDIT	DOMAIN_RESOLVED	LOAN_RECOVERY_RESOLVE	SYSTEM

17. LOAN.WAIVER.SYSTEM via LOAN_WAIVER

LOAN_WAIVER_RESOLVE is detail-name-sensitive. Use these names exactly.

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.WAIVER.DR.IMPACT	DEBIT	DOMAIN_RESOLVED	LOAN_WAIVER_RESOLVE	SYSTEM
LOAN.WAIVER.CR.CONTROL	CREDIT	DOMAIN_RESOLVED	LOAN_WAIVER_RESOLVE	SYSTEM

18. LOAN.WAIVER.REVERSAL.SYSTEM via WAIVER_REV

Use these names exactly.

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.WAIVER.REV.DR.CONTROL	DEBIT	DOMAIN_RESOLVED	LOAN_WAIVER_RESOLVE	SYSTEM
LOAN.WAIVER.REV.CR.IMPACT	CREDIT	DOMAIN_RESOLVED	LOAN_WAIVER_RESOLVE	SYSTEM

19. LOAN.RESTRUCTURE.SYSTEM via RESTRUCTURE

Detail Name	Line Type	Nature	Handler / Source	Amount
LOAN.RESTRUCTURE.DR.PRINCIPAL	DEBIT	DOMAIN_RESOLVED	INTEREST_CAPITALIZATION_RESOLVE	SYSTEM
LOAN.RESTRUCTURE.CR.INTEREST	CREDIT	DOMAIN_RESOLVED	INTEREST_CAPITALIZATION_RESOLVE	SYSTEM

Note: current source does not have a separate RESTRUCTURE_REV tag/op. Restructure reversal is not a first-class GL operation today the way repayment, write-off, recovery, waiver, accrual, and capitalization reversals are.

Dynamic Handlers

Handler Code	What it resolves	Primary source
LOAN_RECEIVABLE_RESOLVE	Principal receivable/control side	loan_product.coa_id plus borrower sub-ledger context
CASH_BANK_RESOLVE	Disbursement settlement side	cash/bank/deposit/teller/wallet context
LOAN_REPAYMENT_SOURCE_RESOLVE	Repayment debit/source side	repayment channel context
LOAN_REPAYMENT_SPLIT	Repayment credit split across principal/interest/fees/penalty/tax/excess	loan transaction/component context
INTEREST_RECEIVABLE_RESOLVE	Interest receivable	product interest_receivable_coa_id, then pricing-item fallback
INTEREST_INCOME_RESOLVE	Interest income	product interest_income_coa_id, then pricing-item fallback
INTEREST_CAPITALIZATION_RESOLVE	Principal-vs-interest side for capitalization/restructure	product principal and interest-receivable accounts
LOAN_PROVISION_RESOLVE	Provision expense/liability	product provision mappings
LOAN_WRITEOFF_RESOLVE	Write-off expense/receivable	product write-off and control mappings
LOAN_RECOVERY_RESOLVE	Recovery settlement/income	settlement channel plus product recovery-income mapping
LOAN_WAIVER_RESOLVE	Waiver impact/control lines	product mappings plus pricing-item fee/penalty accounts

System Tag Guidance

• Keep only one active valid header binding per tag key for the global standard flow.
• If a tag still points at a deleted header id, deactivate that binding.
• Keep LOAN_WAIVER as the waiver tag key. Do not rename it to WAIVER.
• Keep REPAY_COLLATERAL only for collateral-disposal repayment flows.
• Do not create fake reversal tags for operations that source code does not resolve.

Validation Checklist

• [ ] Product account mappings exist for principal, interest, provision, recovery, and write-off where required
• [ ] Every enabled lifecycle operation has both a product binding and a LOAN_GL_RULE tag binding
• [ ] All DOMAIN_RESOLVED lines have the correct handler attached
• [ ] Waiver headers use the exact impact/control detail names above
• [ ] Reversal tags point at dedicated reversal headers, not the forward header
• [ ] No active LOAN_GL_RULE tag binding points at a deleted or rejected rule header
• [ ] Accrual products have both INT_ACCRUE and INT_ACCRUE_REV
• [ ] Capitalized/compound products have both INT_CAPITALIZE and INT_CAPITALIZE_REV

Runtime Resolution Flow

Loan operation
  -> resolve LOAN_GL_RULE tag key
  -> resolve approved header
  -> prefer matching product-bound header
  -> execute detail handlers
  -> each handler resolves the actual COA/sub-ledger

If the tag, header, product binding, detail binding, or required mapped account is missing, the runtime should fail clearly instead of falling back silently.