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) to provide citizen facilities via integration with relevant service players.

Purpose

This document aims to provide information on how to integrate third-party(BBPS) Billing and Collection services with the DIGIT governance platform. It enables system integrators to get the system to create and update bills, 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

Steps to Integration

1. User - Create a new user with type as SYSTEM for 3rd Party system. The user’s login and its generated token should be bound to a specific set of whitelisted IPs.

2. Bill - The 3rd party should call fetchBill from the server-side to fetch the bill details.

3. Transaction - The 3rd party service will call transaction/_create to initiate a transaction before accepting the payments from the customer.

   After payment completion transaction/_update will be called to mark success or failure of the transaction. The transaction/_update should only be allowed to the user who created the transaction. Transactions once marked successful/failed should not be allowed to be updated. 

   On successful transaction, the receipt should be created automatically with a receiptdate as the transaction create date. In cases when bills are only valid for a day, these bills should be handled for transaction success delays. https://www.getpostman.com/collections/3a1626684a1585abf9ee

API List

(Note: All the API’s are in the same postman collection therefore same link is added in each row)

Integration Steps:

• MDMS Changes : In MDMS repository, add a role specific to BBPS in “roles.json” file. After adding role, the required actions should be mapped to this role in “roleactions.json“ file. Here for BBPS integration, the fetchbill, create/update transactions and create payment actions to be mapped. The actionid’s for these endpoints should be taken from the “actions-test.json“ for mapping. The details are given in the API list section above. Once the data is added restart the MDMS service to get the changes into effect.

• USER Creation : In our system we have users of different types like Employee, Citizen and System. For BBPS integration we need to create user of type System who have access only to the API’s and not to our application. Create a user of type SYSTEM, map user to the BBPS role and tenant with state tenant ID(ex: uk.uttarakhand which is base tenant). The api “Createnovalidate“ is used to create system users. While using this endpoint we need to pass the authtoken of a Superuser or the HRMS employee who is responsible for creation of employees in the system. The endpoint details are given in the API list section above.

• API Calls : For making the required API call we need to pass the authtoken of the BBPS system user. Use the authtoken api endpoint for generating the authtoken. The userid and password of the BBPS system user to be provided as parameter for the authtoken api. The endpoint details for authtoken generation is given in the API List section above.

• Payment Modes : For making payment, we have different modes. Expecting enduser to use payment mode as ONLINE. “transactionNumber” is mandatory field in the api. The api contract details are here  https://raw.githubusercontent.com/egovernments/business-services/master/Docs/collection-services/V-2-0.yml