# HMS Billing, Insurance and Laboratory Integration Specification

## Purpose

This specification defines the minimum application behavior for the supplied billing, insurance and laboratory requirements. It is intentionally implementation-oriented and separates business rules from external integrations.

## Payment options

- **M-Pesa / Mobile Money:** use a dedicated hospital paybill or till number, an invoice/reference number, a gateway transaction reference, and a payment record. The payment must be reconciled before the invoice is marked paid.
- **SHA / SHIF:** submit claims through the approved Afya Yangu or Social Health Authority integration. The patient remains responsible for any approved co-pay, non-covered service, or excess.
- **Private insurance / corporate credit:** capture payer, scheme, member number, preauthorization status, and claim settlement. Credit control must remain separate from cash receipts.
- **Cash, cards and bank transfers:** support cash shifts, POS cards and bank EFT/RTGS. Bank deposits must be linked to the receiving invoice or payer.
- **Payment plans and waivers:** create a structured installment plan or an approved zero-interest financing arrangement. Waivers must have a reason, approver, effective date, scope and audit trail.

## Laboratory lifecycle

1. **Order:** a clinician submits tests, priority, department and clinical notes.
2. **Accession:** the order is assigned a unique barcode and specimen identifier.
3. **Collection and receipt:** sample collection and receipt are timestamped and attributed.
4. **Processing:** the order is transmitted to the configured analyzer, with raw result data imported by the bridge.
5. **Quality control:** analyzer calibration, deviation and maintenance records are retained.
6. **Verification:** result values, reference ranges, delta checks, signatures and report paths are stored.
7. **Release:** the finalized result is published to the EHR and critical values create an alert.

## Data and integration rules

- Use UUID/string identifiers for external payment and analyzer messages.
- Never store full card data or raw gateway secrets in application logs.
- Treat payment as operationally accepted only after the external transaction is confirmed.
- Treat a result as verified only after the required laboratory authorization and signature checks.
- Use database transactions for invoice and payment updates.
- Record every state transition and authorization in the audit log.

## Configuration

- Provider credentials must be supplied through environment variables or an encrypted settings store.
- Analyzer connection types may be `simulated`, `hl7`, `fhir`, or a future provider-specific adapter.
- Payment gateway configuration must allow safe production and test credentials to be selected separately.
- Provider callback endpoints must validate signatures and be idempotent.

## Acceptance criteria

- A lab order can be created and tracked through collection, receipt, processing and verification.
- A payment is never marked settled without a verified reference.
- An insurance claim can be submitted, reviewed, settled or rejected without overwriting the original invoice.
- A payment plan cannot exceed the approved invoice balance and must not allow negative balances.
- A waiver must be linked to the invoice or item and remain auditable.
- No patient identity data is exposed through analyzer logs or payment callbacks.