Billing Service — Epics
Service: billing-service Epic prefix: BILL-EPIC Last updated: 2026-04-17 Companion: Service Template · 03 platform-services · 02 DDD
Epics
BILL-EPIC-01 — Charge Capture and Clinical Coding
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Charge capture from encounter events with CPT/HCPCS/ICHI/local coding |
| Status | To Do |
| Priority | Must |
| Labels | service:billing, domain:billing, slice:S2 |
| Components | charge-capture, coding, ledger |
| Fix version | M1 |
| FR references | FR-BILL-001, FR-BILL-002, FR-BILL-011 |
| Legacy FR refs | FR-BILL-001, FR-BILL-002 |
| Dependencies | cross-service: REG-EPIC-01, ORDERS-EPIC-01, MED-EPIC-01 |
| Rollup status | Not started |
Business outcome: Every clinical service rendered (encounter, procedure, dispense, immunization, telehealth session) automatically creates an auditable charge linked to the patient, provider, facility, and service date — eliminating manual charge-entry and missed revenue.
Description:
Implements the CaptureCharge use case consuming NATS events from registration, scheduling, orders, medication, immunizations, and virtual-care services. Each charge is coded with CPT/HCPCS/ICHI/local codes validated against terminology-service, priced from the effective price list, and posted as an immutable ledger entry. The Charge aggregate transitions draft → posted; reversals create new correcting entries. Money is always represented as { currency: ISO-4217, minor_units: bigint }.
Stories: BILL-US-001, BILL-US-002, BILL-US-012, BILL-US-013
BILL-EPIC-02 — Patient Accounts, Invoices, and Statements
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Patient account AR, invoice lifecycle, and statement generation |
| Status | To Do |
| Priority | Must |
| Labels | service:billing, domain:billing, slice:S2, slice:S3 |
| Components | accounts, invoices, statements |
| Fix version | M1-M2 |
| FR references | FR-BILL-003, FR-BILL-004, FR-BILL-014 |
| Legacy FR refs | FR-BILL-003, FR-BILL-004 |
| Dependencies | BILL-EPIC-01, cross-service: COMMS-EPIC-01, PORTAL-EPIC-01 |
| Rollup status | Not started |
Business outcome: Patients receive accurate, timely statements showing outstanding balances with aging; billing staff can view AR by patient, facility, or age bucket to prioritise collections without touching a spreadsheet.
Description:
Owns the Account aggregate (balance = sum of ledger entries), Invoice lifecycle (draft → issued → paid/voided), and StatementRun batch job. After invoice issue, lines are immutable. Statement runs render PDFs in RTL-capable Pashto/Dari/Arabic (FR-BILL-014) and dispatch via print, SMS-link, or email through communication-service. The billing.statement.generated.v1 event triggers the delivery pipeline. Aging buckets (0-30 through 121+) are materialised for reporting.
Stories: BILL-US-003, BILL-US-004, BILL-US-014, BILL-US-015
BILL-EPIC-03 — Payments, Refunds, and Adjustments
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Cash/card/mobile-money posting, refund approval workflow, adjustment recording |
| Status | To Do |
| Priority | Must |
| Labels | service:billing, domain:billing, slice:S2, slice:S3 |
| Components | payments, refunds, adjustments, ledger |
| Fix version | M1-M2 |
| FR references | FR-BILL-005, FR-BILL-011, FR-BILL-012 |
| Legacy FR refs | FR-BILL-005 |
| Dependencies | BILL-EPIC-02, cross-service: CLAIMS-EPIC-01 |
| Rollup status | Not started |
Business outcome: Every payment — whether cash, card, mobile money (M-Pesa / MTN in Afghanistan context), or payer remittance — is posted with an idempotency guarantee, reconciled against invoices, and traceable to the originating receipt; refunds above configured thresholds require dual approval; contractual adjustments are auto-posted from claims remittance.
Description:
Implements PostPayment (requires Idempotency-Key), RequestRefund, ApproveRefund, RejectRefund, and ApplyAdjustment use cases. Payment methods: CASH | CARD | BANK_TRANSFER | MOBILE_MONEY | PAYER_REMITTANCE | CHECK. Refund state machine requested → pending_approval → approved → posted. The claims.remittance.posted.v1 event consumer auto-posts payer payments and contractual adjustments. No PAN/CVV enters the service; card tokenisation is delegated to the payment-gateway adapter port.
Stories: BILL-US-005, BILL-US-016, BILL-US-017, BILL-US-018
BILL-EPIC-04 — Price Lists, Multi-Currency, and Tax
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Facility-scoped price lists, multi-currency (AFN/AED/USD), and VAT/tax rules |
| Status | To Do |
| Priority | Must |
| Labels | service:billing, domain:billing, slice:S3 |
| Components | price-lists, currency, tax |
| Fix version | M2 |
| FR references | FR-BILL-007, FR-BILL-008, FR-BILL-009, FR-BILL-010 |
| Legacy FR refs | FR-BILL-007, FR-BILL-008, FR-BILL-009, FR-BILL-010 |
| Dependencies | BILL-EPIC-01, cross-service: TENANT-EPIC-01 |
| Rollup status | Not started |
Business outcome: Each facility can maintain its own rate schedule with effective dating (no rate conflicts), support Afghanistan national currency (AFN) alongside AED and USD, and apply jurisdiction-correct tax rules — so invoices are legally compliant across multi-country deployments.
Description:
Implements PriceList aggregate (draft → published → retired) with no-overlap validation on (facility_id, code, currency) effective windows. Price resolution precedence: facility → tenant → national fallback. TaxPolicy port computes tax at charge time; tax lines are snapshotted on the invoice at issue time. Multi-currency: each Account is pinned to one currency at creation; cross-currency invoicing is forbidden (enforced by guard). Mixed payer models (self-pay, corporate, private insurer, public scheme) are configured via payer type on the charge/account.
Stories: BILL-US-007, BILL-US-008, BILL-US-009, BILL-US-010
BILL-EPIC-05 — Payer Remittance Integration
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Auto-post payer payments and contractual adjustments from claims remittance |
| Status | To Do |
| Priority | Must |
| Labels | service:billing, domain:billing, slice:S3 |
| Components | remittance, adjustments, inbox |
| Fix version | M2 |
| FR references | FR-BILL-005, FR-BILL-007 |
| Legacy FR refs | FR-BILL-005, FR-BILL-007 |
| Dependencies | BILL-EPIC-03, cross-service: CLAIMS-EPIC-02 |
| Rollup status | Not started |
Business outcome: When a payer posts remittance advice, the patient account is automatically updated — payer portion credited, contractual adjustment posted, and any patient responsibility remainder surfaced — eliminating manual remittance matching.
Description:
Consumes claims.remittance.posted.v1 from claims-service via the NATS inbox. The remittance saga matches the claim_id on outstanding invoices, calls PostPayment(method=PAYER_REMITTANCE), and then ApplyAdjustment(reason=CONTRACTUAL) for the write-down. Inbox deduplication prevents double-posting. Emits billing.payment.posted.v1 and billing.adjustment.applied.v1 back to the outbox. Unmatched remittances are surfaced as alerts in the operations dashboard.
Stories: BILL-US-019, BILL-US-020
BILL-EPIC-06 — GL Export and ERP Integration
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | General-ledger batch export for ERP systems (CSV/JSON, tenant-scoped) |
| Status | To Do |
| Priority | Should |
| Labels | service:billing, domain:billing, slice:S4 |
| Components | gl-export, erp-adapter |
| Fix version | M3 |
| FR references | FR-BILL-006 |
| Legacy FR refs | FR-BILL-006 |
| Dependencies | BILL-EPIC-03 |
| Rollup status | Not started |
Business outcome: Finance leads can close monthly books by exporting a reconciled, chart-of-accounts-mapped GL file to their ERP, removing the need for manual ledger reconciliation between the health platform and financial systems.
Description:
Implements ExportGeneralLedger use case: async POST /exports/gl with { from, to, format: CSV|JSON }. The export maps ledger entries to configured GL accounts via tenant's chart-of-accounts config; the signed download URL is available via GET /exports/:id when status transitions to completed. Emits no domain events (internal operational export only). Export files are stored in tenant-scoped object storage with 90-day retention. Filtering by facility_id and ledger_type is supported.
Stories: BILL-US-006, BILL-US-021
BILL-EPIC-07 — Module Licensing and Operational Hardening
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Licensing gate, idempotency hardening, outbox reliability, SLO monitoring |
| Status | To Do |
| Priority | Must |
| Labels | service:billing, domain:billing, slice:S2, slice:S4 |
| Components | licensing, outbox, reliability |
| Fix version | M1-M3 |
| FR references | FR-BILL-011, FR-BILL-012, FR-BILL-013 |
| Legacy FR refs | ENH-BILL-001, ENH-BILL-002, ENH-BILL-003, ENH-BILL-004 |
| Dependencies | cross-service: TENANT-EPIC-01, IDENT-EPIC-01 |
| Rollup status | Not started |
Business outcome: The billing service can be safely enabled or disabled per tenant without data leakage; financial mutations are safe to retry under network failures; and the operations team has SLO-backed alerting to catch billing pipeline failures before they become revenue-impacting incidents.
Description:
Implements LicenseClient port check at Kong edge (returns MODULE_NOT_ACTIVE 403 for unlicensed tenants). Idempotency-Key contract for all financial mutations (POST /payments, POST /refunds, POST /adjustments) with IDEMPOTENCY_CONFLICT (409) on hash collision. Outbox relay latency monitored via billing_outbox_lag metric; p95 ≤ 10 s SLO. Refund approval thresholds configurable per tenant. Chaos-tested before M3 GA.
Stories: BILL-US-011, BILL-US-022, BILL-US-023
BILL-EPIC-08 — FHIR Exchange Surface
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Expose ChargeItem, Account, Invoice, PaymentReconciliation via interop-service FHIR R4 |
| Status | To Do |
| Priority | Should |
| Labels | service:billing, domain:billing, slice:S3 |
| Components | fhir-gateway, interop |
| Fix version | M2 |
| FR references | FR-BILL-001, FR-BILL-003, FR-BILL-004, FR-BILL-005 |
| Legacy FR refs | FR-BILL-001, FR-BILL-003, FR-BILL-004, FR-BILL-005 |
| Dependencies | BILL-EPIC-01, BILL-EPIC-02, BILL-EPIC-03, cross-service: INTEROP-EPIC-01 |
| Rollup status | Not started |
Business outcome: External payer systems, national health information exchanges, and insurance claim platforms can consume billing data using standard FHIR R4 resources, enabling seamless interoperability without custom integrations.
Description:
Implements the FhirGateway port in billing's infrastructure layer. When charges, invoices, or payments are committed, the gateway adapter upserts the corresponding FHIR resources via interop-service: ChargeItem (from Charge), Account (from Account aggregate), Invoice (from Invoice), PaymentNotice + PaymentReconciliation (from Payment/Adjustment). Writes via inbound FHIR HTTP to billing are out-of-scope (read surface only via interop-service at /fhir/R4/…).
Stories: BILL-US-024, BILL-US-025