Zum Hauptinhalt springen

Stripe Integration Setup

Diese Anleitung erklärt, wie du die Stripe-Integration der School-SaaS Webapp (webapp/) einrichtest.

1. Stripe Account einrichten​

  1. Erstelle einen Account auf stripe.com
  2. Wechsle zum Dashboard
  3. Stelle sicher, dass du im Testmodus bist (Toggle oben rechts)

2. API Keys generieren​

  1. Gehe zu Developers > API keys im Stripe Dashboard
  2. Kopiere den Publishable key (beginnt mit pk_test_)
  3. Kopiere den Secret key (beginnt mit sk_test_)

3. Webhook einrichten​

Für Vercel Deployment:​

  1. Gehe zu Developers > Webhooks im Stripe Dashboard

  2. Klicke auf Add endpoint

  3. Setze die Endpoint URL auf: https://deine-vercel-domain.vercel.app/api/stripe/webhook

  4. Wähle folgende Events aus. Diese Liste entspricht exakt dem relevantEvents-Set in app/api/stripe/webhook/route.ts — andere Events werden vom Handler ignoriert:

    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • customer.subscription.trial_will_end
    • invoice.payment_succeeded
    • invoice.payment_failed

    Die Events customer.subscription.paused und customer.subscription.resumed werden nicht verarbeitet und müssen nicht abonniert werden.

  5. Klicke auf Add endpoint

  6. Kopiere den Webhook signing secret (beginnt mit whsec_)

Für lokale Entwicklung:​

  1. Installiere die Stripe CLI: stripe.com/docs/stripe-cli
  2. Einmalig authentifizieren (bei Ablauf der Session wiederholen): 
    stripe login
  3. Starte den Webhook-Listener: 
    stripe listen --forward-to localhost:3000/api/stripe/webhook
  4. Verwende den generierten Webhook Secret für lokale Tests
hinweis

Die Stripe CLI verwendet eine eigene OAuth-Session, die unabhängig vom API-Key abläuft. Wenn stripe listen mit api_key_expired (401) fehlschlägt, einfach stripe login erneut ausführen.

4. Environment Variables konfigurieren​

Für Vercel Deployment:​

  1. Gehe zu deinem Vercel Dashboard
  2. Wähle dein Projekt → Settings → Environment Variables
  3. Füge folgende Variablen hinzu:
# Stripe API Keys
Name: STRIPE_SECRET_KEY
Value: sk_test_dein_secret_key_hier
Environment: Production, Preview, Development

Name: NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
Value: pk_test_dein_publishable_key_hier
Environment: Production, Preview, Development

# Stripe Webhook
Name: STRIPE_WEBHOOK_SECRET
Value: whsec_dein_webhook_secret_hier
Environment: Production, Preview, Development

# Trial-Preis-ID (Schreibweise "PROCUCT" beachten — so im Code verwendet)
Name: NEXT_PUBLIC_STRIPE_TRIAL_PROCUCT_PRICE_ID
Value: price_dein_trial_price_id_hier
Environment: Production, Preview, Development

Hinweis: Eine Variable STRIPE_PROFESSIONAL_PRICE_ID wird im Code nicht gelesen. Die einzige im Code referenzierte Preis-ID-Variable ist NEXT_PUBLIC_STRIPE_TRIAL_PROCUCT_PRICE_ID (siehe getStripeTrialProductPriceId() in lib/environment-handling.ts). Alle übrigen Produkte/Preise werden zur Laufzeit live aus der Stripe-API geladen (GET /api/stripe/get-all-products).

Für lokale Entwicklung (.env):​

Lokal lädt die App .env im Verzeichnis webapp/:

# Stripe API Keys
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Trial-Preis-ID (einzige im Code gelesene Preis-ID-Variable)
NEXT_PUBLIC_STRIPE_TRIAL_PROCUCT_PRICE_ID=price_...

5. Produkte und Preise erstellen​

  1. Gehe zu Products im Stripe Dashboard
  2. Erstelle ein Produkt:
    • Professional (€19.99/Monat) - für den 14-Tage Trial
  3. Für das Produkt:
    • Erstelle einen Recurring price mit monatlicher Abrechnung
    • Kopiere die Price ID (beginnt mit price_)

6. Produkte im Dashboard pflegen​

