Collection Service V2

Objective:

 

The objective of Collection service is to serve as revenue collection platform for all the billing systems through cash, cheque, dd, swipe machine. To provide a receipt for every payment done on the egov platform

Requirements:

  • Prior Knowledge of Java/J2EE

  • Prior Knowledge of SpringBoot

  • Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON etc

  • Prior Knowledge of Kafka and related concepts like Producer, Consumer, Topic etc.

Setup:

 

Step 1: Start the ID-Gen service present in the following repo: https://github.com/egovernments/core-services/tree/master/egov-idgen Or port forward the ID-Gen service. This service is used to generate ID for some fields.

Step 2: Start the egov-common-masters service present in the following repo: https://github.com/egovernments/core-services/tree/master/egov-common-masters Or port forward the egov-common-masters-service. This service is used for business Details.

Step 3: Start the egf-instrument service present in the following repo: https://github.com/egovernments/business-services/tree/master/egf-instrument Or port forward the egf-instrument service.This service is used to get details of payment mode.

Step 4: Start the egov-apportion service present in the following repo: https://github.com/egovernments/business-services/tree/master/egov-apportion-service Or port forward the egov-apportion service. 

Step 5: Start the billing-service present in the following repo: https://github.com/egovernments/business-services/tree/master/billing-service Or port forward the billing-service.

Step 6: Start the egov-mdms service present in the following repo: https://github.com/egovernments/core-services/tree/master/egov-mdms-service Or port forward the egov-mdms service.

 

Configurable Properties:

 Following are the properties in application.properties file in collection service which are configurable.

Property

Value

Remarks

collection.receipts.search.paginate



true/false

By setting this property true, show you the search result of receipt in a bucket(page) which contains a certain number of records.

collection.receipts.search.default.size



Certain number (say 30)

Give the 30 records at a time and next 30 results are in the next page.

collection.is.user.create.enabled



true/false

By setting this property true, enabling the creation of user with receipt creation

receiptnumber.idname



receipt.id



This property is used for creation of receipt number using ID-GEN service

receiptnumber.servicebased

true/false

If servicebased is set to false, use default state level format for the format of receipt number and if it is set to true the format for the receipt number has to be mentioned in MDMS

receiptnumber.state.level.format



[cy:MM]/[fy:yyyy-yy]/[SEQ_COLL_RCPT_NUM]

Default state level format for the receipt number.

collection.payments.search.paginate



true/false

By setting this property true, show you the search result of payment records in a bucket(page) which contains a certain number of records.

kafka.topics.payment.create.name



egov.collection.payment-create



The kafka topic on which the record has to push/pull when payment is created.

kafka.topics.payment.cancel.name

egov.collection.payment-cancel



The kafka topic on which the record has to push/pull when payment is cancelled.

kafka.topics.payment.update.name

egov.collection.payment-update



The kafka topic on which the record has to push/pull when payment is updated.

 

API Calls:

_search:

This API search payments based on search parameters like consumerCode, mobileNumber, transactionNumber etc.

  • Endpoint

/collection-services/payments/{modulename}/_search?tenantId={tenantId}&consumerCode={consumercode}&businessService={businessService}

  • Body

The request body will have requestInfo.

{ "RequestInfo": { "apiId": "emp", "ver": "1.0", "ts": 1558889531536, "action": "create", "did": "1", "key": "abcdkey", "msgId": "20170310130900", "requesterId": "", "authToken": "c94fad3f-8691-489d-8838-25b2bfc714fd" } }

 

  • URL instance

_create: 

This API create the payment for list of bill with a transaction number and persists the payment details. The payment information is then pushed to queue for further processing.

  • Endpoint

/collection-services/payments/_create

  • Body

The request body will have request info and the payment object with proper payment details. Bill, Bill details and Bill account details object.

