Stripe billing integration — payment method registration, invoice listing, spending limit management, and webhook processing. Covers Stopa C issues fe#11, fe#12, fe#13, and be#111.
Overview
TalkIDE integrates with Stripe (test mode) to enable users to register a payment method, view invoices, and control their monthly spending limit. The BE foundation (be#111) implements the Stripe Customer lifecycle, SetupIntent, and webhook event processing.
Key design decisions:
- One Stripe Customer per TalkIDE user, lazy-created on first billing action (
stripe_customer_idstored inuserstable). - No Stripe Products / Prices / Subscriptions — this is not a recurring subscription billing. Stripe is used for payment method on file + invoice generation only.
- All Stripe API calls are made BE-side. FE never holds a Stripe secret key.
- Stripe test mode throughout — no real money; testcard
4242 4242 4242 4242. - Webhook endpoint (
POST /api/v1/stripe/webhook) is excluded from JWT auth filter — authenticated via Stripe-Signature header. - Liquibase migrations are immutable (production phase). New columns are added via new migration files only.
DB Changes (new migration files required)
| Migration file | Change |
|---|---|
0021-add-stripe-customer-id-to-users.xml | ALTER TABLE users ADD COLUMN stripe_customer_id VARCHAR(255) NULL |
0022-add-spending-limit-to-user-budget.xml | ALTER TABLE user_budget ADD COLUMN spending_limit_usd NUMERIC(10,2) NULL (null = unlimited) |
UC Index
| UC ID | Name | Description |
|---|---|---|
| UC-10001 | Register Payment Method | Stripe SetupIntent flow — FE mounts Stripe Elements, BE creates SetupIntent, FE confirms, BE sets default payment method on Customer. |
| UC-10002 | Get Payment Method | Returns current default payment method (card brand, last4, expiry) from Stripe Customer. Shows placeholder when no method registered. |
| UC-10003 | Update Billing Email | Change billing email independently of account email. Validated and persisted to Stripe Customer object. |
| UC-10004 | List Invoices | Paginated list of Stripe invoices for the authenticated user. Supports download via Stripe hosted_invoice_url. |
| UC-10005 | Spending Limit GET + PUT | Read and update the monthly spending limit (USD, nullable = unlimited). Enforced soft: alert at 80% / hard stop at 100%. |
| UC-10006 | Stripe Webhook | Inbound Stripe webhook endpoint — signature verification, idempotent event processing for payment_method.attached, customer.updated, invoice.* events. |
| UC-10007 | Credit Top-up | Jednorázové dobití AI kreditu uživatelem zvolenou částkou (min $5, max $500) přes Stripe PaymentIntent s uloženou kartou. Kredit připsán asynchronně po payment_intent.succeeded webhooky. |
| UC-10008 | Apply Markup to Billing (Phase-2a) | KOMPLETNÍ. Marže (pricing_markup_config) se přestane jen zobrazovat a reálně se promítne do odečtu z kreditu + reconciliation/quota. Raw immutable, charged odvozený. Marže 0 = no-op (žádná regrese). Model-agnostic. |
| UC-10009 | Postpaid Hosting Model (Phase-2b, DESIGN) | Cílový postpaid hosting model (metered akruál → měsíční Stripe charge, ADR-103). Datový model + API náčrt + přeodvozené Open Decisions DP-0..DP-6. Nadřazeně přerámováno UC-10009 ENVIRONMENT REVISION + ADR-026. |
| UC-10009 ENVIRONMENT REVISION | Postpaid přerámováno per-environment | Nadřazené přerámování UC-10009 pod ADR-026 Environment first-class. LOCKED DP-0/1/2/3/5/6 beze změny, DP-4 přerámováno per-env, be#125 z velké části padá, fázovaný migrační plán F1–F5, konsolidované Open Decisions OD-1..OD-7. Všechna rozhodnutí LOCKED (ADR-026 Accepted 2026-05-19). |
| UC-10010 | Environment Foundation — F1 (implementovatelná) | PŘIPRAVENO K IMPLEMENTACI. Entita environment + lazy get-or-create default „TalkIDE” (kind=DEFAULT, resource_mode=SHARED, deletable=false). Liquibase changeset 0031, backfill endpoint, nulový infra dopad. Foundation pro F2–F5. |
| UC-10011 | Environment Phases F2–F5 (scope + acceptance) | Scope, acceptance kritéria a závislosti pro fáze F2 (billing read-path + postpaid + SOFT enforcement), F3 (Create/Manage Environment SHARED), F4 (per-env ns cut-over + hard enforcement), F5 (DEDICATED, post-alfa). Plné UC per-fáze se dopíšou před implementací. |
| UC-10012 | Environment Billing — F2 (implementovatelná) | PŘIPRAVENO K IMPLEMENTACI. Billing read-path + postpaid akruál + měsíční faktura (per-env řádky) + SOFT dunning enforcement. Changesety 0034–0039. Staví na F1 (UC-10010). Žádná infra akce, SOFT enforcement only. |
| UC-10013 | Environment Create/Manage — F3 (implementovatelná) | PŘIPRAVENO K IMPLEMENTACI. Create/Delete/Get/List prostředí (USER_CREATED, SHARED). EnvironmentProvisioner wrapper (K8s + Noop), namespace {tenant}-{env-slug}. projects.environment_id nullable FK (changeset 0040). FE Environment management UI. Staví na F2 (UC-10012). |
| UC-10014 | Environment Deployment Wiring + Live Tenant Cut-over — F4 (implementovatelná) | PŘIPRAVENO K IMPLEMENTACI. Napojení Environment konceptu na deployment pipeline — namespace routing {tenant-slug}-{env-slug} podle prostředí projektu (published) / DEFAULT (preview). NamespaceResolver. Backfill project.environment_id (changeset 0042, jediná DB změna — data, ne schéma). Jednorázový cut-over živých tenantů popelkam/h na nový namespace tvar (ruční runbook). NEzahrnuje ADR-024 worker extraction (druhý tým) ani hard enforcement (F5). Staví na F3 (UC-10013). |
| UC-10015 | Hosting Hard Enforcement — F5 (implementovatelná) | PŘIPRAVENO K IMPLEMENTACI. HARD scale-to-zero enforcement DP-4-A: při SUSPENDED stavu billing účtu (po F2 dunning pipeline) se scalují na 0 jen published prod app Deploymenty. Worker, preview a dev-loop nedotčeny. Resume po úhradě via Stripe webhook. Changesety 0043–0044. Admin endpoints (GET report + POST ruční resume). Staví na F4 (UC-10014). |
| UC-10016 | Usage Breakdown Per-Project (Stopa C — be#35 + fe#10) | PŘIPRAVENO K IMPLEMENTACI. Nový endpoint GET /api/v1/users/me/usage/project-breakdown — AI top-N projektů (charged cost + tokeny) + hosting per-namespace breakdown. Per-period přepínač (this month / last month). Nahrazuje hardcoded USAGE mockup v BillingSection.vue. Žádná Liquibase migrace (read-only). |
| UC-10017 | BOGO Credit Bonus (Stopa D.5 — be#135) | PŘIPRAVENO K IMPLEMENTACI. Early adopters (uživatelé s invite_generation <= bogo_max_generation) dostávají 2× kredit za každý zaplacený Stripe top-up. ⚠️ BOGO se týká výhradně AI prepaid kreditu (UC-10007 top-up) — nesouvisí s hostingem (hosting je postpaid, bez credit balance). Pure BE změna v ProcessTopupWebhookUseCase. Liquibase changeset 0047 přidává bogo_max_generation do pricing_markup_config. Threshold konfigurovatelný v DB bez redeploye; -1 = BOGO vypnuto. |
| UC-10018 | Per-Environment Secrets Management | PŘIPRAVENO K IMPLEMENTACI. Project owner spravuje citlivé konfigurační hodnoty (API klíče, tokeny, hesla) vázané na prostředí projektu. K8s Secret jako source of truth pro values; DB pouze metadata + masked_preview. Mara widget request-secret, agent context injection (Mara + Theo + Kai), FE tabbed Project Settings. Security invariant: value NIKDY v PG, logu ani conversation history. |
Stopa C analýza: UC-10008 Hosting credit fund — FÁZE 1 ANALÝZA — historický stav-as-is podklad; prepaid návrh superseded PIVOTEM na postpaid (viz UC-10009). Sekce „stav-as-is” je stále závazná. Hosting je výhradně postpaid (DP-7, 2026-05-23): Prepaid back-door (
hosting_credit_*sloupce,settlement_mode, TOPUP/AUTOPAY source hodnoty) odstraněn v be#142 + fe#38. Žádné future prepaid doors — viz UC-10009 sekce 6 a ADR-026 DP-7.
Ops
| Dokument | Popis |
|---|---|
| Stripe Prod/Live-Flip Runbook | Interní OPS postup přechodu sandbox → live mode (architektura tajemství, live flip procedura, gapy před flipem). |
Was this page helpful?
Thanks for the feedback.