What is a collection?

A collection is a process of issuing a receipt for every payment done on the egov platform. The scope of collections is to issue and store receipts only.
There's provision to update a few details of the receipt which do not affect the authenticity of the transaction.

Why is it needed?

The receipt is an acknowledgement of the payment. The user needs an interface/provision to pay his bills and obtain acknowledgement for the same,
collections does one part of it which is issuing and managing the receipts of such payments.

What is a receipt?

The receipt is an acknowledgement of the payment. Receipts are generated using the bill that is being paid,
these bills are validated for different business rules before the receipts are generated.

What is demand?

Demand is the details of monetary expectations if applicable against any transaction on the platform.
For instance, the amount to be paid upon applying for trade license, applying for water connection etc in which case transaction is the application.
In some cases, assessment can be considered as a transaction therefore, amount to be paid on assessing a property etc.

What is bill?

Bill is the snapshot of demand at any given point of time. Bill is the artefact used for paying.
Demand can be thought of as the ledger and Bill as its snapshot used to pay. Multiple bills can be generated for the same demand.

What is the relation between Demand, Bill and Receipt?

Bill is generated for a demand, when this bill is paid, a receipt is issued for this payment. A bill can be paid partially or in full based on whether part payment is allowed for the bill.
When partial payments happen, for every payment until the full amount is paid, one receipt is generated.
However, when a bill is partially paid the demand attached to the bill is updated and during the next time, a new bill is generated for the partially paid demand.
Bill won't be generated for a demand that is already paid therefore, receipts are only for non-zero bills.

Importantly, in terms of entities, a demand is mapped to billDetail and demandDetails within the demand are mapped to billAccountDetails within the billDetail. A list of billDetail forms a Bill entity. Although this belongs to the billing-service, this understanding of the structure is crucial to understand the operations in collections-service.

What are Tax heads and what is tax amount and paid amount?

Tax Heads are categories under which payments are done. For instance, payment of property tax is done under PT_TAX tax-head, a rebate on the amount is applied under REBATE tax-head. A group of multiple tax-heads culminate into one demand. Amount to be paid under every tax-head are recorded within Demand details and a demand contains one or more such demand detail entries.

Tax Amount is the amount to be paid for this demand which means when the bill is generated this amount will be the bill amount.

Paid amount is the amount paid for the bill, which can be less than or equal to the bill amount based on the part payment allowance.

What is an Instrument?

An instrument is the means of payment. Payment can be done offline or online, in both cases, there are various means of payment. For instance, DD or a Challan can be used for offline payment similarly Credit Card or Net banking can be used for online payment. All of these are termed as an instrument on the platform and always carry the transaction id along with them.

Basic Flow with Validations and Constraints:

In order to create a receipt, we send a list of bills to the collection service which has exposed APIs for creating, updating and searching receipts, the details of these APIs is provided in the doc later. Currently, collections take only one bill that contains multiple billDetails and each billDetail containing a list of billAccountDetails. Collection-Services creates one receipt for every billDetail present in the bill.

Flow -

Semantic Validations on the bill:

Bill contains various fields as defined by billing-service contract, these fields along with a few collections-service specific fields is sent to the create API which checks if these fields are semantically correct before proceeding to the business logic.

Business validations on the bill:

The billId is fetched from the bill sent in the request, a search call is made to billing-service to fetch bill on this billId. This is done in order to ensure that any changes to the bill if done while passing it to the API are all overridden by actual values available in the system. The fields within the bill belonging to the billing-service are all validated by the billing-service and hence we do not validate those.

In the new billing-service an array of taxAmount for every business service present in the bill is sent.
When the bill is being paid, amountPaid is added to the same array this array if termed as 'taxAndPayments' which is used by the apportioning service to apportion the paid amount. Validations on that array as follows:

If part payment is allowed, amountPaid can be less than or equal to taxAmount.
If the part payment is not allowed, amountPaid should be equal to taxAmount.
Other sanity checks like if the businessservices sent in the request are valid etc.
Also, enriches the validatedBill with the amountPaid value from the request.

Validation is done on fields of receipt and bill object that are pertaining to collections-service as follows:

- Instrument type provided is valid

- Amount Paid & total amount are not null and are integer values, no fractions allowed!

- Allow zero amount ONLY IF the total bill amount is also equal to zero

- Sum of the amount paid on all bill details should be equal to the instrument amount

- The bill is not being repaid, if a receipt is already created and is in completed / pending state do not allow the creation of another receipt.

- Business service code provided is valid, call is being made in a loop as the tenant id could be different for each bill detail

- Bill account details are valid, checks for purpose and GL Codes

- Cheque and DD dates are correct

Enrichment:

Once all the validations have passed, the bill object from billing service needs to be enriched with the fields of the bill sent in the request and the enrichment happens as follows:

- Set payer details

- Set manual receipt number, collectionType and receiptType.

- Set AuditDetails for the record.