{ "requestInfo": { "apiId": "string", "ver": "string", "ts": 0, "action": "string", "did": "string", "key": "string", "msgId": "string", "requesterId": "string", "authToken": "string" }, "Payment": { "tenantId": "string", "id": "string", "totalDue": 0, "totalAmountPaid": 0, "transactionNumber": "string", "transactionDate": 0, "paymentMode": "CASH", "instrumentDate": 0, "instrumentNumber": "string", "instrumentStatus": "APPROVED", "ifscCode": "string", "additionalDetails": {}, "paymentDetails": [ { "id": "string", "tenantId": "string", "totalDue": 0, "totalAmountPaid": 0, "manualReceiptNumber": "string", "receiptNumber": "string", "receiptType": "string", "receiptDate": 0, "businessService": "string", "billId": "string", "bill": { "paidBy": "string", "mobileNumber": "string", "payerName": "string", "payerAddress": "string", "payerEmail": "string", "payerId": "string", "status": "ACTIVE", "reasonForCancellation": "string", "isCancelled": true, "additionalDetails": {}, "collectionModesNotAllowed": [ "string" ], "partPaymentAllowed": true, "isAdvanceAllowed": true, "minimumAmountToBePaid": 0, "businessService": "string", "totalAmount": 0, "consumerCode": "string", "billNumber": "string", "billDate": 0, "billDetails": [ { "id": "string", "tenantId": "string", "demandId": "string", "billId": "string", "amount": 0, "amountPaid": 0, "fromPeriod": 0, "toPeriod": 0, "receiptDate": "2019-12-27", "receiptType": [ "ADHOC" ], "channel": "string", "boundary": [ "string" ], "manualReceiptNumber": "string", "manualReceiptDate": 0, "collectionType": "string", "billDescription": "string", "expiryDate": 0, "displayMessage": "string", "cancellationRemarks": "string", "billAccountDetails": [ { "id": "string", "tenantId": "string", "billDetailId": "string", "demandDetailId": "string", "order": 0, "amount": 0, "adjustedAmount": 0, "taxHeadCode": "string", "additionalDetails": {}, "purpose": "ARREAR" } ] } ] }, "additionalDetails": 0 } ], "paidBy": "string", "mobileNumber": "string", "payerName": "string", "payerAddress": "string", "payerEmail": "string", "payerId": "string", "paymentStatus": "NEW" } }

 

  • URL Instance

https://egov-micro-dev.egovernments.org/collection-services/payments/_create

 

_validate:

 This API is generally called during the creation of payment object. This API run the following set of validation on the payment request.

  1. Bill is present and is in valid state.

  2. Amount paid is positive integer.

  3. Zero amount payment is allowed only if bill amount is zero.

  4. Payment mode is allowed.

  5. Partial Payment is allowed based on the businessService.

  6. Advance payment is allowed based on the businessService.

 

  • Endpoint

/collection-services/payments/_validate

  • Body

The request body will have the payment request which has to be validated. The object have request info and the payment object with payment details. Bill, Bill details and Bill account details object.

{ "requestInfo": { "apiId": "string", "ver": "string", "ts": 0, "action": "string", "did": "string", "key": "string", "msgId": "string", "requesterId": "string", "authToken": "string" }, "Payment": { "tenantId": "string", "id": "string", "totalDue": 0, "totalAmountPaid": 0, "transactionNumber": "string", "transactionDate": 0, "paymentMode": "CASH", "instrumentDate": 0, "instrumentNumber": "string", "instrumentStatus": "APPROVED", "ifscCode": "string", "additionalDetails": {}, "paymentDetails": [ { "id": "string", "tenantId": "string", "totalDue": 0, "totalAmountPaid": 0, "manualReceiptNumber": "string", "receiptNumber": "string", "receiptType": "string", "receiptDate": 0, "businessService": "string", "billId": "string", "bill": { "paidBy": "string", "mobileNumber": "string", "payerName": "string", "payerAddress": "string", "payerEmail": "string", "payerId": "string", "status": "ACTIVE", "reasonForCancellation": "string", "isCancelled": true, "additionalDetails": {}, "collectionModesNotAllowed": [ "string" ], "partPaymentAllowed": true, "isAdvanceAllowed": true, "minimumAmountToBePaid": 0, "businessService": "string", "totalAmount": 0, "consumerCode": "string", "billNumber": "string", "billDate": 0, "billDetails": [ { "id": "string", "tenantId": "string", "demandId": "string", "billId": "string", "amount": 0, "amountPaid": 0, "fromPeriod": 0, "toPeriod": 0, "receiptDate": "2019-12-27", "receiptType": [ "ADHOC" ], "channel": "string", "boundary": [ "string" ], "manualReceiptNumber": "string", "manualReceiptDate": 0, "collectionType": "string", "billDescription": "string", "expiryDate": 0, "displayMessage": "string", "cancellationRemarks": "string", "billAccountDetails": [ { "id": "string", "tenantId": "string", "billDetailId": "string", "demandDetailId": "string", "order": 0, "amount": 0, "adjustedAmount": 0, "taxHeadCode": "string", "additionalDetails": {}, "purpose": "ARREAR" } ] } ] }, "additionalDetails": 0 } ], "paidBy": "string", "mobileNumber": "string", "payerName": "string", "payerAddress": "string", "payerEmail": "string", "payerId": "string", "paymentStatus": "NEW" } }

 

  • URL Instance

