Integration Document - Billing and Collection for W & S
- Rupam Baruah (Unlicensed)
- Elzan Mathew
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 | |||||
Table Of Contents |
|---|
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 |
arrearPenalty | The total arrear penalty | Used to identify the total arrear penalty | 85 | BigDecimal | 12,2 |
arrearInterest | The total arrear interest | Used to identify the total arrear interest | 44 | BigDecimal | 12,2 |
minimumAmountPayable | The minimum amount payable | Used to know the minimum amount to be accepted for collection | 1 | BigDecimal | 12,2 |
maximumAmountPayable | The maximum amount payable | Used to know the maximum amount to be accepted for collection | 100 | BigDecimal | 12,2 |
billDate | The date of the latest bill | Used to get the date for the latest bill generated for the consumer | 25/07/2018 | String | 10 |
billDueDate | The due date of the bill | Due date of the latest bill after which penalty will be applied | 25/07/2018 | String | 10 |
billNumber | The Bill Number | Bill number of the latest bill generated for the consumer | 21130107910001 | String | 10/15 |
Sample Response
Creating the Payment Record in DIGIT API
Overview
After the DIGIT system gives the dues, the system integrator is expected to send it to the field device. The integrator is expected to initiate and collect the charges with citizen’s preferred payment instrument, etc. Once the payment is successful, the integrator is expected to register the payment in DIGIT using the pay charges API.
Note: Pay charges API accepts partial payment minimum of Rs. 1/- and advance payments which are more the due amount and up to 40 times of current billing cycle charges. The ‘paymentMode’ is ‘ONLINE’ for third-party integrators like Paytm, Airtel, Freecharge, etc. as in this type of payments, the payment will be directly received by respective integrators only.
Possible Error Codes and Messages
Error Codes | Error Message |
|---|---|
WSP0003 | The given transaction id is already used for another transaction |
WSP0004 | Advance payment has crossed the permissible limit |
WSP0005 | Could not process the payment at this moment, Please try after some time |
WSP0018 | Receipt date format should be DD-MM-YYYY |
WSP0019 | Receipt date should not be a future date |
Procedure
Use the API /restapi/watersewerage/paycharges.
Request Parameters
Request Parameter | Description | Purpose | Sample Value | Data Type | Min/Max length |
|---|---|---|---|---|---|
consumerCode * | The Consumer number of connection for which payment requested | Used to ensure that the payment is marked against the appropriate consumer | 2113008037 | String | 3/50 |
UlbCode * | The code of the tenant. A four digit code. | Used to ensure that the payment is marked in the appropriate ULB | 2113 | String | 4/4 |
PaymentAmount * | The payment amount of the transaction against the consumer | Used to identify the payment amount. | 2500 | BigDecimal | 12,2 |
PaymentMode * | The mode by which the payment is received. Allowed values are CASH, CHEQUE, DD, ONLINE, CARD, etc. | Used to check the total amount of the transaction | ONLINE | String | 2/50 |
chqddNo | The cheque/dd no in case ‘paymentMode’ is CHEQUE or DD | Used to identify the instrument details in case ‘paymentMode’ is CHEQUE or DD | 782372 | String | 6/6 |
chqddDate | The cheque/dd date in case ‘paymentMode’ is CHEQUE or DD | Used to identify the instrument details in case ‘paymentMode’ is CHEQUE or DD | 10-11-2018 (Date should be in DD-MM-YYYY format) | String | 10/10 |
bankName | The cheque/dd issued bank in case ‘paymentMode’ is CHEQUE or DD | Used to identify the instrument details in case ‘paymentMode’ is CHEQUE or DD | UTIB (This should be code), Please get the supporting banks list from State authority | String | 3/50 |
paidBy * | The payer name. | Used to identify the payer of the payment | eGov | String | 3/100 |
transactionId * | The transaction ref. no of the system integrator | Used to uniquely identify the transaction by system integrator | TEST-TRANS-132 | String | 3/50 |
service * | The service Water or Sewerage | To identify the service Water or Sewerage | WATERCHARGES or SEWERAGECHARGES | String | 2/32 |
deviceId | The device reference ID | Used in case integrators use POS machines on the field for collections | POS-MACHINE-01 | String | 100 |
miscText1 | Any additional information from integrator | Any additional information from integrator will be stored and will be given back in response | Additional Info | String | 100 |
miscText2 | Any additional information from integrator | Any additional information from integrator will be stored and will be given back in response | Additional Info | String | 100 |
receiptDate | Actual payment date made by the customer | Used for retrying to post failed transaction | 12-02-2019 | String | 10/10 |
transactionNumber | Transaction number from the POS machine (used in case of card payment only) | Used to send the transaction number generated by the POS machine for card payments | 1234ABCD | String | 1/20 |
instrumentNumber | Instrument number in case of card payment | Send the last 4 digits of card number used for making the transaction | 2987 | String | 1/4 |
Sample Request
Response Parameters
Response Parameter | Description | Purpose | Sample | Data Type | Min/Max Length |
|---|---|---|---|---|---|
| Receipt Details | |||||
receipt number | Payment receipt identification number | Used to identify the payment acknowledgment. | 10/2018-19/279 | String | 3/50 |
receiptDate | Payment receipt date | Used to identify the payment acknowledgment date | 22/10/2018 (format : dd/MM/yyyy) | String | 10/10 |
totalAmountpaid | Amount paid with this receipt | Used to identify the payment amount. | 3195 | BigDecimal | 12,2 |
consumer number | The Consumer number of the Water or Sewerage connection | To identify the consumer paid for the service | 9999004280 | String | 3/50 |
| Receipt account head wise details | |||||
accountHead | The account head in which the collected amount deposited | To identify against which account head the payment is done | Water Charges - 2018-2019-Q2 (Jul to Sept) | String | 3/128 |
paidAmount | The paid amount | The paid amount | 200 | BigDecimal | 12,2 |
| Instrument details | |||||
type | Type of the instrument | To identify payment mode | CASH | String | 2/50 |
InstrumentNumber | Number of the instrument used for the transaction | To identify the card number used for the transaction | 1234 | String | 1/20 |
TransactionNumber | Transaction number generated by the POS | Transaction number generated by the POS machine for card payment | 1234567890 | String | 1/50 |
chequedddate | Cheque/DD date in case mode of payment is CHEQUE/DD | To identify the instrument date | 21/10/2018 | String | 10/10 |
chequeddno | Cheque/DD no in case mode of payment is CHEQUE/DD | To identify the instrument no | 823842 | String | 6/6 |
bank | Name of the Cheque/DD issuing bank | To identify the issuing bank | State Bank of India | String | 3/50 |
| Payment Period | |||||
paidFrom | The from date for the payment period | To identify the from date for the payment period | 21/10/2018 | String | 10/10 |
paidTo | The to date for the payment period | To identify the to date for the payment period | 21/10/2018 | String | 10/10 |
ulbName | Name of the city in which consumer number is present | To Print on the receipt and giving information to the customer | Longowal 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 |
Sample Response
Fetching the Payment Receipt API
Overview
DIGIT allows searching for receipts based on receipt number and consumer number so that it can be printed or reprinted.
Possible Error Codes and Messages
Error Codes | Error Message |
|---|---|
WSP0006 | Invalid receipt number |
Procedure
Use the API /restapi/collection/receipts/search
Request Parameters
Request Parameter | Description | Purpose | Sample | Data Type | Min/Max Length |
|---|---|---|---|---|---|
UlbCode * | The code of the tenant | 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 | String2/32 | 2/32 |
consumerCode | The Consumer number of the Water or Sewerage connection | To identify the consumer paying for the service | 2113008037 | String | 3/50 |
receiptNumber | The receipt number for the payment of Water or Sewerage connection | To identify the payment receipt | 10/2018-19/6 | String | 3/50 |
Note : Either ‘consumerCode’ or ‘receiptNumber’ is mandatory along with other mandatory fields here.
Sample Request
Response Parameters
Response Parameter | Description | Purpose | Sample | Data Type | Min/Max Length |
|---|---|---|---|---|---|
Receipt Details | |||||
receiptNumber | Payment receipt identification number | Used to identify the payment acknowledgment. | 10/2018-19/279 | String | 3/50 |
receiptDate | Payment receipt date | Used to identify the payment acknowledgment date | 22/10/2018 (format : dd/MM/yyyy) | String | 10/10 |
totalAmountpaid | Amount paid with this receipt | Used to identify the payment amount. | 3195 | BigDecimal | 12,2 |
consumerNumber | The Consumer number of the Water or Sewerage connection | To identify the consumer paid for the service | 9999004280 | String | 3/50 |
| Receipt account head wise details | |||||
accountHead | The account head in which the collected amount deposited | To identify against which account head the payment is done | Water Charges - 2018-2019-Q2 (Jul to Sept) | String | 3/128 |
paidAmount | The paid amount | The paid amount | 200 | BigDecimal | 12,2 |
| Instrument Details | |||||
type | Type of the instrument | To identify payment mode | CASH | String | 2/50 |
InstrumentNumber | Number of the instrument used for the transaction | To identify the card number used for the transaction | 1234 | String | 1/20 |
TransactionNumber | Transaction number generated by the POS | Transaction number generated by the POS machine for card payment | 1234567890 | String | 1/50 |
chequedddate | Cheque/DD date in case mode of payment is CHEQUE/DD | To identify the instrument date | 21/10/2018 | String | 10/10 |
chequeddno | Cheque/DD no in case mode of payment is CHEQUE/DD | To identify the instrument no | 823842 | String | 6/6 |
bank | Name of the Cheque/DD issuing bank | To identify the issuing bank | State Bank of India | String | 3/50 |
| Payment Period | |||||
paidFrom | The from date for the payment period | To identify the from the date for the payment period | 21/10/2018 | String | 10/10 |
paidTo | The to date for the payment period | To identify the to date for the payment period | 21/10/2018 | String | 10/10 |
ulbName | Name of the city in which consumer number is present | To Print on the receipt and giving information to the customer | Longowal 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 |
Sample Response
Note: The consumer of this API may receive multiple receipts for a single consumer code if multiple payments are made for the same consumer code.
Get Transaction status API
Overview
DIGIT allows fetching transaction status for charges based on a transaction ID after the transaction was posted.
Possible Error Codes and Messages
Error Codes | Error Message |
|---|---|
WSP0007 | No payments recorded with given transaction id |
Procedure
Use the API /restapi/collection/transactionstatus
Request Parameters
Request Parameter | Description | Purpose | Sample | Data Type | Min/Max Length |
|---|---|---|---|---|---|
UlbCode * | The code of the tenant | To identify the ULB for which the call is being made | 9999 | String | 4/4 |
Service * | The service Water or Sewerage | To identify the service Water or Sewerage | WATERCHARGES or SEWERAGECHARGES | String | 2/32 |
TransactionId * | The transaction ref. no of the system integrator | To identify the transaction in eGov system for system integrator | TRANS-001 | String | 3/50 |
Sample Request
Response Parameters
Note : If there is a successful payment recorded in the eGov system for given transaction id then the response would be the same as the response of ‘/restapi/watersewerage/paycharges’ otherwise, an error code will be returned.