Salary Advance - V2 Configuration

Product Type: Digital Salary-Based Lending
Use Case: Emergency cash, short-term needs, payday advance
Typical Amount: ₦10,000 - ₦500,000
Typical Tenor: 1-6 months
Interest Rate: 5% - 15% per month (flat)

---

Overview

Salary Advance is a digital-first, mobile-optimized loan product for salaried employees with salary domiciliation. Designed for instant approval and quick disbursement, typically within 5 minutes.

Key Features

• Instant Approval: Automated decisioning in < 5 minutes
• Salary Domiciliation Required: Salary must be paid into bank account
• Auto-Debit Repayment: Automatic deduction on salary payment date
• Digital-First: Mobile app and USSD application
• Minimal Documentation: Employment letter only
• Flexible Amounts: 30%-75% of net monthly salary
• Cooling-Off Period: Mandatory 30 days between loans

---

YAML Field Reference

Basic Information Section

Field Name	Data Type	Required	Description	Example
productCode	String	✅ Yes	Unique product code	"SA-INSTANT-001"
productName	String	✅ Yes	Display name	"Instant Salary Advance"
description	String	No	Product description	"Quick cash for salaried staff"
isActive	Boolean	No	Product status	true
loanProductType	String	No	Loan type	"SalaryAdvance"
lineOfBusiness	Enum	No	Business classification	"Retail"

Loan Tenure Section

Field Name	Data Type	Required	Description	Example
minimumMonths	Integer	✅ Yes	Minimum tenor	1
maximumMonths	Integer	✅ Yes	Maximum tenor	6
defaultMonths	Integer	No	Default tenor	1

Principal Range Section

Field Name	Data Type	Required	Description	Example
minimumAmount	Decimal	No	Minimum loan amount	10000
maximumAmount	Decimal	No	Maximum loan amount	500000
defaultAmount	Decimal	No	Default amount	50000
salaryPercentage.minimum	Decimal	No	Min % of net salary	30
salaryPercentage.maximum	Decimal	No	Max % of net salary	75
salaryPercentage.default	Decimal	No	Default % of net salary	50

Salary Domiciliation Configuration

Field Name	Data Type	Required	Description	Example
requireSalaryDomiciliation	Boolean	✅ Yes	Mandatory salary payment	true
minimumSalaryMonths	Integer	✅ Yes	Min months of salary history	3
minimumNetSalary	Decimal	No	Min monthly net salary	50000
verificationMethod	Enum	✅ Yes	Salary verification method	"BankStatement"
employmentTypes[]	Array	No	Accepted employment types	["Permanent", "Contract"]
excludedEmployers[]	Array	No	Blacklisted employers	[]

Verification Methods: BankStatement, EmployerConfirmation, PaySlip, TaxRemittance

Interest Configuration Section

Field Name	Data Type	Required	Description	Example
isEnabled	Boolean	✅ Yes	Whether interest is charged	true
rate.default	Decimal	✅ Yes	Default rate (% per month)	5.0
rate.minimum	Decimal	No	Minimum rate	3.0
rate.maximum	Decimal	No	Maximum rate	15.0
calculationMethod	Enum	✅ Yes	Calculation method	"FlatRate"
rateTerms	Enum	No	Rate period	"PerMonth"

Auto-Debit Configuration Section

Field Name	Data Type	Required	Description	Example
enableAutoDebit	Boolean	✅ Yes	Automatic repayment	true
debitAccountSource	Enum	✅ Yes	Which account to debit	"SalaryAccount"
debitTiming	Enum	✅ Yes	When to debit	"OnSalaryPayment"
debitDayOffset	Integer	No	Days after salary payment	0
allowPartialDebit	Boolean	No	Allow partial if insufficient	false
mandateRequired	Boolean	No	Require signed mandate	true

Debit Timing Options: OnSalaryPayment, AfterSalaryPayment, FixedDate, CustomDate

Instant Approval Configuration Section

Field Name	Data Type	Required	Description	Example
enableInstantApproval	Boolean	✅ Yes	Automated decisioning	true
maxProcessingMinutes	Integer	No	Max approval time	5
scorecardModel	String	No	Credit scoring model	"SalaryAdvanceV2"
minimumCreditScore	Integer	No	Min score for auto-approval	500
autoDeclineScore	Integer	No	Score for auto-decline	300
manualReviewRange	Object	No	Score range for manual review	See sample

Eligibility Configuration Section