_workflow:

This API call perform the following operation:

  1. Cancellation of receipts in open state.

  2. Remittance of instruments such as Cash, Cheque and DD .

  3. Dishonouring of instruments such as Cheque and DD.

 

  • Endpoint

/collection-services/payments/_workflow

  • Body

The request body will have request info and the payment object with the following fields:

  1. paymentId : The Id of payment on which the workflow operation has to perform.

  2. action : The action to be perform on the payment object.

  3. tenantId : Unique Id of the tenant.

  4. reason : Reason for the action to be perform on  payment object.

  5. additional Details : Mentioned the additional detail for the workflow operation.

 

  • URL Instance

_update:

This API is called to update the payment information, then the payment information is pushed for further processing.

  • Endpoint

/collection-services/payments/_update

  • Body

The request body will have request info and the updated payment object with proper payment details,Bill, Bill details and Bill account details object.

 

  • URL Instance:

Object description

Field in Payment Object

Description

Payments.Id 

Unique Id assign to Payment object

Payments.tenantId

Id of tenant

Payments.totalDue

The total amount which is remaining to be paid by citizen

Payments.totalAmountPaid

The total amount which was already paid by citizen

Payments.transactionNumber

Payment Transaction Number

Payments.transactionDate

Date on which transaction is done

Payments.paymentMode

Mode of payment (DD/Cash/Cheque/Swipe Machine)

Payments.instrumentDate

The date on which payment is done through the payment means(mode)

Payments.instrumentNumber

The number of instrument which is used for payment

Payments.instrumentStatus

The status of instrument which is used for payment

Payments.ifscCode

IFSC code for payment transaction

Payments.additionalDetails

Payment Additional details like created by and time, last modified by and time

Payments.paidBy

Name of the person who made the payment

Payments.mobileNumber

Payer Mobile number

Payments.payerName

Name of the owner for whom payment is created

Payments.payerAddress

Address of the owner

Payments.payerEmail

Email of the owner

Payments.payerId

ID of the owner

Payments.paymentStatus

Based on paymentMode from Payment, the paymentStatus is set.

If paymentMode is ONLINE or CARD then  paymentStatus is set to DEPOSITED otherwise it is set to NEW

Payments.auditDetails.createdBy

Payment audit details like created by and time, last modified by and time

Payments.paymentDetails.Id 

Unique Id assigned to each payment details. A single payment object can have multiple payment details 

Payments.paymentDetails.tenantId

Id of tenant

Payments.paymentDetails.totalDue

For a particular bill, the total amount which is remaining to be paid by citizen

Payments.paymentDetails.totalAmountPaid

For a particular bill, the total amount which was already paid by citizen

Payments.paymentDetails.receiptNumber

The receipt number for particular payment details or payment of bill

Payments.paymentDetails.manualReceiptNumber

The manual receipt number applicable for the receipt

Payments.paymentDetails.manualReceiptDate

The manual receipt date applicable for the receipt

Payments.paymentDetails.receiptDate

The date on which receipt is generated

Payments.paymentDetails.receiptType

The type of receipt like BILLBASED

Payments.paymentDetails.businessService

Indicate for which business service this payment is?

Business service like PT, TL etc

Payments.paymentDetails.additionalDetail

Additional details like created by and time, last modified by and time

Payments.paymentDetails.auditDetail

Audit details like created by and time, last modified by and time

Payments.paymentDetails.billId

Id of the bill for the particular payment.

Payments.paymentDetails.bill

The bill object for particular bill id.

This bill object is obtained from billing service.

 

Collection Migration from V1 to V2

 

Please refer this document Collection Migration V1 to V2 for the details about migration of Collection V1 to Collection V2.