Stripe Billing

​

Was Sie erhalten

• Drei Zugriffsmodi: keine Abos, enthalten + kostenpflichtig oder nur kostenpflichtig
• Stripe-gehosteter Checkout — Benutzer führen ein Upgrade durch, ohne dass Ihre Code-Kartendaten berührt
• Kundenportal — Benutzer aktualisieren Zahlungsmethoden, laden Rechnungen herunter, kündigen — alles auf der Stripe-Benutzeroberfläche
• Webhook-gesteuerte Lebenszyklen — Abos werden automatisch bereitgestellt und erneuert; stornierte kostenpflichtige Benutzer kehren am Ende des Zeitraums zur kostenlosen Stufe zurück (oder werden in reinen Bezahlmodellen nicht berechtigt)
• Kontingentdurchsetzung — Token-Nutzung pro Zeitraum verfolgt; Unterbrechung während des Streams mit strukturierter Upgrade-Aufforderung
• Admin-Seiten für Plan-CRUD und Abonnementüberwachung

​

Voraussetzungen

1. Stripe-Konto mit aktiviertem Live-Modus. Unternehmen mit Sitz in Singapur müssen KYC abschließen (Business UEN, Ausweis des Geschäftsführers, Bankkonto). Die Genehmigung dauert normalerweise 1–3 Tage.
2. Stripe Live API-Schlüssel vom Typ Restricted (empfohlen gegenüber Standard sk_live_*** — einfacher zu widerrufen, begrenzte Berechtigungen).
3. Webhook-Endpunkt öffentlich erreichbar unter <your-domain>/api/webhooks/stripe.
4. Bankkonto für Auszahlungen. Multi-Währungs-Abrechnung (z. B. USD-Auszahlung auf ein USD-Konto) wird für Stripe-Konten ohne USD-Standard empfohlen, um 1,5–2 % Devisenverluste pro Transaktion zu vermeiden.

​

Einrichtung

​

1. Stripe Dashboard

​

Pro-Produkt erstellen

1. Catalog → Products → + Add product
2. Name: Pro, description: 5M tokens / month, priority support
3. Pricing: Recurring, monthly, $20.00 USD (adjust to your pricing strategy)
4. Save → copy the resulting price_*** ID (you will UPDATE the local billing_plans table with this value after activation)

​

Erstellen Sie einen eingeschränkten API-Schlüssel

1. Developers → API keys → + Create restricted key
2. Name: fim-one production
3. Permissions (minimum):
   • Customers: Write
   • Subscriptions: Write
   • Checkout Sessions: Write
   • Customer portal: Write
   • Prices: Read
   • Products: Read
4. Save → copy rk_live_***

​

Webhook-Endpunkt registrieren

1. Developers → Webhooks → + Add endpoint
2. URL: https://<your-domain>/api/webhooks/stripe
3. Zu empfangende Events:
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
4. Nach dem Speichern auf “Reveal signing secret” klicken → whsec_*** kopieren

​

Multi-Währungs-Abrechnung konfigurieren (empfohlen)

1. Settings → Bank accounts and currencies → Add a settlement currency
2. Wählen Sie die Preiswahrung (z. B. USD)
3. Fügen Sie das entsprechende Bankkonto an (z. B. ein Aspire USD Virtual Account)
4. Speichern — Stripe leitet USD-Gebühren direkt zu USD-Auszahlungen weiter, ohne Devisenumrechnung

​

2. Backend .env

STRIPE_SECRET_KEY=rk_live_***
STRIPE_WEBHOOK_SECRET=whsec_***
STRIPE_BILLING_RETURN_URL=https://<your-domain>/settings?tab=billing

./deploy.sh   # or: docker compose restart fim-one

​

3. In Admin aktivieren

1. Melden Sie sich als Admin an
2. Admin → System Settings → Access and billing
3. Wählen Sie eine Posture aus (die Instanz befindet sich immer in genau einer):
   • No subscriptions (Software-Standard) — Stripe wird nicht verwendet. Token-Zugriff ist das Standard-Monatskontingent (0 = unbegrenzt).
   • Included + paid — Stripe erforderlich. Neue Benutzer landen auf dem Included-Tier; sie können upgraden. Stornierte bezahlte Benutzer kehren am Ende des Abrechnungszeitraums zum Included-Tier zurück.
   • Paid only — Stripe erforderlich. Kein Included-Tier. Benutzer müssen sich abonnieren, bevor sie Modelle aufrufen können. Bestehende Benutzer des Included-Tiers behalten ihr Kontingent, wenn Sie von Included + paid wechseln.
