Skip to content

Backend Billing Invoices Subscriptions

Ankit Upadhyay edited this page Jul 24, 2026 · 2 revisions

Backend: Billing, Invoices, Subscriptions

Money — Stripe Connect (platform + connected accounts), invoices with full pricing/tax/discount math, payments/refunds, subscriptions, expenses, and org account withdrawals. Architecture context: Payments Architecture / ADR-0002. Part of Backend Overview.

What it owns

The clinic is the merchant of record on its own Stripe account; the backend creates charges on the connected account and reconciles Stripe events. A dedicated services/finance/ module holds the pure billing logic separate from the Stripe plumbing. Finance webhooks are raw-body (registered before express.json()).

Routers

invoice.router.ts, finance.router.ts (mounted at both /v1/finance and /fhir/v1/invoice), stripe.router.ts, expense.router.ts, account-withdrawal.router.ts.

Controllers

app/invoice.controller.ts, app/finance.controller.ts (FinanceController.webhook), web/stripe.controller.ts (StripeController.webhook, .connectWebhook), app/expense.controller.ts, app/account-withdrawals.controller.ts.

Services

  • Top-level: invoice.service.ts, stripe.service.ts, expense.service.ts, account-withdrawal.service.ts.
  • The services/finance/ module:
    • payment.ts — FinancePaymentService (Stripe payment attempts / refunds / settlement).
    • subscription.ts — SubscriptionStatus / BillingInterval mapping.
    • pricing.ts — roundMoney, discount/tax line math.
    • discount-settings.ts — FinanceDiscountSettingsService (per-organisation cap on the overall invoice discount).
    • tax.ts — Stripe Tax snapshots.
    • events.ts — FinanceEventService (finance audit events).

Models

Billing entities are Prisma-only (the Mongoose billing models were removed in PR #1819): Prisma models payment, paymentAttempt, refund, subscription, plus tax/tenant tables. Utils: utils/billing.ts, utils/payment.ts.

Notable

  • Webhook signature verification — Stripe and Stripe Connect webhooks are verified against their signing secrets on the raw body; the router is mounted before JSON parsing precisely so signatures validate.
  • FinanceEventService provides an audit-style event stream for finance, one of the decoupling mechanisms in place of a general event bus.
  • The overall invoice discount posts to the ledger and is capped per organisation (PR #1866, merged 2026-07-23).
  • Multi-currency, invoice linking across booking channels, and the provider-port abstraction are covered in the Payments & Currency plans.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally