Overview:

The main objective of the billing module is to serve the Bill for all revenue Business services. To serve the Bill, Billing-Service requires demand. Demands will be prepared by Revenue modules and stored by billing based on which it will generate the Bill.

Pre-requisites:

Prior Knowledge of Java/J2EE.
Prior Knowledge of Spring Boot.
Prior Knowledge of KAFKA
Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON, etc.
Prior knowledge of the demand-based systems.
Following services should be up and running:
- user
- MDMS
- Id-Gen
- URL-Shortening
- notification-sms

Key Functionality:

eGov billing service creates and maintains demands.
Generates bills based on demands.
Updates the demands from payment when the collection service takes a payment.

Deployment Details:

Deploy the latest image of the billing service available.

Configuration Details:

In the MDMS data configuration, the following master data is needed for the functionality of billing

MDMS:

Business Service JSON

{
  "tenantId": "pb",
  "moduleName": "BillingService",
  "BusinessService": [
    {
      "businessService": "PropertyTax",
      "code": "PT",
      "isBillAmendmentEnabled":"true",
      "collectionModesNotAllowed": [
        "DD","OFFLINE_NEFT","OFFLINE_RTGS","POSTAL_ORDER"
      ],
      "partPaymentAllowed": true,
      "minAmountPayable":100,
      "isAdvanceAllowed": false,
      "demandUpdateTime": 86400000,
      "isVoucherCreationEnabled": true,
      "billGineiURL" : "egov-searcher/bill-genie/billswithaddranduser/_get"
    },
    {
      "businessService": "WaterCharges",
      "code": "WC",
      "isBillAmendmentEnabled":"true",
      "collectionModesNotAllowed": [
        "DD","OFFLINE_NEFT","OFFLINE_RTGS","POSTAL_ORDER"
      ],
      "partPaymentAllowed": false,
      "isAdvanceAllowed": true,
      "demandUpdateTime": 86400000,
      "isVoucherCreationEnabled": false
    },
    {
      "businessService": "TradeLicense",
      "code": "TL",
      "collectionModesNotAllowed": [
        "DD","OFFLINE_NEFT","OFFLINE_RTGS","POSTAL_ORDER"
      ],
      "partPaymentAllowed": false,
      "isAdvanceAllowed": false,
      "demandUpdateTime": 604800000,
      "isVoucherCreationEnabled": true
    }
  ]
}

TAX-Head JSON

{
  "tenantId": "pb",
  "moduleName": "BillingService",
  "TaxHeadMaster": [
    {
      "category": "ADVANCE_COLLECTION",
      "service": "PT",
      "name": "Pt advance carry forward",
      "code": "PT_ADVANCE_CARRYFORWARD",
      "isDebit": true,
      "isActualDemand": false,
      "order": "0",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt owner exemption",
      "code": "PT_OWNER_EXEMPTION",
      "isDebit": true,
      "isActualDemand": true,
      "order": "5",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt time rebate",
      "code": "PT_TIME_REBATE",
      "isDebit": true,
      "isActualDemand": true,
      "order": "2",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt unit usage excemption",
      "code": "PT_UNIT_USAGE_EXEMPTION",
      "isDebit": true,
      "isActualDemand": true,
      "order": "6",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt adhoc penalty",
      "code": "PT_ADHOC_PENALTY",
      "isDebit": false,
      "isActualDemand": false,
      "order": "1",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "propertytax",
      "code": "PT_TAX",
      "isDebit": false,
      "isActualDemand": true,
      "order": "0",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt fire cess",
      "code": "PT_FIRE_CESS",
      "isDebit": false,
      "isActualDemand": true,
      "order": "7",
      "isRequired": false
    }
  ]
}

Tax-Period JSON

{
  "tenantId": "pb",
  "moduleName": "BillingService",
  "TaxPeriod": [
    {
      "fromDate": 1554076799000,
      "toDate": 1585679399000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2019",
      "financialYear": "2019-20"
    },
    {
      "fromDate": 1522540800000,
      "toDate": 1554076799000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2018",
      "financialYear": "2018-19"
    },
    {
      "fromDate": 1491004800000,
      "toDate": 1522540798000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2017",
      "financialYear": "2017-18"
    },
    {
      "fromDate": 1459468800000,
      "toDate": 1491004799000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2016",
      "financialYear": "2016-17"
    },
    {
      "fromDate": 1522540800000,
      "toDate": 1554076799000,
      "periodCycle": "ANNUAL",
      "service": "TL",
      "code": "TLAN2018",
      "financialYear": "2018-19"
    }
  ]
}


