Stripe-Zahlungen hinzufügen

Schritt-für-Schritt für Einsteiger

Voraussetzungen: Die App läuft lokal (In 5 Minuten shippen) und eine migrierte Datenbank steht für echte Konten (Datenbank einrichten). Sie brauchen eine E-Mail-Adresse für das Stripe-Konto — keine Karte und keine Abbuchungen. Alles in diesem Guide passiert im Testmodus: Spielgeld, Testkartennummern, unbegrenzte Versuche vor dem Livegang.

Kurze Begriffe: Der Testmodus ist Stripes Sandbox — der Test-mode-Schalter im Dashboard hält jeden Key, jedes Produkt und jede Zahlung künstlich, bis Sie ihn ausschalten. Ein Secret Key (sk_test_…) ist das Passwort Ihres Servers bei Stripe. Ein Produkt mit einem Preis ist das, was Kunden kaufen; eine Price ID (price_…) benennt es im Code. Ein Webhook ist Stripe, das Ihren Server aufruft, wenn eine Zahlung gelingt oder ein Abo sich ändert; das Signing Secret (whsec_…) beweist, dass der Aufruf wirklich von Stripe kommt.

Was Sie erstellen: ein Stripe-Konto, ein Produkt mit wiederkehrendem Preis, einen geheimen API-Key und einen Webhook-Endpoint — etwa zwanzig Minuten. Stripe hostet die Checkout-Seite selbst; das Kit erzeugt die Session serverseitig und leitet weiter, darum ist kein publishable Browser-Key nötig.

Denken Sie an den Umfang: Dieser Guide verkauft nur Web-Abos. Käufe innerhalb der iOS-/Android-App müssen über Apple- und Google-Billing laufen — nie über Stripe Checkout — darum nutzt Mobile stattdessen RevenueCat.

• Die Datenbank einrichten
• RevenueCat für mobile Käufe einrichten

Das Stripe-Konto erstellen

1. Öffnen Sie stripe.com → Start now und melden Sie sich mit Ihrer E-Mail an.

2. Das Onboarding fragt nach Ihrem Geschäft — im Testmodus können Sie jede Frage überspringen und trotzdem die volle Sandbox nutzen; die Aktivierung vervollständigen Sie erst vor echten Zahlungen.

Erwartet: Sie landen im Dashboard mit dem Test-mode-Schalter im Header sichtbar. Lassen Sie ihn für alles Folgende an — Live-Keys gehören später in den Secret Store der Produktion, nie in eine Env-Datei auf dem Laptop.

Die API-Keys kopieren

1. Öffnen Sie im Dashboard Developers → API keys.

2. Sie sehen zwei Test-Keys: einen Publishable key pk_test_… und einen maskierten Secret key. Klicken Sie neben dem Secret auf Reveal test key und kopieren Sie den sk_test_…-Wert.

Das Kit braucht nur den Secret Key: Checkout-Sessions werden auf dem Server erzeugt und der Nutzer landet auf Stripes gehosteter Seite — kein Publishable Key landet in Env-Variablen. Baut ein Produkt später Stripe.js ein, käme der Publishable Key clientseitig zum Einsatz; der Billing-Flow des Kits nutzt ihn nicht.

Der sk_test_…-Key ist ein vollwertiges Credential für das Sandbox-Konto: Er liegt in apps/web/.env.local oder einem Secret Store, nie in NEXT_PUBLIC_-/EXPO_PUBLIC_-Variablen und nie in Git.

Produkt und Preis erstellen

1. Öffnen Sie Product catalog → Add product.

2. Benennen Sie es nach Ihrem Plan — Pro passt zum mitgelieferten Plan des Kits — geben Sie ihm einen Preis und wählen Sie Recurring (zum Beispiel monatlich): Das Checkout des Kits erzeugt Sessions im Abo-Modus, die einen wiederkehrenden Preis brauchen, keinen einmaligen.

3. Speichern Sie, öffnen Sie das Produkt und kopieren Sie die Price ID — sie beginnt mit price_… (nicht prod_…, das ist die Produkt-ID).

