Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source

What This Module Is (Big Picture)

The tax module manages how taxes are calculated and applied to transactions.
Taxes may apply to:
  • loan interest
  • service charges
  • account maintenance fees
  • penalties
  • transaction fees
This module ensures that correct tax amounts are calculated and recorded.

Layman Example

Imagine a loan interest payment.
Customer pays interest = ₹1,000
If tax rate = 10%
Tax amount = ₹100
Final accounting:
Interest income = ₹900
Tax payable to government = ₹100
The tax module calculates and splits these amounts automatically.

Where the Code Lives

Key Package

org.apache.fineract.portfolio.tax
Responsibilities include:
  • defining tax components
  • grouping tax components
  • calculating tax amounts
  • applying tax to transactions

Core Domain Entity:

TaxComponent.java

Path
fineract-tax/src/main/java/org/apache/fineract/portfolio/tax/domain/TaxComponent.java
This class represents a single tax rule.

Key fields on

TaxComponent

Tax Groups

Often multiple taxes must be applied together.
Example:
Service Tax = 8%
Education Tax = 2%
Total tax = 10%
This is handled using Tax Groups.

Core Entity:

TaxGroup.java

Path
fineract-tax/src/main/java/org/apache/fineract/portfolio/tax/domain/TaxGroup.java
A tax group represents a collection of tax components.

Key fields on

TaxGroup

Example Tax Calculation

If transaction amount = ₹1000
Tax group contains:
VAT = 8%
Service tax = 2%
Total tax = 10%
Final tax amount = ₹100

Example Tax Calculation Code

java
QUBITS OF DPK
1public BigDecimal calculateTax(BigDecimal amount, BigDecimal taxPercentage) {
2    return amount.multiply(taxPercentage)
3                 .divide(BigDecimal.valueOf(100));
4}
This method calculates the tax amount for a transaction.

API Layer

Tax APIs allow administrators to configure tax rules.
Example controller
TaxApiResource
Example endpoints
java
QUBITS OF DPK
1GET  /v1/taxes
2POST /v1/taxes
3GET  /v1/taxgroups
4POST /v1/taxgroups
These APIs allow:
  • creating tax components
  • creating tax groups
  • viewing tax configurations

Read Services

Read services retrieve tax configurations.
Examples:
  • retrieve tax components
  • retrieve tax groups
  • retrieve tax rules
These are used when transactions occur to determine applicable taxes.

Write Services

Write services allow administrators to manage tax configurations.
Responsibilities include:
  • creating tax rules
  • updating tax percentages
  • managing tax groups

Tax Application Flow

When a financial transaction occurs:
  1. #
    System identifies applicable tax group
  2. #
    Each tax component is applied
  3. #
    Total tax amount calculated
  4. #
    Transaction split into taxable and tax portions
  5. #
    Accounting entries created

Example Flow

Customer pays loan interest
java
QUBITS OF DPK
1Loan Service
2    │ interest payment
3    ▼
4Tax Processor
5    │ calculate tax
6    ▼
7TaxComponentService
8    │ apply tax percentage
9    ▼
10Accounting Module
11    │ record tax liability
12    ▼
13Database

Repository Layer

Exceptions

These ensure taxes are applied correctly.

Why This Module Matters

The tax module ensures:
  • regulatory compliance
  • accurate tax calculations
  • correct accounting of tax liabilities
Financial institutions must correctly calculate and report taxes.

One-Sentence Summary

fineract-tax manages tax rules and calculations applied to financial transactions such as interest payments, service charges, and fees.