subscription-stripe

Stripe payment provider plugin for billing-foundation. Reads its Stripe API key + webhook secret from system config keys with backing:"secrets" (envelope-encrypted in the secrets store under the system tenant) and a billingLive system config flag — all at runtime, so keys rotate and prod goes live without a redeploy. The mask on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via createSubscriptionStripeFeature({ priceToTier }); the optional apiKey/webhookSecret options are env→secrets bridge fallbacks. The plugin always mounts — createCheckoutSession throws feature_disabled unless billingLive is true, so sk_test_ keys in prod never produce a live checkout. Implements webhook verify, checkout, portal, cancel, retrievePrices (10-minute TTL-cached price lookup for the billing-plans catalog), createPlanSwitchSession (auto-provisions a Customer-Portal configuration for switching an existing subscription to another plan tier — each tier needs its own Stripe product), retrieveSubscription (live provider-side snapshot for the sync-subscriptions backfill job, mapped identically to the webhook path), plus isBillingEnabled (billingLive + an api-key existence probe, no secret read).

How it fits

What this feature needs to run (Requires).

flowchart TB
  n_subscription_stripe["subscription-stripe"]
  subgraph how_reqs["Requires"]
    n_billing_foundation["billing-foundation"]
    n_config["config"]
    n_secrets["secrets"]
  end
  n_billing_foundation --> n_subscription_stripe
  n_config --> n_subscription_stripe
  n_secrets --> n_subscription_stripe

Dependencies

• Requires: billing-foundation, config, secrets
• Activation: always on (not toggleable)

Configuration

Per-tenant config keys, set via the tenant-admin UI or a seed. 🔒 = encrypted at rest.

Key	Type	Default	Scope	Who can write	Who can read
api-key	text	—	system 🔒	SystemAdmin	TenantAdmin, Admin, SystemAdmin
billing-live	boolean	false	system	system, SystemAdmin	TenantAdmin, Admin, SystemAdmin
webhook-secret	text	—	system 🔒	SystemAdmin	TenantAdmin, Admin, SystemAdmin

Extensions & cross-feature APIs

• Registers extension: subscriptionProvider → stripe