Der mitgelieferte pro-Plan zeigt bereits einen Monthly/Yearly-Umschalter: Monatlich bucht über STRIPE_PRICE_ID, und die jährliche Option braucht einen zweiten wiederkehrenden Preis in STRIPE_PRICE_ID_PRO_YEARLY — ohne ihn scheitert ein Jahres-Checkout mit price-unconfigured. Plan-Namen, Beträge und was ein Kauf gewährt ändern Sie in packages/web-core/src/product-plans.ts — Stripe speichert die Geldseite, die Plan-Datei die Entitlement-Seite.

Den Webhook-Endpoint hinzufügen

Der Webhook ist das, was Zugang tatsächlich gewährt: Das Kit schaltet das Entitlement erst, nachdem ein signiertes Stripe-Event angekommen ist — eine Checkout-Weiterleitung allein beweist nichts.

1. Öffnen Sie Developers → Webhooks → Add endpoint.

2. Endpoint URL: Ihre öffentliche URL plus /api/billing/webhook — zum Beispiel https://yourdomain.com/api/billing/webhook. Die anderen Billing-Anbieter bekommen eigene Pfade unter diesem Verzeichnis; Stripes Empfänger liegt an der Wurzel.

3. Wählen Sie unter Select events die Events, die das Kit behandelt: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated und customer.subscription.deleted.

4. Erstellen Sie den Endpoint, öffnen Sie seine Seite, klicken Sie unter Signing secret auf Reveal und kopieren Sie den whsec_…-Wert — jeder Endpoint hat sein eigenes Secret.

Lokale Entwicklung kann Stripes Server nicht erreichen, darum nutzen Sie stattdessen die Stripe CLI: einmal stripe login, dann stripe listen --forward-to localhost:3000/api/billing/webhook in einem zweiten Terminal. Sie gibt ein temporäres whsec_… aus — dieser Wert, nicht der aus dem Dashboard, gehört in .env.local, solange stripe listen läuft.

Die Werte in die App eintragen

Setzen Sie die Zeilen unten in apps/web/.env.local. BILLING_PROVIDER=stripe wählt den Adapter; die anderen drei sind Key, Preis und Signing Secret. Den Anbieter zu aktivieren, während einer davon fehlt, lässt den Start fehlschlagen und nennt die Variable.

Alle drei STRIPE_*-Werte bleiben serverseitig — nie NEXT_PUBLIC_/EXPO_PUBLIC_, nie committet; die Produktion bekommt sie über den Secret Manager des Hosts (der Deploy-Guide behandelt Secret Manager). Starten Sie den Dev-Server nach dem Bearbeiten neu.

# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_…   # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_…   # required for the shipped Yearly toggle

Prüfen und Fehler beheben

Starten Sie stripe listen --forward-to localhost:3000/api/billing/webhook und lassen Sie es laufen, starten Sie den Dev-Server neu, öffnen Sie dann /billing, wählen Sie den Pro-Plan und schließen Sie Stripes gehostetes Checkout mit der Testkarte 4242 4242 4242 4242, einem beliebigen zukünftigen Ablaufdatum und beliebigem CVC ab.

Erwartet: Die App kehrt zu /billing?checkout=success zurück und das Entitlement des Workspace springt auf aktiv — das Listen-Terminal protokolliert die zugestellten Events, und Developers → Webhooks → Ihr Endpoint im Dashboard zeigt grüne Zustellungen.

Um den Empfänger ohne Klick durchs Checkout zu testen, sendet stripe trigger checkout.session.completed ein synthetisches Event durch die Listen-Weiterleitung.

Typische Fehler: Ein 400 bei jeder Zustellung heißt, das Signing Secret passt nicht zu diesem Endpoint — kopieren Sie whsec_… für den richtigen Endpoint erneut und aktualisieren Sie die Env; stille Null-Effekte heißen, BILLING_PROVIDER ist noch local; und sk_live_-Keys in einem Test-Setup heißen, Sie haben Keys aus dem falschen Modus kopiert — halten Sie Test und Live strikt getrennt.

Das Kit liefert denselben Ein-Vertrag-Adapter für Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo und PayPal — gleicher Ablauf, andere Konsole und Env-Namen — und mobile Käufe bleiben bei RevenueCat, nicht Stripe.

• Die Billing-Anbieter vergleichen
• Als Nächstes Resend-E-Mail hinzufügen
• Mobile Käufe laufen über RevenueCat