Personal Loan - V2 Configuration

Product Type: Unsecured Personal Lending
Use Case: General purpose loans for individuals
Typical Amount: â‚¦50,000 - â‚¦5,000,000
Typical Tenor: 6-60 months
Interest Rate: 15.5% - 35% per annum

Overview

Personal loans are unsecured general-purpose loans designed for individual customers. They offer flexible terms for various personal needs including education, home improvements, medical expenses, and debt consolidation.

Key Features

No collateral required
Fixed monthly repayments
Flexible loan amounts and tenors
Income verification required
Optional guarantor
Early repayment allowed

YAML Field Reference

Basic Information Section

Field Name	Data Type	Required	Description	Example
`productCode`	String	âœ… Yes	Unique code identifying the loan product	`"PL-001"`
`productName`	String	âœ… Yes	Display name of the product	`"Personal Loan"`
`description`	String	No	Detailed product description	`"Unsecured personal loan for individuals"`
`isActive`	Boolean	No	Whether product is currently active	`true`
`loanProductType`	String	No	Type of loan product (V1 compatibility)	`"FixedTermLoan"`
`repaymentAllocationOrder`	String	No	Order of payment allocation	`"FEES_PENALTY_INTEREST_PRINCIPAL"`
`lineOfBusiness`	Enum	No	Business line classification	`"Retail"`
`currencyCode`	String	No	Currency code (e.g., NGN, USD)	`"NGN"`

Loan Tenure Section

Field Name	Data Type	Required	Description	Example
`minimumMonths`	Integer	âœ… Yes	Minimum loan duration in months	`6`
`maximumMonths`	Integer	âœ… Yes	Maximum loan duration in months	`60`
`defaultMonths`	Integer	No	Default tenure offered	`12`

Principal Range Section

Field Name	Data Type	Required	Description	Example
`minimumAmount`	Decimal	No	Minimum loan amount	`50000`
`maximumAmount`	Decimal	No	Maximum loan amount	`5000000`
`defaultAmount`	Decimal	No	Default loan amount suggested	`500000`

Interest Configuration Section

Field Name	Data Type	Required	Description	Example
`isEnabled`	Boolean	âœ… Yes	Whether interest is charged	`true`
`rate.default`	Decimal	âœ… Yes	Default interest rate (%)	`15.5`
`rate.minimum`	Decimal	No	Minimum interest rate (%)	`12.0`
`rate.maximum`	Decimal	No	Maximum interest rate (%)	`35.0`
`calculationMethod`	Enum	âœ… Yes	Interest calculation method	`"DecliningBalance"`
`deductionMethod`	Enum	No	How interest is collected	`"PaymentDueDate"`
`rateTerms`	Enum	No	Rate expression (per year/month)	`"PerYear"`

Interest Calculation Methods:

DecliningBalance - Interest calculated on reducing balance (most common)
Flat - Interest calculated on original principal amount
DecliningBalanceEqualInstallments - Equal monthly payments with declining interest

Repayment Configuration Section

Field Name	Data Type	Required	Description	Example
`frequency`	Enum	âœ… Yes	Repayment frequency	`"Monthly"`
`allocationOrder`	String	No	Payment allocation priority	`"FEES_PENALTY_INTEREST_PRINCIPAL"`
`principalCollectionInterval`	Integer	No	Collect principal every X repayments	`1`
`firstDueDateOffset`	Integer	No	Days until first repayment	`30`

Repayment Frequencies: Daily, Weekly, Biweekly, Monthly, Quarterly, Annually

Fees Section

Field Name	Data Type	Required	Description	Example
`fees[].code`	String	âœ… Yes	Unique fee code	`"PROC_FEE"`
`fees[].name`	String	âœ… Yes	Fee display name	`"Processing Fee"`
`fees[].feeType`	Enum	âœ… Yes	When fee is applied	`"DeductedDisbursement"`
`fees[].calculationType`	Enum	âœ… Yes	How fee is calculated	`"PercentOfPrincipal"`
`fees[].value`	Decimal	âœ… Yes	Fee amount or percentage	`2.5`
`fees[].minimum`	Decimal	No	Minimum fee amount	`5000`
`fees[].maximum`	Decimal	No	Maximum fee amount	`50000`
`fees[].glAccountId`	Integer	No	GL account for fee income	`40001`