Field Name	Data Type	Required	Description	Example
minimumAge	Integer	No	Minimum age	21
maximumAge	Integer	No	Maximum age	60
employmentStatus[]	Array	✅ Yes	Accepted employment types	["Salaried"]
minimumServiceYears	Integer	No	Min years with employer	1
requiredDocuments[]	Array	✅ Yes	Mandatory documents	["EmploymentLetter", "BankStatement3Months"]
kycLevel	Enum	No	Required KYC tier	"Tier2"

Cooling-Off Period Configuration

Field Name	Data Type	Required	Description	Example
enableCoolingOffPeriod	Boolean	✅ Yes	Enforce waiting period	true
coolingOffDays	Integer	✅ Yes	Days between loans	30
applyOnFullRepayment	Boolean	No	Start after full repayment	true
allowOverride	Boolean	No	Manager can override	false

Fees Configuration Section

Field Name	Data Type	Required	Description	Example
fees[].code	String	✅ Yes	Fee code	"PROC_FEE"
fees[].name	String	✅ Yes	Fee name	"Processing Fee"
fees[].feeType	Enum	✅ Yes	Fee collection method	"DeductedDisbursement"
fees[].calculationType	Enum	✅ Yes	How to calculate	"Flat"
fees[].value	Decimal	✅ Yes	Fee amount	500
fees[].minimum	Decimal	No	Minimum fee	500
fees[].maximum	Decimal	No	Maximum fee	5000
fees[].glAccountId	Integer	✅ Yes	GL account	40001

Mobile/Digital Configuration Section

Field Name	Data Type	Required	Description	Example
mobileEnabled	Boolean	No	Enable mobile app	true
ussdEnabled	Boolean	No	Enable USSD code	true
ussdCode	String	No	USSD short code	"*737*5*1#"
webEnabled	Boolean	No	Enable web portal	true
biometricAuth	Boolean	No	Fingerprint/FaceID login	true

Notifications Configuration Section

Field Name	Data Type	Required	Description	Example
sendApplicationConfirmation	Boolean	No	Confirm application	true
sendApprovalNotification	Boolean	No	Notify approval	true
sendDisbursementNotification	Boolean	No	Confirm disbursement	true
sendRepaymentReminders	Boolean	No	Remind before debit	true
reminderDaysBefore	Integer	No	Days before debit	2
channels.sms	Boolean	No	Enable SMS	true
channels.email	Boolean	No	Enable email	true
channels.push	Boolean	No	Enable push	true

---

Complete Sample YAML Configuration

basicInfo:
  productCode: "SA-INSTANT-001"
  productName: "Instant Salary Advance"
  description: "Quick cash advance for salaried employees with instant approval"
  isActive: true
  loanProductType: "SalaryAdvance"
  repaymentAllocationOrder: "FEES_PENALTY_INTEREST_PRINCIPAL"
  lineOfBusiness: "Retail"
  currencyCode: "NGN"

loanTenure:
  minimumMonths: 1
  maximumMonths: 6
  defaultMonths: 1

principalRange:
  minimumAmount: 10000
  maximumAmount: 500000
  defaultAmount: 50000
  salaryPercentage:
    minimum: 30
    maximum: 75
    default: 50

salaryDomiciliationConfig:
  requireSalaryDomiciliation: true
  minimumSalaryMonths: 3
  minimumNetSalary: 50000
  verificationMethod: "BankStatement"
  employmentTypes:
    - "Permanent"
    - "Contract"
  excludedEmployers: []

interestConfig:
  isEnabled: true
  rate:
    default: 5.0  # 5% per month
    minimum: 3.0
    maximum: 15.0
  calculationMethod: "FlatRate"
  rateTerms: "PerMonth"

autoDebitConfig:
  enableAutoDebit: true
  debitAccountSource: "SalaryAccount"
  debitTiming: "OnSalaryPayment"
  debitDayOffset: 0
  allowPartialDebit: false
  mandateRequired: true

instantApprovalConfig:
  enableInstantApproval: true
  maxProcessingMinutes: 5
  scorecardModel: "SalaryAdvanceV2"
  minimumCreditScore: 500
  autoDeclineScore: 300
  manualReviewRange:
    minimum: 300
    maximum: 499

eligibilityConfig:
  minimumAge: 21
  maximumAge: 60
  employmentStatus:
    - "Salaried"
  minimumServiceYears: 1
  requiredDocuments:
    - "EmploymentLetter"
    - "BankStatement3Months"
    - "ValidID"
  kycLevel: "Tier2"

