Skip to content

Latest commit

 

History

History
349 lines (299 loc) · 17.7 KB

README.md

File metadata and controls

349 lines (299 loc) · 17.7 KB
Raw

Billing Service

Overview

The main objective of the billing module is to generate the bill for all revenue-based business services. To serve the bill, the Billing-Service requires demand. Demands will be prepared by the revenue modules and stored by billing based on which it generates 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 demand-based systems.
  • The following services should be up and running:
    • user
    • MDMS
    • Id-Gen
    • URL-Shortening
    • notification-sms

Key Functionalities

  • 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 the 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"
    }
  ]
}
Variable Path Description
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 a 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 the 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 Details

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

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

Interaction Diagram

Interaction Diagram V1.1:

Reference Docs

Doc Links

Description Link
Id-Gen service ****
url-shortening
MDMS

API List

Description 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 FAQs

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 heads 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 holds that if the full amount is paid for any bill then each individual tax head should get nullified with their corresponding adjusted amount.

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

Example: given below

Tax Head Amount Order Full Payment (2000) Partial Payment (1500) Partial Payment (750) Partial Payment 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:
Example: The apportioning details for the financial year 2014-15 are given below.

Tax Head Amount Tax Period From Tax Period To 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

The table below illustrates the demand structure generated in case there are no payments for the specified financial year (2015-16).

Tax Head Amount Tax Period From Tax Period To Order Purpose
Pt_tax 1000 2014 2015 6 Arrear
AdjustedAmt 0
Pt_tax 1500 2015 2016 6 Current
AdjustedAmt 0
Penalty 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

Creative Commons License​All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.