4. Das Backend validiert, dass sowohl STRIPE_SECRET_KEY als auch STRIPE_WEBHOOK_SECRET vorhanden sind, wenn Sie eine Stripe-Posture wählen — wenn einer fehlt, wird 400 zurückgegeben
5. Bei der ersten Aktivierung einer Stripe-Posture führt das Backend ein idempotentes Setup durch:
   • Included + paid: erstellt den Included-Plan (slug=free) + eine Pro-Vorlage mit einer leeren Price ID; setzt default_plan_id; füllt Benutzer ohne Plan auf
   • Paid only: erstellt nur die Pro-Vorlage; führt keine Auffüllung durch
   • Kopiert default_token_quota auf den Included-Plan, wenn dieser Plan erstellt wird (0 bleibt 0, unbegrenzt)
6. Das Zurückschalten auf No subscriptions ist ein reines Flag-Flip ohne Datennebenwirkungen. Der Standard-Included-Plan kann nicht gelöscht werden, während Included + paid aktiv ist.

​

4. Aktualisieren Sie den Pro-Plan mit Ihrem Live-Preis

• Admin → Billing → Plans → Pro → Edit
• Fügen Sie Ihre price_1*** (aus Schritt 1) in Stripe Price ID ein
• Speichern

UPDATE billing_plans
SET stripe_price_id = 'price_1***'
WHERE slug = 'pro';

​

5. Smoke-Test

1. Öffnen Sie /settings?tab=billing als normaler Benutzer
2. Klicken Sie auf Switch to Pro
3. Stripe Checkout wird geöffnet; füllen Sie es mit einer echten Karte mit niedrigem Betrag aus (erstatten Sie danach)
4. Webhook sollte ausgelöst werden — überprüfen Sie im Stripe Dashboard → Webhooks → aktuelle Ereignisse zeigen 2xx-Antworten
5. Abonnementzeile erscheint in der Tabelle subscriptions; users.plan_id wechselt zu pro
6. Die Benutzeroberfläche zeigt jetzt Pro-Plan + Schaltfläche „Manage subscription”

​

Abrechnung deaktivieren