coolingOffConfig:
  enableCoolingOffPeriod: true
  coolingOffDays: 30
  applyOnFullRepayment: true
  allowOverride: false

fees:
  - code: "PROC_FEE"
    name: "Processing Fee"
    feeType: "DeductedDisbursement"
    calculationType: "Flat"
    value: 500
    minimum: 500
    maximum: 5000
    glAccountId: 40001

mobileConfig:
  mobileEnabled: true
  ussdEnabled: true
  ussdCode: "*737*5*1#"
  webEnabled: true
  biometricAuth: true

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

penaltyConfig:
  isEnabled: true
  tolerancePeriod: 0
  calculationMethod: "OverduePrincipal_DaysLate_Rate"
  rate:
    default: 10.0  # 10% per month on overdue
    minimum: 5.0
    maximum: 20.0

---

Use Cases & Examples

Example 1: Emergency Medical Expense

Scenario: Employee needs ₦50,000 for medical emergency.

Employee Profile:

• Net Monthly Salary: ₦150,000
• Employment: 2 years (permanent)
• Salary History: 6 months in bank
• Credit Score: 650

Application Flow:

1. Customer opens mobile app
2. Requests ₦50,000 (33% of salary ✅)
3. Automated decisioning:
   - Salary verification ✅
   - Credit score 650 > 500 ✅
   - Cooling-off check ✅
4. Instant approval (3 minutes)
5. Disbursement to account (2 minutes)

Repayment Calculation:

Principal: ₦50,000
Tenor: 1 month
Interest Rate: 5% flat
Processing Fee: ₦500

Interest: ₦50,000 × 5% = ₦2,500
Total Repayment: ₦50,000 + ₦2,500 = ₦52,500
Net Disbursement: ₦50,000 - ₦500 = ₦49,500

Auto-debit on next salary date: ₦52,500

Example 2: Multi-Month Salary Advance

Scenario: Employee needs ₦200,000 for home repairs over 3 months.

Employee Profile:

• Net Monthly Salary: ₦300,000
• Employment: 5 years
• Credit Score: 750

Configuration:

principalRange:
  requestedAmount: 200000  # 67% of salary
  
loanTenure:
  months: 3

interestConfig:
  rate: 4.0  # Lower rate for higher credit score

Repayment Schedule:

Principal: ₦200,000
Tenor: 3 months
Interest Rate: 4% per month (flat)
Processing Fee: ₦500

Monthly Interest: ₦200,000 × 4% = ₦8,000
Total Interest: ₦8,000 × 3 = ₦24,000
Total Repayment: ₦224,000
Monthly Deduction: ₦224,000 / 3 = ₦74,667

Month 1: ₦74,667 (auto-debit on salary date)
Month 2: ₦74,667
Month 3: ₦74,666

Example 3: USSD Application

Scenario: Employee uses USSD for quick loan.

USSD Flow:

Customer: *737*5*1#
Bank: Welcome to Salary Advance
      1. Apply for loan
      2. Check eligibility
      3. Loan balance

Customer: 1
Bank: Enter amount (₦10,000 - ₦500,000):

Customer: 100000
Bank: Tenor (1-6 months):

Customer: 1
Bank: Checking eligibility...
      ✅ Eligible for ₦100,000
      Interest: ₦5,000
      Repayment: ₦105,000
      Debit date: Next salary
      Reply 1 to confirm

Customer: 1
Bank: ✅ Approved!
      ₦99,500 credited to your account
      Ref: SA20260102001

---

Instant Approval Decision Tree

instantApprovalConfig:
  scorecardModel: "SalaryAdvanceV2"
  minimumCreditScore: 500
  autoDeclineScore: 300

Decisioning Logic:

Step 1: Credit Score Check
  Score ≥ 500 → AUTO-APPROVE
  300 ≤ Score < 500 → MANUAL REVIEW
  Score < 300 → AUTO-DECLINE

Step 2: Salary Verification (if not declined)
  Salary history < 3 months → DECLINE
  Net salary < ₦50,000 → DECLINE
  Requested > 75% of salary → DECLINE

Step 3: Cooling-Off Check
  Last loan < 30 days ago → DECLINE
  Outstanding loan exists → DECLINE

Step 4: Document Verification
  Employment letter missing → DECLINE
  Bank statement missing → DECLINE

Result:
  All checks passed → INSTANT APPROVAL (< 5 minutes)
  Any check failed → DECLINE or MANUAL REVIEW

Credit Scoring Factors:

