Deposit Product - Accounting Configuration (V2)

Module: Deposit Products
Configuration Section: accountingConfig
Version: V2 (ConfigData YAML)
Status: âœ… Production Ready

Overview

The Accounting Configuration section defines how deposit transactions are posted to the General Ledger. V2 uses a flexible Account Leg system where each transaction type maps to specific GL accounts based on the accounting methodology.

Key Concepts

Account Legs: Predefined transaction components (e.g., SavingsControl, InterestExpense)
Methodology: Accrual or Cash accounting
GL Account Mapping: Each leg maps to a specific GL account code
Multi-Company Support: Optional company-specific GL accounts

Accounting Methodology

Methodology	Description	When to Use	Impact
Cash	Recognize transactions when cash moves	Simple operations, small institutions	Interest posted only when paid
Accrual	Recognize transactions when obligation created	Standard banking practice, regulatory compliance	Interest accrued daily, posted periodically

Cash vs Accrual Comparison

Cash Accounting:

accountingConfig:
  interestRecognitionMethod: Cash

âœ… Simple and straightforward
âœ… Real-time cash flow visibility
âŒ Doesn't show future obligations
âŒ Less accurate financial position
Use Case: Microfinance, small savings schemes

Accrual Accounting:

accountingConfig:
  interestRecognitionMethod: Accrual

âœ… True financial position (IFRS compliant)
âœ… Shows accrued interest payable
âœ… Better for regulatory reporting
âŒ More complex GL posting
Use Case: Commercial banking, regulated institutions

Account Leg Types

The V2 system defines 8 standard account legs for deposit products:

1. SavingsControl (Required)

Purpose: Customer deposit liability account
Account Type: Liability
Normal Balance: Credit

Transactions:

Deposit: Credit (increase liability)
Withdrawal: Debit (decrease liability)
Transfer Out: Debit
Transfer In: Credit

Example:

- legType: SavingsControl
  accountCode: "2010100"  # Savings Deposits - Customer Liabilities
  description: "Customer savings deposit control account"

2. InterestExpense (Accrual Only)

Purpose: Interest cost to the bank
Account Type: Expense
Normal Balance: Debit

Transactions:

Interest Accrual: Debit (increase expense)
Interest Payment: No entry (already expensed)

Example:

- legType: InterestExpense
  accountCode: "5020100"  # Interest Expense on Deposits
  description: "Interest expense for savings accounts"

3. InterestPayable (Accrual Only)

Purpose: Accrued but unpaid interest liability
Account Type: Liability
Normal Balance: Credit

Transactions:

Daily Accrual: Credit (increase liability)
Interest Payment: Debit (clear liability)

Example:

- legType: InterestPayable
  accountCode: "2030200"  # Accrued Interest Payable
  description: "Accrued interest liability on savings"

4. FeeIncome (Required)

Purpose: Service charges and transaction fees revenue
Account Type: Income
Normal Balance: Credit

Transactions:

Monthly Maintenance Fee: Credit (income)
Excess Withdrawal Fee: Credit (income)
Below Minimum Balance Fee: Credit (income)

Example:

- legType: FeeIncome
  accountCode: "4010500"  # Fee Income
  description: "Transaction and maintenance fee income"

5. WithholdingTax (Optional)

Purpose: Tax withheld on interest payments
Account Type: Liability
Normal Balance: Credit

Transactions:

Interest Payment: Credit (tax withheld)
Tax Remittance: Debit (pay to tax authority)

Example:

- legType: WithholdingTax
  accountCode: "2040300"  # Withholding Tax Payable
  description: "10% withholding tax on interest income"

6. Suspense (Optional)

Purpose: Temporary holding for unidentified transactions
Account Type: Liability/Asset (depending on balance)
Normal Balance: Varies

Transactions:

Unidentified Deposits: Credit
Resolved Items: Debit/Credit (reverse)

Example:

- legType: Suspense
  accountCode: "2050400"  # Suspense Account
  description: "Temporary holding for unidentified transactions"

7. OverdraftControl (Optional)

Purpose: Overdraft facility liability account
Account Type: Asset (money lent to customer)
Normal Balance: Debit

Transactions:

Overdraft Granted: Debit (asset increase)
Overdraft Repayment: Credit (asset decrease)

Example:

- legType: OverdraftControl
  accountCode: "1030500"  # Overdraft Loans
  description: "Overdraft facility extended to savings accounts"

8. ChannelSettlement (Optional)

Purpose: Settlement account for specific channels
Account Type: Asset
Normal Balance: Debit

Transactions:

Channel Deposit: Debit (cash received)
Channel Withdrawal: Credit (cash paid)

Example:

- legType: ChannelSettlement
  accountCode: "1010600"  # Mobile Channel Settlement
  description: "Settlement account for mobile banking transactions"

Complete AccountingConfig Section

Basic Structure

