Skip to content

Payments Architecture

Ankit Upadhyay edited this page Aug 25, 2026 · 2 revisions

Payments Architecture

How money moves — and deliberately does not move through the platform. The decision is ADR-0002; implementation plans are in Plans - Payments and Currency.

Core principle: the clinic is the merchant of record

Yosemite Crew is "software and governance only." It is not a payment facilitator and never holds clinic funds:

  • Each clinic connects a Stripe Standard Connect account.
  • Charges are direct charges created on the clinic's connected account (stripeAccount: organisation.stripeAccountId), not on the platform account.
  • The clinic bears processing fees, disputes, and refund liability directly with Stripe. The platform takes no platform fee / application fee.

This keeps the platform out of payment-facilitator / money-transmitter regulatory scope and lets clinics keep their own Stripe dashboard and portable payment history. Full rationale and trade-offs (Connect KYC onboarding required, less platform control over the flow): ADR-0002. The Standard Connect + direct-charges model shipped via PR #1680.

flowchart LR
    OWNER[Pet owner] -->|pays| STRIPE[Stripe<br/>clinic's connected account]
    CLINIC[Clinic] -->|owns| STRIPE
    API[apps/backend] -->|creates PaymentIntent<br/>on connected account| STRIPE
    STRIPE -->|funds settle to| CLINIC
    API -.no fee, no custody.-> PLATFORM[Yosemite Crew platform]
Loading

Provider abstraction

Stripe is one implementation behind a PaymentProviderPort interface (the "agnostic payments" principle) rather than hard-wired throughout the backend. This is the seam for adding new providers without touching call sites. As of ADR-0002 the port is in progress and not fully merged — until it lands, some Stripe-specific code sits directly in services.

Financing, not a second card processor

Adyen for Platforms was evaluated and dropped: it requires the platform to act as the regulatory principal for sub-merchants, which conflicts with the merchant-of-record-is-the-clinic principle. For clinics that need point-of-care lending, the platform integrates CareCredit and Scratchpay instead — financing partners with a direct clinic-to-provider relationship. See the payment-gateway abstraction epic #1659.

Multi-currency

Clinics operate in different currencies, so money is currency-aware end to end:

  • Currency is chosen at org onboarding and immutable afterward (localeFinalized locks it). Amounts are stored in minor units (cents) with an ISO 4217 currency code.
  • A single presentation system formats EUR / USD / GBP consistently across invoices, payments, inventory, expenses, and subscriptions — on web, mobile, and backend.

The rollout is documented across three implementation guides (backend + Stripe, web, mobile) collected in Plans - Payments and Currency.

What the backend owns

Invoices, subscriptions, expenses, treatment-plan estimates, deposits, and refunds are modeled in Postgres and reconciled against Stripe events. The per-subsystem detail lives in Backend: Billing, Invoices, Subscriptions.

Hardening since 2026-07

A billing-correctness pass landed across 2026-08: invoices now settle only once Stripe reports the funds actually arrived, zero-decimal currencies are honoured in amount handling, the appointment billing lock is enforced server-side rather than trusted to the client, an approved estimate converts directly into an invoice (PR #2429), superseded Stripe artifacts are expired when billing state changes, and a booking invoice is bound to its Stripe payment intent (PR #2477).

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