• Salary consistency (40%)
• Repayment history (30%)
• Account age (15%)
• Transaction behavior (10%)
• External credit bureau (5%)

---

Salary-Based Limit Calculation

principalRange:
  salaryPercentage:
    minimum: 30
    maximum: 75

Calculation Examples:

Scenario 1: Conservative Limit

Net Monthly Salary: ₦100,000
Credit Score: 550 (Medium)
Employment: 1 year

Maximum Loan = ₦100,000 × 50% = ₦50,000

Scenario 2: Higher Limit

Net Monthly Salary: ₦200,000
Credit Score: 750 (Excellent)
Employment: 5 years
Perfect repayment history

Maximum Loan = ₦200,000 × 75% = ₦150,000

Scenario 3: First-Time Borrower

Net Monthly Salary: ₦150,000
Credit Score: 600
Employment: 2 years
No loan history

Maximum Loan = ₦150,000 × 30% = ₦45,000 (conservative)

---

Auto-Debit Process

autoDebitConfig:
  enableAutoDebit: true
  debitTiming: "OnSalaryPayment"
  debitDayOffset: 0

Debit Flow:

1. Salary Credit Detected
   ├─> Bank system monitors salary account
   ├─> Detects credit matching salary pattern
   └─> Triggers auto-debit process

2. Loan Identification
   ├─> Retrieves active salary advance loans
   ├─> Calculates total repayment due
   └─> Checks signed mandate

3. Account Balance Check
   ├─> Verifies sufficient balance
   ├─> If insufficient: Send alert (no partial debit)
   └─> If sufficient: Proceed to debit

4. Debit Execution
   ├─> Debit loan repayment amount
   ├─> Update loan status
   ├─> Send confirmation SMS/email
   └─> If fully repaid: Start cooling-off period

5. Exception Handling
   ├─> Insufficient funds: Retry next day (3 attempts)
   ├─> Account closed: Manual intervention
   └─> Mandate expired: Request renewal

---

Cooling-Off Period Enforcement

coolingOffConfig:
  enableCoolingOffPeriod: true
  coolingOffDays: 30
  applyOnFullRepayment: true

Purpose: Prevent debt cycle and encourage responsible borrowing.

Example Timeline:

Jan 1: Loan disbursed (₦50,000)
Jan 15: Auto-debit repayment (₦52,500)
Jan 15 - Feb 14: Cooling-off period (30 days)
Feb 15: Eligible for new loan ✅

Timeline Visualization:
|---Loan Active---|---Cooling-Off---|---Can Borrow Again---|
Jan 1           Jan 15            Feb 14               Future
  ↓                ↓                 ↓
Disburse         Repaid         Can reapply

Validation:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

---

Validation Rules

Salary Verification

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Instant Approval Validation

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

---

Troubleshooting

Issue: "Insufficient salary history"

Cause: Less than 3 months of salary credits in account.

Solutions:

1. Wait until 3 salary credits are received
2. Provide additional salary evidence (payslips, tax remittance)
3. Apply through alternate product (Personal Loan with documentation)

Issue: "Cooling-off period active"

Cause: Less than 30 days since last loan repayment.

Solution:

Last Repayment: Jan 15
Next Eligible: Feb 14
Current Date: Jan 20
Days Remaining: 25 days

Wait until cooling-off period expires.
(No override allowed per config)

Issue: "Auto-debit failed"

Cause: Insufficient balance on salary payment date.

Solutions:

1. Automatic Retries:
   - Day 1: Failed (insufficient funds)
   - Day 2: Retry 1 (failed)
   - Day 3: Retry 2 (failed)
   - Day 4: Retry 3 → Final attempt

2. Customer Action:
   - Fund account before retry
   - Contact bank for manual payment
   - Risk: Penalty interest accumulates

3. Bank Action:
   - Send alerts after each failed attempt
   - Escalate to collections after 3 failures
   - Report to credit bureau after 30 days

---

Migration from V1

V1 Salary Advance Mapping

V1 Field/Table	V2 YAML Path
SalaryAccount	autoDebitConfig.debitAccountSource
SalaryThreshold	salaryDomiciliationConfig.minimumNetSalary
ApprovalTime	instantApprovalConfig.maxProcessingMinutes
CoolingPeriod	coolingOffConfig.coolingOffDays
MaxSalaryPercentage	principalRange.salaryPercentage.maximum
USSDCode	mobileConfig.ussdCode

Sample Migration Script

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 - Digital/Automated)