- Set status to approved by default for now, no workflow

- Set collection type to online or counter

- Set receipt date

- Generate and set receipt number

Apportion:

Bill apportioning is the concept of distributing the paid amount amongst all the billAccountDetails entries inside the billDetail. Remember, the receipt is generated for every billDetail entry within the bill. Now, why is it needed? As already discussed, we have the provision of partial payment under which a bill can be partially paid. Now we know that a bill contains billDetail and that billDetail is in one way a sum of multiple billAccountDetail. Let's say we have to generate a receipt for a payment of INR 100 which is the sum of INR 20 PT_TAX, INR 50 WC_TAX and 30 TL_TAX. If part payment is allowed, then the payer can pay only INR 20 for this bill instead of INR 100, in such a case, apportion comes into play and adjusts this INR 20 amongst the 3 billAccountDetail entries as mentioned above. This adjustment of partial payment is done based on order or priority that is attached to every tax-head and this order is configurable in the system. Once this adjustment is done the underlying demand of the bill is updated and when the same is being paid next time, the updated bill is generated.

This is a crucial part of the collections-service functionality. Although this apportioning task is owned by a separate service, collections will still need this task to be completed before issuing the receipt.

So, with the validated enriched bill collections-service makes an apportion API call to the Apportioning service and gets the bill apportioned.

Persistence:

This bill that is validated, enriched and apportioned (if applicable) is then persisted into the database. The receipt is now generated and is persisted into 2 tables namely - egcl_receiptheader and egcl_receiptdetails. The instrument is stored in a table named - egcl_instrumentheader. However, the structure of the tables and the entity that is persisted into these tables are different, we use the same bill object with a wrapper of receipt and persist into the tables mentioned above. When a bill is searched, it is returned by combining data from these tables. Link to files is provided in the Docs section to understand the structure of tables.

Use Cases/Features:

Create Receipt -

The process of issuing a receipt on payment of the bill.

Update Receipt -

Usually updating of a receipt is not allowed. However, few fields that dont essentially alter the authenticity of the receipt are open for update in collections-service. This feature provides ways for updating such fields.

Search Receipt -

The process of searching the receipts available in the system.

Workflow -

Workflow is a step-by-step process of any transaction. A receipt goes through following states - To be Submitted, Approval Pending, Approved, Rejected, Cancelled, Remitted, Dishonoured. All these states or say statuses of a receipt are the result of a set of actions on the receipt. The process of defining the predecessor states, successor states and the set of actions that cause this change is workflow of receipt. Every action on the receipt passes through the API which facilitates the workflow.

Remittance -

Once the collection is done, the amount paid by the user has to be deposited to the bank account owned by the govt, this process of depositing the amount is termed as remittance. This also means that once the receipt is generated, the money is not actually deposited and only when the remittance is successful, the payment is complete. However, remittance is considered to be a background task and receipt generation is not affected by remittance. However, once the remittance is done, the receipt is updated to move to the 'Remitted' state and the instrument to 'Deposited' state.

Dishonour -

The process of marking an instrument and thereby the attached receipt as invalid due to failed remittance. For instance, the payment is done through Cheque, the receipt is generated for the payment while attempting to deposit this payment, the cheque bounces and the remittance is failed so we mark the instrument and the receipt as 'Dishonored' or in simple terms invalid.

Web Sequence Diagram of the flow:

A sequence diagram in the Unified Modeling Language (UML) is an interaction diagram that shows how processes operate with one another and in what order. UML sequence diagrams model the flow of logic within your system in a visual manner, enabling you both to document and validate your logic, and are commonly used for both analysis and design purposes. Sequence diagrams are the most popular UML artifact for dynamic modeling, which focuses on identifying the behavior within your system.

//Attach the WSD of Collection-Services.

Use-cases belonging to Revenue Modules.

Property Tax -

When a property is created, a demand is created along with it in the demand system. When assessments happen on these properties, based on the changes in the property, demand is updated and consequently, bill is generated which is paid using collection-service and pg-service.

Trade License -

Demand is generated when the application for Trade License is initiated. During the payment, the same demand is used to generate the bill and is paid using collection-service and pg-service.

Docs:

API Doc Billing Service - https://raw.githubusercontent.com/egovernments/egov-services/master/docs/billingservice/contracts/v1-1.yml

API Doc Collections-Service - https://raw.githubusercontent.com/egovernments/egov-services/feature-collections/docs/collections/contracts/collections-receipt/v1-0-1.yml

API Doc Apportioning-Service - https://raw.githubusercontent.com/egovernments/egov-services/APPORTION_SERVICE/docs/collections/contracts/apportion/egov-apportion-service.yml

DB Scripts to understand the DB Structure - https://github.com/egovernments/egov-services/tree/master/collections/collection-services/src/main/resources/db/migration/main

CHANGELOG.md - https://github.com/egovernments/egov-services/blob/master/collections/collection-services/CHANGELOG.md

Browser not supported