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"
    }
  ]
}

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

API List

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

Case 2: Apportioning with two years of arrear: Example: The apportioning details for the financial year 2014-15 are given below.

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

Overview

The consumer sometimes needs additional amounts (Amendments) added to their bill due to reasons from outside of the system. The addition of amounts happens with respect to the consumer code of the entity in the product(PT, WS, etc..,), any unpaid demand in the system is a candidate for amendments.

Pre-requisites

• Prior knowledge of billing-service in the DIGIT framework.

Key Functionalities

Amendment mainly works with two types of functionality as follows:

• Amendment

• Demand

Bill Amendment provides a separate flow that triggers the workflow for validating the process of adding additional amounts to existing demands. This validation was earlier available only to the respective modules. An amendment is allowed only when there is a need to add or reduce the amount from the existing bill belonging to an entity. The reasons for such cases could be:

1. Court case settlement

2. One time waiver

3. Write-offs

4. DCB correction (old demands in paid status)

5. Property tax remission

Criteria:

Below are certain prerequisites to creating an amendment,

1. presence of demand in the billing system

2. any one of the reasons listed above

3. valid document proof for the reason

4. there is no other amendment already in the workflow

Procedure:

The process of adding an amendment in specific scenarios is given below.

There are two scenarios on how an amendment is completed based on the paid status of the existing demands in the system.

1. when demand is unpaid/partially paid

1. Create a demand (Or an existing demand can be used) with demand detail → DD1.

2. Do not pay the bill or make a partial payment.

3. Create an amendment for the same consumer code (with demand detail → DD2).

4. Approve the amendment - the response should return an amendment with the status CONSUMED.

5. Search the demand or fetch the bill for the consumer code. The demand/bill should contain demand details of the demand and amendment together with DD1 and DD2 in the same demand/bill.

2. when demand is completely paid

1. Create demand and make complete payment or choose a consumer code which is fully paid.

2. Create amendment (with demand detail → DD1).

3. Approve amendment - the response should be APPROVED.

4. Create new demand for the consumer code (with demand detail → DD3). The demand response should contain two demand details DD1 and DD2 saved to the demand.

5. The amendment search returns CONSUMED status after the demand is created.

IMPACT: Does not impact any other functionality other than adding demand details to demands on APPROVAL.

IMPACTED BY: Existence of demands in the system.

Configuration Details

Billing Service | Configuration-Details: ​Refer to billing-service config for MDMS data. The amendment makes use of the same data set.

WORKFLOW CONFIG:

{
  "RequestInfo": {
    "apiId": "Rainmaker",
    "action": "",
    "did": 1,
    "key": "",
    "msgId": "20170310130900|en_IN",
    "requesterId": "",
    "ts": 1513579888683,
    "ver": ".01",
    "authToken": "{{authToken_amritsar}}"
  },
  "BusinessServices": [
    {
      "tenantId": "pb",
      "businessService": "BS.AMENDMENT",
      "business": "BS",
      "businessServiceSla": null,
      "states": [
        {
          "tenantId": "pb",
          "sla": null,
          "state": null,
          "applicationStatus": "INWORKFLOW",
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "actions": [
            {
              "tenantId": "pb",
              "action": "OPEN",
              "nextState": "APPROVALPENDING",
              "roles": [
                "EMPLOYEE"
              ]
            }
          ]
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "APPROVALPENDING",
          "applicationStatus": "INWORKFLOW",
          "docUploadRequired": true,
          "isStartState": true,
          "isTerminateState": false,
          "actions": [
            {
              "tenantId": "pb",
              "action": "APPROVE",
              "nextState": "APPROVED",
              "roles": [
                "EMPLOYEE"
              ]
            },
            {
              "tenantId": "pb",
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "EMPLOYEE"
              ]
            }
          ]
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "REJECTED",
          "applicationStatus": "INACTIVE",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "actions": null
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "APPROVED",
          "applicationStatus": "ACTIVE",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "actions": null
        }
      ]
    }
  ]
}

Integration Details

Integration Scope

Amendment integration helps organizations add additional value to the demand without any change in the system.

Integration Benefits

• Easy to create and simple process of updating demands

• Helps ease changes into the system which are not part of normal functionality - Amendment of bills in case of legal requirements.

Steps to Integration

This is integrated into the billing system by default.

• The amendment facility can be used in case of a legal issue to add values to existing demands using /amendment/_create. The parameter /amendment/_update is used to cancel the created updates or update configured workflows.

Doc Links

API Definition

API SPEC FOR BILL-AMENDMENT

API List