Finance Billing

Revenue Cycle & Financial Engine Specifications

Financial Architecture Guardrail

This document designs the ledger framework for the HMIS, enforcing multi-payer transaction splits, atomic billing states, and real-time reconciliation with SHA and M-Pesa.

1. Payer Architecture & Multi-Channel Routing

The Level 4 facility handles three primary financial intake channels: Cash/Mobile Money, the Social Health Authority (SHA), and Private Corporate Insurers. The financial engine tracks liability at the individual line-item level, allowing split billing within a single encounter.

Rendering Chart

2. Double-Entry Ledger & Database Schema Design

To prevent arbitrary data manipulation and ensure transaction integrity, the billing architecture uses an append-only, double-entry bookkeeping design.

2.1 Core Billing Database Schema

Rendering Chart

3. Financial Edge Cases & Exception Workflows

3.1 Partial Payments & Item Discharges

When a patient lacks the funds to settle a comprehensive bill, the system locks downstream fulfillment steps until the balance is cleared or an administrative waiver is applied:

# System core logic for partial processing
from decimal import Decimal
from typing import List, Dict

def calculate_payment_split(ledger_items: List[Dict], available_funds: Decimal) -> Dict:
    """
    Allocates available cash across critical line items sequentially, 
    flagging items that remain unpaid or require partial dispensation.
    """
    settled_items = []
    unpaid_items = []
    remaining_balance = available_funds

    # Prioritize life-saving procedures and diagnostics over consumables
    sorted_items = sorted(ledger_items, key=lambda x: x['priority_score'], reverse=True)

    for item in sorted_items:
        cost = Decimal(str(item['cost_kes']))
        if remaining_balance >= cost:
            remaining_balance -= cost
            settled_items.append({**item, "status": "SETTLED", "paid_amount": cost})
        elif remaining_balance > 0:
            settled_items.append({**item, "status": "PARTIAL", "paid_amount": remaining_balance})
            unpaid_items.append({**item, "status": "OWED", "unpaid_amount": cost - remaining_balance})
            remaining_balance = Decimal('0.00')
        else:
            unpaid_items.append({**item, "status": "UNPAID", "unpaid_amount": cost})

    return {
        "settled": settled_items,
        "owed": unpaid_items,
        "remaining_cash_kes": remaining_balance
    }

3.2 Credit-Based Care and Corporate Guarantors

For authorized organizations (e.g., corporate partners, agricultural firms, county staff insurance schemes), the system allows account-based credit loops:

The system checks the corporate client's credit limit before allowing credit selections: lock:credit:corporate_id.
Transactions generate an authorized invoice token linked directly to the parent account.

If a credit limit is breached, the system locks further requests and displays a balance notice to the user.

{
  "claim_header": {
    "sha_provider_id": "L4-WST-7712",
    "claim_timestamp": "2026-06-22T10:17:48+03:00",
    "fund_type": "SHIF"
  },
  "beneficiary": {
    "sha_member_number": "SHA-992182-AA",
    "biometric_verification_token": "BIO_TOK_8823194012A"
  },
  "clinical_payload": {
    "primary_diagnosis_icd11": "1C10.0",
    "operative_report_attached": false,
    "los_days": 0
  },
  "financial_summary": {
    "total_billed_kes": 1200.00,
    "capitation_deduction_kes": 1200.00,
    "patient_copay_kes": 0.00
  }
}

5. Automated Reconciliation & Audit Logs

To prevent internal fraud, modifications to any financial record or ledger item status generate an entry in an immutable audit ledger:

CREATE TABLE financial_audit_ledger (
    audit_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    ledger_entry_id UUID NOT NULL,
    mutation_type VARCHAR(32) NOT NULL, -- 'STATUS_CHANGE', 'WAIVER', 'SPLIT'
    old_state JSONB,
    new_state JSONB,
    authorized_by_user_id UUID NOT NULL,
    digital_signature TEXT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);