• Alle /api/billing/*-Endpunkte geben 503 zurück
• Der Webhook-Endpunkt gibt 503 zurück (Stripe wird erneut versuchen und dann im Dashboard als fehlgeschlagen angezeigt — das ist in Ordnung, Sie können den Webhook stattdessen im Stripe Dashboard deaktivieren, wenn die Abrechnung dauerhaft ausgeschaltet ist)
• Die Registerkarte Plan & Billing für Benutzer verschwindet
• Die Navigationsgruppe Admin → Billing ist ausgeblendet
• Die Quota-Kette überspringt die Plan-Stufe und fällt direkt auf default_token_quota zurück

​

Berechnungsreferenz — Kontingent- und Token-Mathematik

​

Glossar

​

Was als Token zählt

• Gezählt: Prompt-Tokens + Completion-Tokens bei jedem Modellaufruf
• Gezählt: jeder Roundtrip in einem mehrstufigen / Tool-Use-Agent-Flow (jeder Modellaufruf ist eine separate Belastung)
• Gezählt: Embedding-Anfragen (KB-Ingestion, Abruf-Scoring)
• Nicht gezählt: eingegebene Daten, die nie an ein Modell gesendet werden (z. B. hochgeladene Dateien, die der Benutzer verwirft)
• Nicht gezählt: Anfragen, die fehlschlagen, bevor sie den Provider erreichen (Authentifizierungsfehler, Rate-Limit-Vorabprüfung)
• Zwischengespeicherte Eingabe: in v1 zum vollen Preis gezählt (kein Provider-Cache-Rabatt wird angezeigt). v2 kann zwischengespeicherte Prompt-Tokens möglicherweise separat gutschreiben.

​

Three-state override semantics

​

Quota resolution chain — v1 (current)

1. users.token_quota        ── NULL? skip. 0? unlimited. N>0? cap at N.
2. users.plan.monthly_token_quota   ── only when access_model is freemium or paid_only
3. paid_only + no plan      ── unentitled (stop; do not fall through)
4. system_settings.default_token_quota  ── used when access_model is off
5. unlimited                ── last resort if everything above is unset

​

Periodische Zurückstellung

• Für bezahlte Benutzer spiegelt quota_reset_at Subscription.current_period_end wider. Der invoice.payment_succeeded Webhook-Handler setzt tokens_used_this_period = 0 und verschiebt quota_reset_at bei jeder erfolgreichen Verlängerung auf das neue Periodenende.
• Für kostenlose Benutzer (kein Stripe-Abonnement) setzt ein stündlicher Cron tokens_used_this_period auf 0 an einer Kalendermonatsgrenze, die am Plan-Zuweisungsdatum verankert ist.
• Planänderungen in der Mitte einer Periode setzen den Zähler nicht zurück — nur Verlängerungen tun dies. Dies verhindert Quota-Cycling-Exploits („abonnieren → Pro-Quota nutzen → kündigen → erneut abonnieren”).

​

Mid-stream enforcement

• Pre-flight check at chat-call entry: cheapest path, blocks requests the user can’t afford to start.
• During streaming, the running token count is re-evaluated on every chunk. Crossing the cap closes the stream with a structured terminator frame, not a network error.
• The frontend interprets the terminator and surfaces <QuotaExceededDialog> with a deep link to /settings?tab=billing.
• Non-streaming responses return HTTP 402 with body { code: "QUOTA_EXCEEDED", reset_at, upgrade_url }.

​

Billing-deaktiviert-Fallback

• Schritt 2 der Kette wird übersprungen — die Kette reduziert sich auf override → default → unlimited.
• /api/billing/* und /api/webhooks/stripe geben 503 zurück.
• Die Registerkarte Plan & Billing für Benutzer und die Admin → Billing-Navigationsgruppe sind ausgeblendet.
• Alle Abrechnungsdaten (Abonnements, Pläne, users.plan_id) bleiben erhalten — das erneute Aktivieren setzt den gleichen Status fort, ohne Migration erforderlich zu sein.

​

Reserviert: quota chain v2 — Team-Plätze

• Subscription.quantity führt die Platzanzahl (Stripe-nativ).
• Der effektive Plan eines Benutzers wird durch Team-Mitgliedschaft aufgelöst, bevor auf seinen persönlichen Plan zurückgegriffen wird:
  effective_plan = team.plan if team_member(user) else user.plan
  
• Quota ist pro Platz (jedes Team-Mitglied erhält ein vollständiges monthly_token_quota), nicht ein gemeinsamer Pool. Gemeinsame Pools führen zu First-Come-First-Served-Erschöpfung und sind kundenfeindlich.
• Override-Semantik bleibt unverändert — Team-Administratoren können einzelne Mitglieder weiterhin hart begrenzen über users.token_quota = N, was in der Kette über dem Team-Plan liegt.

​

Reserved: quota chain v3 — native Org allocation (no Stripe)

• Neue Tabelle org_quota_allocations(user_id, monthly_token_quota, org_id) verteilt ein übergeordnetes Budget auf Mitglieder.
• Zuweisungen sind pro Benutzer, kein gemeinsamer Pool — jedes Mitglied hat ein klares individuelles SLA.
• Aktualisierte Chain:
  override → max(plan_quota, org_allocation) → default → unlimited
  
• max(), nicht sum(). Ein bezahlter Pro-Benutzer erhält nie weniger als das, wofür er bezahlt hat, auch wenn sein Org-Administrator eine niedrige Zuweisung festlegt. Das über Stripe bezahlte Kontingent ist unverletzlich.

​

Reserviert: Pay-per-use-Gutschriftsaldo (v3 separate Dimension)

• Neue Tabelle user_credits(user_id, balance_cents, currency) — finanziert über Stripe Checkout mode='payment'.
• Verbrauchsreihenfolge: Abonnement-Kontingent zuerst, dann Gutschriftsaldo (nur nach Erschöpfung des Abonnements beginnt die Gutschrift zu sinken).
• Gutschriftsaldo ist nicht erstattbar (Industriestandard für Prepaid).
• UI zeigt beide Balken: Subscription quota: 4.2M / 5M used + Credits: $7.40 remaining.

​

Standardwerte

​

Preismodell

• Team-Plan (Stripe-Plätze / subscription.quantity)
• Jährliche Abrechnung
• Multi-Währungs-Präsentation
• Gutscheine / Promo-Codes
• Steuerbehandlung (Stripe Tax-Integration — erfordert separate Compliance-Überprüfung)
• Nutzungsbasierte Messung / Überschussgebühren
• Pay-per-Use-Guthaben (einmalige Aufstockung)

​

Fehlerbehebung