Fee Types:

Manual - Applied manually
DeductedDisbursement - Deducted from loan amount
CapitalizedDisbursement - Added to principal
UpfrontDisbursement - Paid before disbursement
LateRepayment - Charged on late payments

Penalty Configuration Section

Field Name	Data Type	Required	Description	Example
`isEnabled`	Boolean	No	Whether penalties are charged	`true`
`tolerancePeriod`	Integer	No	Grace period in days before penalty	`3`
`calculationMethod`	Enum	No	Penalty calculation basis	`"OverduePrincipal_DaysLate_Rate"`
`rate.default`	Decimal	No	Default penalty rate (%)	`2.0`
`rate.minimum`	Decimal	No	Minimum penalty rate (%)	`1.0`
`rate.maximum`	Decimal	No	Maximum penalty rate (%)	`5.0`

Collateral Configuration Section

Field Name	Data Type	Required	Description	Example
`isRequired`	Boolean	No	Whether collateral is mandatory	`false`
`types[]`	Array	No	Accepted collateral types	`["Property", "Vehicle"]`
`coverageRatio`	Decimal	No	Required collateral value ratio (%)	`120`

Eligibility Configuration Section

Field Name	Data Type	Required	Description	Example
`minimumAge`	Integer	No	Minimum customer age	`21`
`maximumAge`	Integer	No	Maximum customer age	`60`
`minimumIncome`	Decimal	No	Minimum monthly income required	`50000`
`employmentStatus[]`	Array	No	Accepted employment types	`["Employed", "SelfEmployed"]`
`requiredDocuments[]`	Array	No	Required documentation	`["NationalID", "ProofOfIncome"]`
`kycLevel`	Enum	No	Required KYC level	`"Tier2"`

Notifications Configuration Section

Field Name	Data Type	Required	Description	Example
`sendApplicationConfirmation`	Boolean	No	Notify on application submission	`true`
`sendApprovalNotification`	Boolean	No	Notify on approval	`true`
`sendDisbursementNotification`	Boolean	No	Notify on disbursement	`true`
`sendRepaymentReminders`	Boolean	No	Send repayment reminders	`true`
`reminderDaysBefore`	Integer	No	Days before due date to remind	`3`
`channels.sms`	Boolean	No	Enable SMS notifications	`true`
`channels.email`	Boolean	No	Enable email notifications	`true`
`channels.push`	Boolean	No	Enable push notifications	`false`

Complete Sample YAML Configuration

basicInfo:
  productCode: "PL-STANDARD-001"
  productName: "Standard Personal Loan"
  description: "Unsecured personal loan for general purposes"
  isActive: true
  loanProductType: "FixedTermLoan"
  repaymentAllocationOrder: "FEES_PENALTY_INTEREST_PRINCIPAL"
  lineOfBusiness: "Retail"
  currencyCode: "NGN"

loanTenure:
  minimumMonths: 6
  maximumMonths: 60
  defaultMonths: 12

principalRange:
  minimumAmount: 50000
  maximumAmount: 5000000
  defaultAmount: 500000

interestConfig:
  isEnabled: true
  rate:
    default: 15.5
    minimum: 12.0
    maximum: 35.0
  calculationMethod: "DecliningBalance"
  deductionMethod: "PaymentDueDate"
  rateTerms: "PerYear"

repaymentConfig:
  frequency: "Monthly"
  allocationOrder: "FEES_PENALTY_INTEREST_PRINCIPAL"
  principalCollectionInterval: 1
  firstDueDateOffset: 30

fees:
  - code: "PROC_FEE"
    name: "Processing Fee"
    feeType: "DeductedDisbursement"
    calculationType: "PercentOfPrincipal"
    value: 2.5
    minimum: 5000
    maximum: 50000
    glAccountId: 40001
  
  - code: "MGMT_FEE"
    name: "Management Fee"
    feeType: "CapitalizedDisbursement"
    calculationType: "Flat"
    value: 10000
    glAccountId: 40002

