For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /de/docs/web/stripe-payments.md (or send Accept: text/markdown).
Stripe-Zahlungen hinzufügen
Erstellen Sie ein kostenloses Stripe-Konto, ein Produkt mit wiederkehrendem Preis, einen Secret Key und den signierten Webhook, der Entitlements nach dem Checkout gewährt.
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.
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 apps/web/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 togglePrü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.