accountingConfig:
  interestRecognitionMethod: Cash | Accrual
  accountLegs:
    - legType: SavingsControl
      accountCode: "string"
      companyCode: "string"  # Optional
      description: "string"  # Optional
    - legType: InterestExpense
      accountCode: "string"
      # ... additional legs

Field Reference

Field Name	Data Type	Required	Description	Example
`interestRecognitionMethod`	Enum	âœ… Yes	Accounting methodology	`"Cash"` or `"Accrual"`
`accountLegs[]`	Array	âœ… Yes	GL account mappings	See below
`accountLegs[].legType`	Enum	âœ… Yes	Account leg type	`"SavingsControl"`
`accountLegs[].accountCode`	String	âœ… Yes	GL account code	`"2010100"`
`accountLegs[].companyCode`	String	No	Company code (multi-company)	`"COMP001"`
`accountLegs[].description`	String	No	Leg description	`"Customer deposits"`

Required Account Legs by Methodology

Methodology	Required Legs	Optional Legs
Cash	â€¢ SavingsControl â€¢ FeeIncome	â€¢ WithholdingTax â€¢ Suspense â€¢ OverdraftControl â€¢ ChannelSettlement
Accrual	â€¢ SavingsControl â€¢ InterestExpense â€¢ InterestPayable â€¢ FeeIncome	â€¢ WithholdingTax â€¢ Suspense â€¢ OverdraftControl â€¢ ChannelSettlement

Sample Configurations

Example 1: Cash Accounting (Simple Savings)

accountingConfig:
  interestRecognitionMethod: Cash
  accountLegs:
    # Customer deposit liability
    - legType: SavingsControl
      accountCode: "2010100"
      description: "Savings Deposits - Customer Liabilities"
    
    # Fee income from service charges
    - legType: FeeIncome
      accountCode: "4010500"
      description: "Service Charge Income"
    
    # Optional: Withholding tax on interest
    - legType: WithholdingTax
      accountCode: "2040300"
      description: "Withholding Tax Payable (10%)"

Transaction Flow (Deposit of â‚¦10,000):

DR: Cash/Channel Account     â‚¦10,000
CR: SavingsControl (2010100)  â‚¦10,000

Transaction Flow (Monthly Interest Payment of â‚¦50):

DR: Interest Expense          â‚¦50.00
CR: SavingsControl (2010100)  â‚¦45.00  (90%)
CR: WithholdingTax (2040300)  â‚¦5.00   (10%)

Example 2: Accrual Accounting (Standard Banking)

accountingConfig:
  interestRecognitionMethod: Accrual
  accountLegs:
    # Customer deposit liability
    - legType: SavingsControl
      accountCode: "2010100"
      description: "Savings Deposits - Customer Liabilities"
    
    # Interest expense recognition
    - legType: InterestExpense
      accountCode: "5020100"
      description: "Interest Expense on Deposits"
    
    # Accrued interest liability
    - legType: InterestPayable
      accountCode: "2030200"
      description: "Accrued Interest Payable"
    
    # Fee income
    - legType: FeeIncome
      accountCode: "4010500"
      description: "Service Charge Income"
    
    # Withholding tax
    - legType: WithholdingTax
      accountCode: "2040300"
      description: "Withholding Tax Payable (10%)"

Transaction Flow (Daily Interest Accrual of â‚¦1.50):

DR: InterestExpense (5020100)  â‚¦1.50
CR: InterestPayable (2030200)  â‚¦1.50

Transaction Flow (Monthly Interest Payment of â‚¦50):

DR: InterestPayable (2030200)  â‚¦50.00
CR: SavingsControl (2010100)   â‚¦45.00  (90%)
CR: WithholdingTax (2040300)   â‚¦5.00   (10%)

Example 3: Multi-Company Configuration

accountingConfig:
  interestRecognitionMethod: Accrual
  accountLegs:
    # Company A - Main operations
    - legType: SavingsControl
      accountCode: "2010100"
      companyCode: "COMP_A"
      description: "Savings Deposits - Company A"
    
    # Company B - Branch operations
    - legType: SavingsControl
      accountCode: "2010200"
      companyCode: "COMP_B"
      description: "Savings Deposits - Company B"
    
    # Shared fee income (no company code)
    - legType: FeeIncome
      accountCode: "4010500"
      description: "Service Charge Income (All Companies)"
    
    # ... other legs

Transaction Processing

How BPMCore Uses AccountingConfig

All BPMCore transaction handlers follow this pattern:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Validation Rules

The system automatically validates:

Required Legs Present: Based on methodology
Valid Account Codes: GL accounts must exist
No Duplicates: Each leg type appears once per company
Methodology Consistency: Accrual requires InterestExpense + InterestPayable

Example Validation Error:

# âŒ INVALID: Missing InterestPayable for Accrual
accountingConfig:
  interestRecognitionMethod: Accrual
  accountLegs:
    - legType: SavingsControl
      accountCode: "2010100"
    - legType: InterestExpense
      accountCode: "5020100"
    # Missing: InterestPayable (required for Accrual)