penaltyConfig:
  isEnabled: true
  tolerancePeriod: 3
  calculationMethod: "OverduePrincipal_DaysLate_Rate"
  rate:
    default: 2.0
    minimum: 1.0
    maximum: 5.0

collateralConfig:
  isRequired: false
  types:
    - "Property"
    - "Vehicle"
    - "Guarantor"
  coverageRatio: 0  # Not required for personal loans

eligibilityConfig:
  minimumAge: 21
  maximumAge: 60
  minimumIncome: 50000
  employmentStatus:
    - "Employed"
    - "SelfEmployed"
  requiredDocuments:
    - "NationalID"
    - "ProofOfIncome"
    - "UtilityBill"
  kycLevel: "Tier2"

notificationsConfig:
  sendApplicationConfirmation: true
  sendApprovalNotification: true
  sendDisbursementNotification: true
  sendRepaymentReminders: true
  reminderDaysBefore: 3
  channels:
    sms: true
    email: true
    push: false

accountingConfig:
  methodology: "Accrual"
  glAccounts:
    portfolioControlAccount: 10501
    interestReceivableAccount: 10502
    feeReceivableAccount: 10503
    penaltyReceivableAccount: 10504
    interestIncomeAccount: 40101
    feeIncomeAccount: 40102
    penaltyIncomeAccount: 40103

Use Cases & Examples

Example 1: Standard Personal Loan

Scenario: Customer needs â‚¦500,000 for home renovation over 12 months.

Configuration:

Principal: â‚¦500,000
Tenor: 12 months
Interest: 15.5% per annum (Declining Balance)
Processing Fee: 2.5% (â‚¦12,500)

Monthly Repayment Calculation:

Using Declining Balance:
Monthly Interest Rate = 15.5% / 12 = 1.292%
Monthly Payment = â‚¦500,000 Ã— [0.01292 Ã— (1 + 0.01292)^12] / [(1 + 0.01292)^12 - 1]
Monthly Payment â‰ˆ â‚¦44,859

Total Repayment: â‚¦538,308
Total Interest: â‚¦38,308

Example 2: Low-Income Personal Loan

principalRange:
  minimumAmount: 50000
  maximumAmount: 500000  # Lower max
  defaultAmount: 200000

interestConfig:
  rate:
    default: 18.0  # Slightly higher risk
    minimum: 15.0
    maximum: 25.0

eligibilityConfig:
  minimumIncome: 30000  # Lower income threshold
  maximumAge: 55  # Lower age limit

Example 3: High-Value Personal Loan

principalRange:
  minimumAmount: 1000000
  maximumAmount: 10000000  # Higher max
  
interestConfig:
  rate:
    default: 12.5  # Better rate for higher amounts
    minimum: 10.0
    maximum: 18.0

eligibilityConfig:
  minimumIncome: 300000  # Higher income requirement
  requiredDocuments:
    - "NationalID"
    - "ProofOfIncome"
    - "BankStatements6Months"
    - "TaxClearance"

Common Configurations

Quick Approval Personal Loan

eligibilityConfig:
  minimumAge: 25
  minimumIncome: 100000
  requiredDocuments:
    - "NationalID"
    - "BankStatement3Months"
  
collateralConfig:
  isRequired: false
  
notificationsConfig:
  sendApplicationConfirmation: true
  channels:
    sms: true
    email: true

Secured Personal Loan (Lower Rate)

interestConfig:
  rate:
    default: 12.0  # Lower due to collateral
    minimum: 10.0
    maximum: 18.0

collateralConfig:
  isRequired: true
  types:
    - "Property"
    - "Vehicle"
  coverageRatio: 120

Interest Calculation Examples

Declining Balance (Reducing Balance)

Most Common Method - Interest calculated on remaining principal.

Loan Amount: â‚¦500,000
Interest Rate: 15.5% p.a. (1.292% monthly)
Tenor: 12 months