Produkte und Preise werden direkt aus Stripe geladen — es gibt keine hardcodierten Price IDs im Code. Der Endpoint GET /api/stripe/get-all-products ruft alle aktiven Produkte und Preise live ab, die PricingCards-Komponente rendert sie automatisch.

Damit ein Produkt korrekt dargestellt wird, müssen im Stripe Dashboard unter Metadata folgende Felder gesetzt sein:

KeyBeispielwertBedeutung
order1, 2, 3Sortierreihenfolge der Karten
populartrueHebt das Produkt als „Am beliebtesten" hervor
featuresUnbegrenzt Schüler, Alle FeaturesKommagetrennte Feature-Liste

Der Trial-Plan wird separat über die Umgebungsvariable NEXT_PUBLIC_STRIPE_TRIAL_PROCUCT_PRICE_ID konfiguriert (siehe Abschnitt 4).

7. Testen​

Für Vercel:​

  1. Deploye deine App auf Vercel
  2. Gehe zu /pricing um die Pricing-Seite zu testen
  3. Teste den Registrierungsprozess mit Kreditkartendaten
  4. Verwende die Stripe Test-Kartennummern:
    • Erfolgreiche Zahlung: 4242 4242 4242 4242
    • Fehlgeschlagene Zahlung: 4000 0000 0000 0002

Für lokale Entwicklung:​

  1. Starte deine Entwicklungsumgebung: pnpm dev
  2. Starte Stripe CLI: stripe listen --forward-to localhost:3000/api/stripe/webhook
  3. Gehe zu /pricing um die Pricing-Seite zu testen
  4. Teste den Registrierungsprozess

8. Webhook Events testen​

Von Stripe Dashboard:​

  1. Gehe zu Developers > Webhooks im Stripe Dashboard
  2. Klicke auf deinen Webhook
  3. Klicke auf "Send test webhook"
  4. Wähle ein Event aus (z.B. customer.subscription.created)
  5. Klicke auf "Send test webhook"

Mit Stripe CLI (lokal):​

# Test-Event senden
stripe trigger customer.subscription.created

9. Produktionsumgebung​

Für die Produktion:

  1. Wechsle zu Live mode im Stripe Dashboard
  2. Generiere neue Live API Keys
  3. Aktualisiere die Umgebungsvariablen in Vercel
  4. Stelle sicher, dass dein Webhook auf die Live-URL zeigt
  5. Teste alle Webhook-Events gründlich

Wichtige Hinweise​

  • Niemals deine Stripe Secret Keys im Frontend-Code verwenden
  • Verwende immer HTTPS in der Produktion
  • Für Vercel: Environment Variables müssen im Vercel Dashboard gesetzt werden
  • Für lokale Tests: Verwende .env (in webapp/) und die Stripe CLI
  • Teste alle Webhook-Events gründlich
  • Implementiere proper error handling für alle Stripe-API-Aufrufe
  • Überwache deine Stripe-Logs für fehlgeschlagene Webhooks
  • Subscription-Daten werden in der subscriptions-Tabelle gespeichert (nicht am User-Modell) — siehe Subscription-Datenmodell

Troubleshooting​

Webhook funktioniert nicht:​

  1. Überprüfe die Webhook-URL in Stripe
  2. Stelle sicher, dass alle Environment Variables in Vercel gesetzt sind
  3. Überprüfe die Vercel Function Logs
  4. Teste mit einem einfachen Event

Lokale Tests funktionieren nicht:​

  1. Stelle sicher, dass Stripe CLI läuft
  2. Überprüfe die .env Datei
  3. Verwende stripe listen für Webhook-Forwarding

stripe listen schlägt fehl mit „Expired API Key" (401):​

Die Stripe CLI verwendet eine eigene OAuth-Session, die unabhängig vom API-Key abläuft. Der Fehler sieht so aus:

FATAL Error while authenticating with Stripe: Authorization failed, status=401, body={
  "error": { "type": "api_error", "code": "api_key_expired", ... }
}

Lösung: CLI-Session neu authentifizieren:

stripe login

Dadurch öffnet sich der Browser zur Bestätigung. Danach funktioniert stripe listen wieder — der eigentliche API-Key in .env ist davon nicht betroffen.

Support​

Bei Problemen:

  1. Überprüfe die Stripe-Logs im Dashboard
  2. Überprüfe deine Vercel Function Logs
  3. Konsultiere die Stripe-Dokumentation
  4. Nutze den Stripe-Support