bs.businesscode.demand.updateurl	{ "PT":"http://pt-calculator-v2:8080/pt-calculator-v2/propertytax/_updatedemand", "TL":"" }	Each module’s application calculator should provide its own update URL. if not present then new bill will be generated without making any changes to the demand.
bs.bill.billnumber.format	BILLNO-{module}-[SEQ_egbs_billnumber{tenantid}]	IdGen format for bill number
`bs.amendment.idbs.bill.billnumber.format`	`BILLNO-{module}-[SEQ_egbs_billnumber{tenantid}]`
`is.amendment.workflow.enabled`	`true/false`	enable disable workflow of bill amendment

Integration

Integration Scope

Billing service can be integrated with any organization or system that wants a demand-based payment system.

Integration Benefits

Easy to create and simple process of generating bills from demands
The amalgamation of bills period-wise for a single entity like PT or Water connection.
Amendment of bills in case of legal requirements.

Steps to Integration

Customer can create a demand using the /demand/_create
Organization or System can search the demand using /demand/_searchendpoint
Once the demand is raised the system can call /demand/_update endpoint to update the demand as per need.
Bills can be generated using, which is a self-managing API that generates a new bill only when the old one expires /bill/_fetchbill.
Bills can be searched using /bill/_search.
Amendment facility can be used in case of a legal issue to add values to existing demands using /amendment/_create and /amendment/_update can used to cancel the created ones or update workflow if configured.

Interaction Diagram

Interaction Diagram V1.1:

Reference Docs

Doc Links

Title	Link
Id-Gen service
url-shortening
MDMS

API List

Title	Link
/demand/_create, _update, _search	https://www.getpostman.com/collections/900d99a85d083fb2d377
/bill/_fetchbill, _search	https://www.getpostman.com/collections/900d99a85d083fb2d377
/amendment/_create, _update	https://www.getpostman.com/collections/b195d3b1d354c767b6bd

Apportioning :

What is apportioning?

Adjusting the receivable amount with the individual tax head.

Types of apportioning V1.1:

Default order based apportioning(Based on apportioning order adjust the received amount with each tax head).V1.1

Types of apportioning V1.2: (TBD)

Proportionate based apportioning (Adjust total receivable with all the tax head equally)
Order & Percentage based apportioning(Adjust total receivable based on order and the percentage which is defined for each tax head).

Principle of apportioning:

The basic principle of apportioning is, if the full amount is paid for any bill then each individual tax head should get nullify with their corresponding adjusted amount.

Example:
Case 1: When there are no arrears all tax heads belong to their current purpose:

TaxHead	Amount	Order	Full Payment(2000)	Partial Payment1(1500)	Partial payment2(750)	Partial payment2 with rebate(500)

Pt_tax	1000	6	1000	1000	750	750
AdjustedAmt			1000	-250	-750	-750
RemainingAMTfromPayableAMT			0	0	0	0

Penality	500	5	500	500
AdjustedAmt			500	-500
RemainingAMTfromPayableAMT			1000	250


Interest	500	4	500	500
AdjustedAmt			500	-500
RemainingAMTfromPayableAMT			1500	750

Cess	500	3	500	500
AdjustedAmt			500	-500
RemainingAMTfromPayableAMT			2000	1250

Exm	-250	1	-250	-250
AdjustedAmt			-250	250
RemainingAMTfromPayableAMT			2250	1750

Rebate	-250	2	-250			-250
AdjustedAmt			-250			250
RemainingAMTfromPayableAMT			2500			750

Case 2: Apportioning with two years of arrear:
If the current financial year is 2014-15. Below are the demands

TaxHead	Amount	TaxPeriodFrom	TaxPeriodTo	Order	Purpose

Pt_tax	1000	2014	2015	6	Current
AdjustedAmt	0

Penality	500	2014	2015	5	Current
AdjustedAmt	0

Interest	500	2014	2015	4	Current
AdjustedAmt	0

Cess	500	2014	2015	3	Current
AdjustedAmt	0

Exm	-250	2014	2015	1	Current
AdjustedAmt	0

if any payment is not done, and we generating demand in 2015-16 then the demand structure will as follows:

TaxHead	Amount	TaxPeriodFrom	TaxPeriodTo	Order	Purpose

Pt_tax	1000	2014	2015	6	Arrear
AdjustedAmt	0

Pt_tax	1500	2015	2016	6	Current
AdjustedAmt	0

Penality	600	2014	2015	5	Arrear
AdjustedAmt	0

Penalty	500	2015	2016	5	Current
AdjustedAmt	0

Interest	500	2014		4	Arrear
AdjustedAmt	0

Cess	500	2014		3	Arrear
AdjustedAmt	0

Exm	-250	2014		1	Arrear
AdjustedAmt	0

eGov Knowledge Base

Billing Service