PT Calculator
Overview
PT-Calculator Service is used for creating demands based on property assessments, mutations, and updating demands with the penalty, interest in case of payment delay.
Pre-requisites
Before you proceed with the documentation, make sure the following pre-requisites are met -
Java 8
Kafka server is up and running
PSQL server is running and a database is created to store property/application data
Following services should be up and running:
MDMS
property-services
billing-service
Key Functionalities
Calculate the property tax and mutation fee based on the billing slab.
create and update demand.
Deployment Details
Deploy the latest version of the property service and pt-calculator
Billing Slabs
Criteria:
Property Type
Property Subtype
Usage Category Major
Usage Category Minor
Usage Category Subminor
Usage Category Detail
Ownership Category
Sub Ownership Category
Plot Size
Floor Number
Area Type
The combination of the above variables can be used to define a billing slab. The billing slabs are stored in the database in the table named “eg_pt_billingslab_v2”. To perform CRUD operations on the billing slabs, the module provides APIs. Following is a sample create request:
The ‘ALL' keyword can be used if the slab is independent of that particular variable. If ‘fromPlotSize’ or ‘toPlotSize’ values are null, they will be set to positive infinity and negative infinity, respectively. A similar process applies to ‘fromFloor’ and ‘toFloor’ values.
Estimation
The estimation service class loops through all the units and calculates the tax based on the applicable billing slab. The exemptions are calculated using master data in MDMS Service. Each tax or exemption is added to the tax head estimate. Following are the exemptions and taxes that are calculated:
Property Base Tax
Owner Exemption
Unit Exemption
Penalty
Rebate
Interest
Fire Cess
Cancer Cess
From the above charges and exemptions penalty, interest and rebate are time-based. Rebate is given if the payment is done before the rebate deadline date specified in Rebate master data. Similarly, the penalty is charged if payment is not done before the deadline to pay tax. After the deadline to pay tax is passed daily interest is charged according to the rate defined in the master.
Property Tax
Property tax is calculated by adding the tax for each unit calculated using the billing slab for that unit. The formula for calculating tax for the unit is:
In case the unit is commercial and rented the formula is as follows:
ARV stands for Annual rent value.
If the property contains ground units (i.e., units with floor number = 0) then tax is also calculated for the unbuilt area. The formula for calculating the tax on the unbuilt area is as follows:
Interest
Below is a sample of master data JSON for interest :
If the given year rate is not defined, the service will recursively fall back on the previous year until it finds a defined rate slab. The time for which interest is applicable is calculated by subtracting the epoch value of the starting day (At 00:00 AM) from the epoch value of the end of the day (23:59) of the current date. In the case of partial payment, interest is calculated for each interval between payments and summed, since the applicable interest amount won’t be constant across intervals.
Round Off
If the fraction is greater than or equal to 0.5, round up; otherwise, round down. eg: 100.4 will be rounded to 100 while 100.6 will be rounded to 101
Penalty
The following is the format of penalty master data:
If the demand creation date is later than the penalty start date, a penalty of x% will be applied. The x% is defined in the rate field. The penalty also provides a fallback for master data: if an entry is not present for a particular year, it will recursively search for the previous year and apply that rate.
Owner Exemption
Depending on the owner type, an absolute amount or a percentage of the tax amount is granted as an exemption. For multiple owners, the exemption is calculated for each owner and then summed. Following is a sample master data:
Demand Generation
Once the property is entered into the calculator, its tax estimates are generated. Using these tax head estimates, demand details are created. For every tax head, the estimate-demand function will create a corresponding demand detail.
Whenever the _calculate API is called, the demand is first searched by property ID and the from-to period. If demand already exists, it is updated; otherwise, new demand is generated, with the consumer code as the property, and demand from and to a period equal to the financial year start and end periods. In the case of Reassessment, the demand is always updated for the given year.
In case of an update, if the tax head estimates change, the difference for that tax head is added as a new demand detail. For example, if the initial demand has one demand detail with PT_TAX equal to 100
After updating, if PT_TAX increases to 150, we add one more demand detail to account for the increase. The demand detail will be updated to:
RoundOff is bill-based: whenever a bill is generated, the round-off is adjusted so that the payable amount is a whole number. Individual PT_ROUNDOFF values in the demand detail can exceed 0.5, but the sum of all PT_ROUNDOFF values will always be less than 0.5.
Example:
If demand is created and the total tax is 100.40, a negative round-off of -0.40 is added to bring the tax to 100. If, during reassessment, the tax changes to 111.70, the estimate will round it to 111.70, giving a tax head estimate of +0.3. The demand generation logic will add a new demand detail by calculating the difference between the old and new tax amounts for that tax head. Therefore, a new demand detail of 0.3- (-0.4) = 0.7 will be added. There will now be two PT_ROUNDOFF tax heads: one with an amount of -0.4 and the other with 0.7. The total round-off amount is (-0.4+0.7)=0.3, which, with the tax amount of 111.70, gives a bill amount of 111.70+0.3=112.
Integration Details
Integration Scope
PT-calculator should be integrated with property-services, which internally invokes the calculator service to calculate and generate demand for the charges.
Integration Benefits
Carries out the process of creating demand and updating them on a need basis as per the requirements of assessment and mutation.
Steps to Integration
/_calculate should be exposed internally for property-services integration.
/_estimate API should be exposed for UI integration, enabling users to view the estimate before proceeding.
/demand/_update API should be configured in the billing service for the demand update function on bill expiry.
Reference Docs
Property-services Property Services
API Collection - https://www.getpostman.com/collections/d7c858f62b53d17c4335
Last updated
Was this helpful?