Integration Document - Billing and Collection for W & S
Integration Document - Billing & Collection Services with DIGIT for Water And Sewage
Document Name | Integration Document - Billing & Collection Services with DIGIT for Water And Sewage | Version Revision | .05 | ||
Authorized By | Rupam Baruah | Date | 15-May-2019 | ||
Version History | |||||
Overview
DIGIT is India's largest open source platform for Urban Governance. It provides API based access to governance functions enabling Urban Local Bodies (ULBs) provide citizen facilities via integration with relevant service players.
Purpose
This document aims to provide information on how to integrate third-party Billing and Collection services with the DIGIT governance platform.It enables system integrators to get the system to fetch bills due, record payments and generate receipts for the amount paid. However,this document does not include information about any third-party system, DIGIT configuration outside the stated scope, installation or deployment of either the third-party software or DIGIT.
Intended Audience
System Integrators (SI)
Prerequisites
Knowledge of REST API usage
Knowledge of JSON
Process Flow
Above diagram depicts the high-level flow of calls between On-Field devices like PoS machines to the backend of the Integrator System and the backend of the Integrator System to the DIGIT Platform.
Integration with DIGIT is a server to server integration, where the integrator’s backend system makes calls to the DIGIT platform as per the need. This is because the SI in-field team already makes these calls to their own system (or a standard system like BBPS)
Flow Steps
A bill collection flow consists of the following steps:
Know consumer dues
Creating the Payment Record in DIGIT
Fetching the Payment Receipt (optional)
Finding the status of a transaction for which response not received during posting
The task is completed by making the required API calls.
Assumptions for APIs
The fields marked with a (*) are mandatory
The values in the sample requests are indicative. They need to be modified with actual values according to specific environments
The values in the sample response are indicative. Actual values will differ as per specific environments
The hostname in the URL will differ for specific environments. In the below sample requests, the hostname pertains to DIGIT development server
All the requests are secured with auth token, hence request header should have an auth token details ( see details in the sample requests for each API)
The ulbCodes and credentials given in the document are only indicative. Please get in touch with a concerned person to get the test instances details and credentials for the integration.
System Integrators needs to ignore any extra attributes that may come with the request/response body. System Integrators application should not expect extra fields to be present in the future. It will ensure System Integrators application doesn't break when DIGIT introduces new fields or removes extra fields.
Common Error codes and message across APIs
Error Codes | Error Messages |
|---|---|
AUTH0001 | Invalid access token |
AUTH0002 | Invalid ULB code |
WSP0001 | Invalid Consumer code |
WSP0002 | Invalid Service |
Getting the Authentication Token API
Overview
To ensure data privacy and security, transactional APIs in DIGIT are protected by an authentication mechanism. System integrators need to contact the respective state authority to get the necessary authentication tokens that can be used to access these APIs.
Note: Apart from a user ID and password, the system may enforce IP based access control. If that is the case, the SI may be required to share the IP address of the machine or a range of IP addresses from which the request will originate.
Possible Error Codes and Messages
The error codes covered in common errors
Procedure
Make a REST API call to restapi/oauth/token
Request Parameters
Request Parameter | Description | Purpose | Sample Value |
|---|---|---|---|
grant_type* | The type of permission sought | Used to identify the type of authentication sought by the user | password |
username* | The name of the user | Used to identify the user making the request | restapi_test |
password* | The user’s password | Used to check the authenticity of the user making the request | 12345678 |
ulbCode* | The code of the tenant for which permissions are sought, this will be a request param | Used to identify the tenant | 2113 |
Sample Request
Response Parameters
Response Parameter | Description | Purpose | Sample Value |
|---|---|---|---|
access_token | The token to be used to access the API | Used to authenticate the API request sent by the user | 109c2eda-a11c-48d8-bfb0-b797475d79ea |
token_type | The type of token generated | Used to check the type of security access provided to the requestor | Bearer |
refresh_token | The token to be used for renewed access to the API | Used to renew access to the requested API | b40310f1-eb0f-418a-8a28-c9f416b0017b |
Sample Response
Know Consumer Dues API
Overview
DIGIT allows integrators to get citizen’s dues using the consumer number of the Water or Sewerage service.
Possible Error Codes and Messages
The error codes covered in common errors
Procedure
Use the post API /restapi/watersewerage/dues
Request Parameters
Request Parameter | Description | Purpose | Sample Value | Data Type | Min/Max Length |
|---|---|---|---|---|---|
ulbCode * | The ID of the tenant. A four-digit code | To identify the ULB for which the call is being made | 2113 | String | 4/4 |
service * | The service Water or Sewerage | To identify the service Water or Sewerage | WATERCHARGES or SEWERAGECHARGES | String | 2/32 |
consumerCode * | The Consumer number of the Water or Sewerage connection | To identify the consumer being billed for the service | 2113002088 | String | 3/50 |
Sample Request
Response Parameters
Response Parameter | Description | Purpose | Sample Value | Data Type | Min/Max Length |
|---|---|---|---|---|---|
Consumer Details | |||||
consumerCode | The consumer’s code for the service | Used to identify the specific consumer of the citizen service. | 2113002088 | String | 3/50 |
oldConsumerNumber | The old consumer’s reference for the service | Used to identify the connection in case of legacy data. | 6474 | String | 50 |
ownerName | Name of the consumer | Used to identify the name of the consumer | Naib Singh | String | 3/100 |
guardianName | Name of the guardian (father/mother/other) | Used to identify the guardian of the consumer | Subha Singh | String | 3/100 |
mobileNumber | The contact number of the consumer | Used to communicate the consumer via SMS | 9999999999 | String | 10/10 |
emailAddress | Email of the consumer | Used to communicate the consumer via email | test@egov.org | String | 3/128 |
address | Address of the consumer | Used to communicate consumer | 303, Indiranagar, Bangalore - 560038 | String | 3/512 |
locality | The locality where the consumer resides | Used to identify the locality of the consumer | Locality one | String | 3/512 |
connectionType | Type of connection, valid only for Water | Used to identify the type of connection | Metered | String | 3/50 |
usageType | Usage type of connection | Used to identify the connection usage | Domestic | String | 3/50 |
propertyID | Property id of the connection is given | Used to identify the property id for which connection is given | PID-001 | String | 3/50 |
propertyType | Type of a property for which the connection is given | Used to identify the type of a property for which the connection is given | Residential | String | 50 |
billingType | The type of billing to charge for a connection | Used to identify the type of billing to charge a connection. The charge calculation rules depend on the billing type. | STANDARD | String | 50 |
waterSource | The type of water source for water connection to citizen | To identify the source of water for water connection. It's valid only for the Service ‘WATERCHARGES’ | Ground Water | String | 100 |
ulbName | Name of the city in which consumer number is present | To Print on the receipt and giving information to the customer | Sunam-DEV Municipal Council | String | 100 |
ulbCode | City code against which consumer number is present | To identify the city code against which transaction was done | 2113 | String | 4/4 |
service | Service against which the API is requested | To identify whether water or sewerage charges service. | WATERCHARGES | String | 50 |
category | The category of a citizen who is owning a connection. | To identify the category of the citizen who is owning a connection. It's valid only for the Service ‘WATERCHARGES’ | BPL | String | 50 |
Change Due Details | |||||
totalChargesDue | The total due amount for connection | Used to identify the dues of the connection | 10946 | BigDecimal | 12,2 |
currentCharges | The current billing cycle charges | Used to identify the current billing cycle charges | 300 | BigDecimal | 12,2 |
currentPenalty | The current billing cycle penalty | Used to identify the current billing cycle penalty | 30 | BigDecimal | 12,2 |
currentInterest | The current billing cycle interest | Used to identify the current billing cycle interest | 15 | BigDecimal | 12,2 |
arrearCharges | The total arrear charges | Used to identify the total arrear charges | 740 | BigDecimal | 12,2 |