Month 1:
  Opening Balance: â‚¦500,000
  Interest: â‚¦500,000 Ã— 1.292% = â‚¦6,458
  Principal: â‚¦44,859 - â‚¦6,458 = â‚¦38,401
  Closing Balance: â‚¦461,599

Month 2:
  Opening Balance: â‚¦461,599
  Interest: â‚¦461,599 Ã— 1.292% = â‚¦5,963
  Principal: â‚¦44,859 - â‚¦5,963 = â‚¦38,896
  Closing Balance: â‚¦422,703

...continues until paid off

Flat Rate (Less Common)

Interest calculated on original principal throughout.

Loan Amount: â‚¦500,000
Interest Rate: 15.5% p.a. flat
Tenor: 12 months

Total Interest: â‚¦500,000 Ã— 15.5% = â‚¦77,500
Total Repayment: â‚¦577,500
Monthly Payment: â‚¦577,500 / 12 = â‚¦48,125 (fixed)

Validation Rules

Built-in Validations

Tenure Validation:
- minimumMonths must be > 0
- maximumMonths must be >= minimumMonths
Principal Validation:
- minimumAmount must be > 0
- maximumAmount must be >= minimumAmount
Interest Rate Validation:
- default must be between minimum and maximum
- All rates must be > 0
Fee Validation:
- Each fee must have unique code
- value must be > 0
- If minimum/maximum specified, value must be within range

Business Rule Validations

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Troubleshooting

Issue: "Interest rate out of range"

Cause: Requested rate not within configured min/max.

Solution: Check interestConfig.rate bounds:

interestConfig:
  rate:
    default: 15.5
    minimum: 12.0  # Must be <= default
    maximum: 35.0  # Must be >= default

Issue: "Tenure not allowed"

Cause: Requested months outside configured range.

Solution: Verify loanTenure settings:

loanTenure:
  minimumMonths: 6
  maximumMonths: 60  # Must accommodate request

Issue: "Fee calculation error"

Cause: Fee configuration mismatch.

Solution: Ensure fee calculation type matches value:

fees:
  - calculationType: "PercentOfPrincipal"
    value: 2.5  # Percentage (not 0.025)
  - calculationType: "Flat"
    value: 10000  # Fixed amount

Migration from V1

V1 Field Mapping

V1 Field/Table	V2 YAML Path
`LoanProduct.LoanProductType`	`basicInfo.loanProductType`
`LoanProduct.RepaymentAllocationOrder`	`basicInfo.repaymentAllocationOrder`
`LoanProductInterestSetting.*`	`interestConfig.*`
`RepaymentReschedulingSetting.*`	`repaymentConfig.*`
`LoanAmountSetting.*`	`principalRange.*`
`LoanProductPenaltySetting.*`	`penaltyConfig.*`
`LoanProductFee` records	`fees[]` array

Migration Script Example

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Last Updated: January 2, 2026
API Version: V2 (BPMCore)
Product Category: Loan Products
Complexity: ââ (Moderate)

Overview​

Key Features​

YAML Field Reference​

Basic Information Section​

Loan Tenure Section​

Principal Range Section​

Interest Configuration Section​

Repayment Configuration Section​

Fees Section​

Penalty Configuration Section​

Collateral Configuration Section​

Eligibility Configuration Section​

Notifications Configuration Section​

Complete Sample YAML Configuration​

Use Cases & Examples​

Example 1: Standard Personal Loan​

Example 2: Low-Income Personal Loan​

Example 3: High-Value Personal Loan​

Common Configurations​

Quick Approval Personal Loan​

Secured Personal Loan (Lower Rate)​

Interest Calculation Examples​

Declining Balance (Reducing Balance)​

Flat Rate (Less Common)​

Validation Rules​

Built-in Validations​

Business Rule Validations​

Troubleshooting​

Issue: "Interest rate out of range"​

Issue: "Tenure not allowed"​

Issue: "Fee calculation error"​

Migration from V1​

V1 Field Mapping​

Migration Script Example​