Third party system to Finance Integration

Owned by Elzan Mathew
Last updated: Jul 23, 2020
4 min read

Introduction

This document details how a third party system can post a voucher to DIGIT Finance. One can push a receipt or a Journal voucher to the Finance system using the APIs. It is very normal for a state or a city to have multiple third party applications used along with DIGIT Finance. In such cases, all the revenues, demands and bills from various sources need to be accounted to the Finance system. This is possible using the voucher integration APIs.

High-Level Design

Finance system exposes a REST API to create the voucher which is authenticated. This API needs to be called after the creation of a collection receipt or bill creation. This will push a voucher in the Finance system with relevant information like - source module, the amount collected, mode of collection and so on.

Low-Level Design

Create  a voucher

For the creation of a voucher, one should call the  /rest/voucher/_create API which is referred to in the contract. One voucher is created in the Finance system in approved status for a receipt or bill that is pushed using the API. In order to make sure multiple vouchers are not created for any record, pass the reference number and billing service appropriately.

Collections can be made in - Cash, Cheque, DD, online. There are different account code configured for each of these instruments. The third-party system will have to pass the correct account code while creating a voucher. DIGIT Finance will be the source of truth for account code. This is applicable for all the masters that are required for a voucher, like- Fund, Function, Department and any other.

For Online collections, the money will be either directly debited to the bank or to a cash in transit account. Configuration needs to be done based on the state/city requirement. Back update the source system for voucher reference if required.

Search a voucher

/rest/voucher/_search APi is used to search for any voucher. One can search for a particular voucher or a list of vouchers using the available filters.

Cancel a voucher

/rest/voucher/_cancel API is used to cancel a voucher that is created from the third-party system.

Sample payload

For calling any of the voucher APIs authentication is mandatory. Use the below-mentioned API for getting the authentication token which then can be passed as "authToken" to the voucher APIs request. The values for "access_token" will be passed as the "authToken" value in the other APIs.

Access Token Generation API: https://staging.egovernments.org/user/oauth/token

Request:

{
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/x-www-form-urlencoded"
},
{
"key": "Authorization",
"value": "Basic ZWdvdi11c2VyLWNsaWVudDplZ292LXVzZXItc2VjcmV0"
}
],
"url": {
"raw": "https://staging.egovernments.org/user/oauth/token",
"protocol": "https"
},
"body": {
"mode": "urlencoded",
"urlencoded": [
{
"key": "username",
"value": "EMP2_SU",
"type": "text"
},
{
"key": "scope",
"value": "read",
"type": "text"
},
{
"key": "password",
"value": "EMPSU01234",
"type": "text"
},
{
"key": "grant_type",
"value": "password",
"type": "text"
},
{
"key": "tenantId",
"value": "pg.citya",
"type": "text"
},
{
"key": "userType",
"value": "EMPLOYEE",
"type": "text"
}
]
}
}

Response:

{
"access_token": "594caf72-808c-437f-af0c-f64976e9b831",
"token_type": "bearer",
"refresh_token": "abcd5ac2-9099-439d-9126-37b3b6e49ae0",
"expires_in": 604527,
"scope": "read",
"ResponseInfo": {
"api_id": "",
"ver": "",
"ts": "",
"res_msg_id": "",
"msg_id": "",
"status": "Access Token generated successfully"
},
"UserRequest": {
"id": 1389,
"uuid": "7e9e676f-60d1-426f-861c-0cfdd5a8a572",
"userName": "EMP2_SU",
"name": "EMP2_SU",
"mobileNumber": "1111111112",
"emailId": null,
"locale": null,
"type": "EMPLOYEE",
"roles": [
{
"name": "HRMS ADMIN",
"code": "HRMS_ADMIN",
"tenantId": "pg.citya"
},
{
"name": "BPA Services verifier",
"code": "BPA_VERIFIER",
"tenantId": "pg.citya"
},
{
"name": "Super User",
"code": "SUPERUSER",
"tenantId": "pg"
},
{
"name": "Super User",
"code": "SUPERUSER",
"tenantId": "pg.citya"
}
],
"active": true,
"tenantId": "pg.citya"
}
}

https://citya.egovernments.org/services/EGF/rest/voucher/_create

Request Body:

{
"tenantId": "pg.citya",
"RequestInfo": {
"apiId": "Mihy",
"ver": ".01",
"ts": null,
"action": "_update",
"did": "1",
"key": "",
"msgId": "20170310130900|en_IN",
"authToken": "e24a7289-14bc-4df7-9633-2843450245e2",
"correlationId": "340e8045-2c2f-4877-a038-125805a8090f",

"vouchers": [
{
"id": null,
"name": "BPA.NEWCONSTRUCTION_APP_FEE",
"type": "Receipt",
"voucherNumber": null,
"description": "BPA.NEWCONSTRUCTION_APP_FEE Receipt",
"voucherDate": "01/04/2020",
"fund": {
"id": null,
"name": null,
"code": "01",
"identifier": null,
"level": null,
"parentId": null,
"isParent": null,
"active": null
},
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"fiscalPeriod": null,
"status": null,
"originalVhId": null,
"refVhId": null,
"cgvn": null,
"moduleId": 10,
"department": "DEPT_25",
"source": "/services/collection/receipts/receipt-viewReceipts.action?selectedReceipts=c5c1f0a8-9928-45c0-9e49-00a937a80c50",
"scheme": {
"id": null,
"code": null
},
"subScheme": null,
"functionary": {
"id": null,
"code": null
},
"fundsource": null,
"ledgers": [
{
"id": null,
"orderId": null,
"glcode": "1404011",
"debitAmount": 0,
"creditAmount": 120,
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
},
{
"id": null,
"orderId": null,
"glcode": "4502001",
"debitAmount": 120,
"creditAmount": 0,
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
}
],
"tenantId": "pg.citya",
"referenceDocument": "c5c1f0a8-9928-45c0-9e49-00a937a80c34",
"serviceName": "BPA.NC_APP_FEE"
}
]
}

Response:

{
"page": null,
"Vouchers": [
{
"id": 1100,
"name": "BPA.NEWCONSTRUCTION_APP_FEE",
"type": "Receipt",
"voucherNumber": "1/BRV/00000605/04/2020-21",
"description": "BPA.NEWCONSTRUCTION_APP_FEE Receipt",
"voucherDate": "01/04/2020",
"fund": {
"id": null,
"name": null,
"code": "01",
"identifier": null,
"level": null,
"parentId": null,
"isParent": null,
"active": null
},
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"fiscalPeriod": null,
"status": null,
"originalVhId": null,
"refVhId": null,
"cgvn": null,
"moduleId": 10,
"department": "DEPT_25",
"source": "/services/collection/receipts/receipt-viewReceipts.action?selectedReceipts=c5c1f0a8-9928-45c0-9e49-00a937a80c50",
"scheme": {
"id": null,
"code": null
},
"subScheme": null,
"functionary": {
"id": null,
"code": null
},
"fundsource": null,
"ledgers": [
{
"id": null,
"orderId": null,
"glcode": "1404011",
"debitAmount": 0,
"creditAmount": 120,
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
},
{
"id": null,
"orderId": null,
"glcode": "4502001",
"debitAmount": 120,
"creditAmount": 0,
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
}
],
"tenantId": "pg.citya",
"serviceName": "BPA.NC_APP_FEE",
"referenceDocument": "c5c1f0a8-9928-45c0-9e49-00a937a80c34"
}
],
"ResponseInfo": {
"apiId": "Mihy",
"ver": ".01",
"ts": "Tue Jul 21 10:49:48 IST 2020",
"resMsgId": "20170310130900|en_IN",
"msgId": null,
"status": "201"
}
}

https://citya.egovernments.org/services/EGF/rest/voucher/_search

Request Body:
{
"tenantId": "pg.citya",
"RequestInfo": {
"apiId": "Mihy",
"ver": ".01",
"ts": null,
"action": "_search",
"did": "1",
"key": "",
"msgId": "20170310130900|en_IN",
"authToken": "25c3916c-471f-4c16-bc91-ae439ae86d26"
},
"voucherNumbers": "1/BRV/00000605/04/2020-21"
}

Response:

{
"page": null,
"Vouchers": [
{
"id": 1100,
"name": "BPA.NEWCONSTRUCTION_APP_FEE",
"type": "Receipt",
"voucherNumber": "1/BRV/00000605/04/2020-21",
"description": null,
"voucherDate": "01-04-2020",
"fund": {
"id": null,
"name": null,
"code": "01",
"identifier": null,
"level": null,
"parentId": null,
"isParent": null,
"active": null
},
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"fiscalPeriod": null,
"status": {
"id": null,
"moduleType": null,
"code": "0",
"description": null
},
"originalVhId": null,
"refVhId": null,
"cgvn": "1/MSR/CGVN0000000605",
"moduleId": 10,
"department": "DEPT_25",
"source": null,
"scheme": null,
"subScheme": null,
"functionary": null,
"fundsource": null,
"ledgers": [
{
"id": 3050,
"orderId": null,
"glcode": "4502001",
"debitAmount": 120,
"creditAmount": 0,
"function": {
"id": 188,
"name": null,
"code": null,
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
},
{
"id": 3049,
"orderId": null,
"glcode": "1404011",
"debitAmount": 0,
"creditAmount": 120,
"function": {
"id": 188,
"name": null,
"code": null,
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
}
],
"tenantId": "pg.citya",
"serviceName": "BPA.NC_APP_FEE",
"referenceDocument": "c5c1f0a8-9928-45c0-9e49-00a937a80c34"
}
],
"ResponseInfo": {
"apiId": "Mihy",
"ver": ".01",
"ts": "Wed Jul 22 10:28:27 IST 2020",
"resMsgId": "20170310130900|en_IN",
"msgId": null,
"status": "200"
}
}

https://citya.egovernments.org/services/EGF/rest/voucher/_cancel

Request Body:

{
"tenantId": "pg.citya",
"RequestInfo": {
"apiId": "Mihy",
"ver": ".01",
"ts": null,
"action": "_search",
"did": "1",
"key": "",
"msgId": "20170310130900|en_IN",
"authToken": "25c3916c-471f-4c16-bc91-ae439ae86d26"
},
"voucherNumbers": "1/BRV/00000605/04/2020-21"
}

Response:

{
"page": null,
"Vouchers": [
{
"id": 1100,
"name": "BPA.NEWCONSTRUCTION_APP_FEE",
"type": "Receipt",
"voucherNumber": "1/BRV/00000605/04/2020-21",
"description": null,
"voucherDate": "01-04-2020",
"fund": {
"id": null,
"name": null,
"code": "01",
"identifier": null,
"level": null,
"parentId": null,
"isParent": null,
"active": null
},
"function": {
"id": null,
"name": null,
"code": "909100",
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"fiscalPeriod": null,
"status": {
"id": null,
"moduleType": null,
"code": "4",
"description": null
},
"originalVhId": null,
"refVhId": null,
"cgvn": "1/MSR/CGVN0000000605",
"moduleId": 10,
"department": "DEPT_25",
"source": null,
"scheme": null,
"subScheme": null,
"functionary": null,
"fundsource": null,
"ledgers": [
{
"id": 3049,
"orderId": null,
"glcode": "1404011",
"debitAmount": 0,
"creditAmount": 120,
"function": {
"id": 188,
"name": null,
"code": null,
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
},
{
"id": 3050,
"orderId": null,
"glcode": "4502001",
"debitAmount": 120,
"creditAmount": 0,
"function": {
"id": 188,
"name": null,
"code": null,
"level": null,
"active": null,
"isParent": null,
"parentId": null
},
"subledgerDetails": []
}
],
"tenantId": "pg.citya",
"serviceName": "BPA.NC_APP_FEE",
"referenceDocument": "c5c1f0a8-9928-45c0-9e49-00a937a80c34"
}
],
"ResponseInfo": {
"apiId": "Mihy",
"ver": ".01",
"ts": "Wed Jul 22 10:32:15 IST 2020",
"resMsgId": "20170310130900|en_IN",
"msgId": null,
"status": "200"
}
}

Steps to configure

  • Make sure all the common masters that are used for voucher creation are in sync with the two systems.
  • If a city has a specific bank account to which the money needs to be accounted for online collection, configure the bank account in DIGIT Finance as well as in third-party application with the account code kept same.
  • Write a kafka consumer to post the voucher to DIGIT Finance when collection happens. Keeping the two asynchronous is better. 
  • Create a new role for "Finance System Integrator" in DIGIT Finance.
  • Create a new user with type as "SYSTEM" and role as "Finance System Integrator".
  • Share the user credentials to the third-party system for them to pass it as part of the authentication key.
  • You can create a voucher using the superuser credentials. Staging server credentials are- Username- EMP2_SU, Password- EMPSU01234, City- City A