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.
API Calls:
_search:
This API search payments based on search parameters like consumerCode, mobileNumber, transactionNumber etc.
Endpoint
/collection-services/payments/_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
https://egov-micro-dev.egovernments.org/collection-services/payments/_se
arch?tenantId=pb.amritsar&consumerCode=PB-TL-2019-12-19-003737&bus
_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.
Bill is present and is in valid state.
Amount paid is positive integer.
Zero amount payment is allowed only if bill amount is zero.
Payment mode is allowed.
Partial Payment is allowed based on the businessService.
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
https://egov-micro-dev.egovernments.org/collection-services/payments/_validate
_workflow:
This API call perform the following operation:
Cancellation of receipts in open state.
Remittance of instruments such as Cash, Cheque and DD .
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:
paymentId : The Id of payment on which the workflow operation has to perform.
action : The action to be perform on the payment object.
tenantId : Unique Id of the tenant.
reason : Reason for the action to be perform on payment object.
additional Details : Mentioned the additional detail for the workflow operation.
{
"requestInfo": {
"apiId": "string",
"ver": "string",
"ts": 0,
"action": "string",
"did": "string",
"key": "string",
"msgId": "string",
"requesterId": "string",
"authToken": "string"
},
"Payment": {
"paymentId": "string",
"action": "CANCEL",
"tenantId": "string",
"reason": "string",
"additionalDetails": 0
}
}
URL Instance
https://egov-micro-dev.egovernments.org/collection-services/payments/_workflow
_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.
{
"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/_update
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.