Skip to main content

Overview

:::info Source Sourced from services/billing-service/SERVICE_OVERVIEW.md in the documentation repo. :::

1. Purpose​

Subscriptions, invoices, payments, tax, dunning, provider payouts. Anti-Corruption Layer (ACL) to external payment gateways (Stripe primary).

2. Bounded Context​

Billing (Generic). UL: Subscription, Invoice, Payment, Customer, TaxJurisdiction, DunningProcess, Payout, PayoutBatch.

3. Responsibilities​

  • Create payment intents; process payments via Stripe.
  • Invoice generation + PDF rendering.
  • Subscription lifecycle (trial → active → past_due → canceled).
  • Tax calculation (Stripe Tax / TaxJar).
  • Dunning (failed payment retries + communication).
  • Provider payouts (Stripe Connect standard + express).
  • Webhooks from Stripe (signed HMAC).
  • Tax filings support (export per tenant + jurisdiction).

4. Non-Responsibilities​

  • Does not own marketplace logic (marketplace-service does).
  • Does not store card data (tokenized via Stripe).
  • Does not decide pricing (marketplace does).

5. Dependencies​

  • Upstream: marketplace-service (order.placed), tenant-service (tenant lifecycle).
  • Downstream: marketplace (payment.succeeded triggers saga step), notification (receipts), analytics (revenue).
  • External: Stripe, Stripe Connect, Stripe Tax, (optional) TaxJar, bank APIs for payouts.

6. Slices & Milestones​

  • S3 (M2): payment processing + invoicing + first revenue.
  • S5 (M4): subscriptions + dunning + payout reconciliation.
  • S6 (M5): multi-currency + payouts at scale.

7. Architectural Freeze Points​

  • F19 — Billing ACL contract: M2 start; vendor-specific code behind ACL; events vendor-agnostic.
  • F20 — Purchase saga billing step: M2 start.
  • F21 — Invoice schema: M2 start.

8. Key Invariants​

  • Payment status reflects processor truth (Stripe is source of truth; we project).
  • Refund ≤ original payment amount.
  • Subscription state machine deterministic.
  • Invoice total = Σ lines + tax - discounts (rounded per currency rules).
  • Payouts reconciled daily; variance < 0.01% alerted.