Error Message: "Accrual accounting requires InterestPayable account leg"

Migration from V1

V1 Structure (Old)

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

V2 Structure (New)

accountingConfig:
  interestRecognitionMethod: Accrual
  accountLegs:
    - legType: SavingsControl
      accountCode: "2010100"
    - legType: InterestExpense
      accountCode: "5020100"

Migration Benefits

Flexibility: Add custom legs without schema changes
Multi-Company: Support multiple companies in one product
Validation: Built-in YAML validation
Documentation: Self-documenting with descriptions
Extensibility: Easy to add new leg types

Automatic V1 Fallback

If ConfigData is null, the system automatically uses V1:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Troubleshooting

Common Issues

Issue 1: Missing Required Leg

Error: "SavingsControl account leg is required"

Solution:

accountingConfig:
  interestRecognitionMethod: Cash
  accountLegs:
    - legType: SavingsControl  # âœ… Add this
      accountCode: "2010100"

Issue 2: Invalid GL Account

Error: "GL Account '9999999' not found"

Solution: Verify account code exists in Chart of Accounts

Issue 3: Methodology Mismatch

Error: "InterestExpense not required for Cash methodology"

Solution: Remove unused legs or change methodology to Accrual

Issue 4: Duplicate Legs

Error: "Duplicate account leg: SavingsControl"

Solution: Each legType should appear only once (unless using companyCode)

Best Practices

1. Use Accrual for Regulated Institutions

# âœ… RECOMMENDED: Standard banking
interestRecognitionMethod: Accrual

2. Document Each Leg

# âœ… GOOD: Clear descriptions
- legType: SavingsControl
  accountCode: "2010100"
  description: "Customer savings deposits - retail"

3. Separate Income Streams

# âœ… GOOD: Separate fee income from interest
- legType: FeeIncome
  accountCode: "4010500"  # Transaction fees
- legType: FeeIncome
  accountCode: "4010600"  # Maintenance fees (if needed)

4. Plan for Multi-Company Early

# âœ… FUTURE-PROOF: Include companyCode from start
- legType: SavingsControl
  accountCode: "2010100"
  companyCode: "DEFAULT"  # Even if single company now

5. Validate Before Deployment

# âœ… TEST: Validate with sample transactions
# - Create test account
# - Post sample deposits/withdrawals
# - Verify GL entries

Version History

Version	Date	Changes
V2.0	Jan 2026	Initial V2 AccountingConfig documentation
V1.0	-	Legacy table-based accounting (deprecated)

Support

For questions or issues:

Check Troubleshooting section
Review Sample Configurations
Contact: Technical Support Team

Overview​

Key Concepts​

Accounting Methodology​

Cash vs Accrual Comparison​

Account Leg Types​

1. SavingsControl (Required)​

2. InterestExpense (Accrual Only)​

3. InterestPayable (Accrual Only)​

4. FeeIncome (Required)​

5. WithholdingTax (Optional)​

6. Suspense (Optional)​

7. OverdraftControl (Optional)​

8. ChannelSettlement (Optional)​

Complete AccountingConfig Section​

Basic Structure​

Field Reference​

Required Account Legs by Methodology​

Sample Configurations​

Example 1: Cash Accounting (Simple Savings)​

Example 2: Accrual Accounting (Standard Banking)​

Example 3: Multi-Company Configuration​

Transaction Processing​

How BPMCore Uses AccountingConfig​

Validation Rules​

Migration from V1​

V1 Structure (Old)​

V2 Structure (New)​

Migration Benefits​

Automatic V1 Fallback​

Troubleshooting​

Common Issues​

Best Practices​

1. Use Accrual for Regulated Institutions​

2. Document Each Leg​

3. Separate Income Streams​

4. Plan for Multi-Company Early​

5. Validate Before Deployment​

Related Documentation​

Version History​

Support​

Overview

Key Concepts

Accounting Methodology

Cash vs Accrual Comparison

Account Leg Types

1. SavingsControl (Required)

2. InterestExpense (Accrual Only)

3. InterestPayable (Accrual Only)

4. FeeIncome (Required)

5. WithholdingTax (Optional)

6. Suspense (Optional)

7. OverdraftControl (Optional)

8. ChannelSettlement (Optional)

Complete AccountingConfig Section

Basic Structure

Field Reference

Required Account Legs by Methodology

Sample Configurations

Example 1: Cash Accounting (Simple Savings)

Example 2: Accrual Accounting (Standard Banking)

Example 3: Multi-Company Configuration

Transaction Processing

How BPMCore Uses AccountingConfig

Validation Rules

Migration from V1

V1 Structure (Old)

V2 Structure (New)

Migration Benefits

Automatic V1 Fallback

Troubleshooting

Common Issues

Best Practices

1. Use Accrual for Regulated Institutions

2. Document Each Leg

3. Separate Income Streams

4. Plan for Multi-Company Early

5. Validate Before Deployment

Related Documentation

Version History

Support