OpenMRS 3.x Billing Module Billing

This page outlines the purpose, features, configuration, and developer resources for the billing microfrontend (MF) in OpenMRS 3.x. It is meant to guide implementers, developers, and testers in setting up, customizing, and using the billing functionality.

Repositories

Frontend App: openmrs-esm-billing-app (see especially the README)
Backend App: openmrs-module-billing

Overview

The Billing Module for OpenMRS 3.x is a frontend microfrontend (MF) application designed to streamline financial operations in clinical settings. It provides tools to:

Create and manage patient bills
Capture and track payments
Define and categorize billable services
Configure patient categories (e.g., paying, insurance, exempt)
Seamlessly integrate with patient visits, encounters, and dashboards

This module communicates with the backend OpenMRS Billing Module and adheres to the OpenMRS 3.x microfrontend architecture.

User Stories

Actors

Patient
Registration Clerk
Consultant/Clinician
Lab Technician
Pharmacist
Hospital Supervisor
Cashier
Administrator

As a Patient

I would like to pay via Mobile Money, Card, or Cash.
I would like to get services even as a non-paying client.
I would like to know the cost before receiving services.

As a Registration Clerk

I should be able to register patients with their preferred payment method.
I should be able to select the billable items (e.g., consultation, lab, pharmacy).

As a Consultant/Clinician

I should be able to add billable items to the invoice.
I should be able to see costs to advise the patient accordingly.

As a Lab Technician

I should generate billable items once I confirm capability (e.g., reagents, samples).

As a Pharmacist

I should generate billable items only for available or alternative stock.
I should dispense only after confirming payment for walk-in prescriptions.

As a Hospital Supervisor

I should view all bills: paid, unpaid.
I should waive some or all billable items.
I want role-based access for staff.

As a Cashier

I should view bills by payment status.
I should view individual invoices with item-wise payment options.
I should print invoices and receipts.
I should see indicators for waived items.

As an Administrator

I should configure pricing and billable items.
I should set up cashier points per service area.

Features for RefApp

Role-based access control
Captures all services as billable items (consultation, labs, drugs)
Item menu for cashiers to bill clients
Payment modes: cash, card, mobile money
Handles non-paying clients (e.g., prisoners, waived bills)
Displays mode of payment per patient
Mobile money integration
Teller reconciliation: service, amount, officer, date, time, station
Lists bills by payment status (paid, unpaid, new)

Technical Approach

Strategy I: Frontend/Backend Billing Modules

Adopt the existing Billing module as a reference and:

Create OpenMRS backend and frontend billing modules
Trigger event-driven bill creation from lab/test orders or specific encounters
Configure per-point billing or end-of-visit billing flows
Add support for minor procedures and surgeries as billable items
Add a billing widget to the patient chart
Support creation of new bills inline with services

Accessing the Billing UI

Start your OpenMRS 3.x server and log in
Navigate to System Administration → Implementer Tools → Feature Flags
Enable the Billing Module toggle
Access the billing UI via the App Switcher or directly at /openmrs/spa/billing

Local Development

Prerequisites

Node.js v18+
Yarn (npm install -g yarn)
Git clone of the repo

Setup

yarn            # Install dependencies
yarn start      # Start dev server

After login and selecting a location:

Navigate to feature flags and enable the Billing Module
Access the app at /openmrs/spa/billing

Configuration

The billing MF supports frontend configuration through the OpenMRS configuration framework. Use the openmrs.config.billing key to provide overrides.

Sample Configuration

{
  "openmrs": {
    "config": {
      "billing": {
        "defaultCurrency": "UGX",
        "pageSize": 20,
        "showEditBillButton": true,
        "patientCatergory": {
          "paymentDetails": "fbc0702d-b4c9-4968-be63-af8ad3ad6239",
          "insuranceScheme": "aac48226-d143-4274-80e0-264db4e368ee"
        },
        "nonPayingPatientCategories": {
          "childUnder5": "1528AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
        }
      }
    }
  }
}

Note: All UUIDs must be valid and present in your OpenMRS dictionary

Configuring Currency

To configure the currency used in the billing module, set the defaultCurrency property in your configuration. This determines the currency code (e.g., UGX for Ugandan Shillings, KES for Kenyan Shillings, USD for United States Dollars etc) displayed in the billing interface.

Example:

{
  "openmrs": {
    "config": {
      "billing": {
        "defaultCurrency": "UGX"
      }
    }
  }
}

This currency setting will be used across all billable items, invoices, and payment screens.

Troubleshooting

If your local instance doesn’t reflect latest features or looks different from dev3:

yarn up openmrs@next @openmrs/esm-framework@next
yarn

Deployment

Follow the official Creating a Distribution guide to include the Billing MF in your distribution.

Resources

Technical approach II: using 3rd party ERPs

Use case I: ERPNext/ Odoo

Features:

Inventory management (stock ledger, balance reports and inventory documentation)

All in one healthcare software(lab management, in-department operations, billing, prescriptions, reminders, pharmacy, accounting, asset management, payroll/ HR management, system configuration).

There will be data exchange between the EMR and the ERP depending on functionality/modules that an implementation prefers to use.