← Zurück zum Blog
TutorialVeröffentlicht 2026-04-28· 14 Min. Lesezeit

Stripe-Abonnements in Next.js: Anleitung 2026

WangNan, author at Uncorne
Veröffentlicht von Uncorne · Aktualisiert 2026-11-12

Dies ist der kürzeste Weg zu Stripe-Abonnements in Next.js, der in Produktion nicht kaputt geht. Vier bewegliche Teile, kein Beiwerk — plus die Verifikationsdetails, die die meisten Anleitungen weglassen.

Abo-Integrationen scheitern selten im Erfolgsfall. Ein Kunde klickt auf abonnieren, eine Checkout-Session wird erstellt, ein Webhook feuert, ein Flag in der Datenbank kippt. Das funktioniert in jedem Tutorial. Was scheitert, ist alles darum herum: ein gefälschter Webhook, der mit 200 bestätigt wird, ein wiederholtes Event, das zweimal angewendet wird, ein Plan, der nach der Kündigung nie zurückkippt, oder ein Geheimnis, das versehentlich in den Browser ausgeliefert wird. Dieser Leitfaden deckt die gesamte Schleife ab, einschließlich der Fehlerfälle.

Die vier beweglichen Teile eines Stripe-Abonnements in Next.js
Die vier beweglichen Teile eines Stripe-Abonnements in Next.js

Voraussetzungen

Drei Dinge, bevor Sie Code schreiben:

  • Ein Next.js-15-Projekt mit App Router. Wenn Sie neu beginnen, ist die App Router-Dokumentation die Referenz.
  • Ein Stripe-Konto im Testmodus mit Ihrem geheimen Schlüssel und einem Webhook-Signatur-Secret.
  • Eine users-Tabelle mit einer plan-Spalte oder eine separate subscriptions-Tabelle, in die Ihr Server schreiben kann.

Setzen Sie die Umgebungsvariablen einmal und halten Sie Test- und Live-Zugangsdaten in getrennten Umgebungen:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO=price_...
NEXT_PUBLIC_APP_URL=http://localhost:3000

Verwenden Sie für einen Stripe-Schlüssel niemals das Präfix NEXT_PUBLIC_. Alles mit diesem Präfix wird in das Browser-Bundle eingebettet und ist per Definition öffentlich. Ein geheimer Schlüssel im Client ist kein Shortcut, sondern ein veröffentlichtes Credential.

Schritt 1: Produkt und Preis anlegen

Erstellen Sie im Stripe-Dashboard ein Produkt mit einem wiederkehrenden Preis — zum Beispiel Pro für 12 USD pro Monat. Kopieren Sie die Price-ID in STRIPE_PRICE_ID_PRO. Codieren Sie sie niemals fest im Quellcode. Price-IDs unterscheiden sich zwischen Test- und Livemodus, daher ist ein fest codierter Testpreis ein stiller Produktionsfehler: Der Checkout sieht gut aus, aber Betrag oder Währung stimmen nicht.

Halten Sie eine kurze Zuordnung Ihrer Plannamen zu Price-IDs, damit regionale oder gestaffelte Preise eine Datenänderung statt einer Codeänderung sind. Modellieren Sie Pläne als Daten, nicht als Verzweigungen im Code. Ein PLANS-Objekt mit id, priceId und entitlements lässt das Feature-Gate eine Fähigkeit wie canExport oder seats prüfen statt eines Plannamens; das Umbenennen einer Stufe berührt dann keine Route. Jahresabrechnung wird dadurch ebenfalls einfach: Fügen Sie demselben Plan eine zweite Price-ID hinzu und lassen Sie die Checkout-Route sie aus einer validierten Anfrage wählen.

Ein Stripe-Dashboard-Produkt mit wiederkehrendem Preis und seiner Price-ID
Ein Stripe-Dashboard-Produkt mit wiederkehrendem Preis und seiner Price-ID

Schritt 2: SDK installieren und konfigurieren

Installieren Sie das offizielle Server-SDK mit npm install stripe. Instanzieren Sie einen Client auf Modulebene, damit die Initialisierung einmal geschieht:

import Stripe from "stripe";

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2025-02-24.acacia",
});

Pinning Sie die API-Version im Code, statt sie floaten zu lassen. Wenn Stripe eine neue Version veröffentlicht, wollen Sie das Changelog lesen und bewusst umsteigen, nicht eine Verhaltensänderung in Ihren Rechnungen entdecken.

Schritt 3: Die Checkout-Route

Eine POST /api/checkout-Route liest den gewünschten Plan, löst die Price-ID auf und erstellt eine Checkout-Session mit mode: "subscription", einer client_reference_id für Ihren Benutzer sowie expliziten success_url und cancel_url. Geben Sie die gehostete URL an den Browser zurück. Bauen Sie kein eigenes Zahlungsformular, bevor Sie einen konkreten Grund dafür haben.

Fordern Sie einen angemeldeten Benutzer, bevor Sie die Session erstellen. Guest-Checkout hinterlässt niemanden, dem die Berechtigung gewährt werden kann: Der Webhook gewährt Zugriff nach Benutzer-ID oder Zahlungs-E-Mail, und wenn keines davon zu einem Konto passt, hat die Lizenz keinen Eigentümer. Lesen Sie die Session im Route Handler aus cookies, nicht aus einer vom Client gelieferten Benutzer-ID.

export async function POST(req: Request) {
  const user = await getSessionUser();           // serverseitig, aus cookies
  if (!user) return Response.json({ error: "unauthorized" }, { status: 401 });

  const { plan } = await req.json();
  const priceId = PLANS[plan]?.priceId;          // aus der Env, nie vom Client
  if (!priceId) return Response.json({ error: "bad plan" }, { status: 400 });

  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: priceId, quantity: 1 }],
    client_reference_id: user.id,
    customer_email: user.email,
    success_url: `${APP_URL}/billing?status=success`,
    cancel_url: `${APP_URL}/billing?status=cancel`,
  });

  return Response.json({ url: session.url });
}

Zwei Details zählen. Der Preis kommt aus Ihrer Umgebung, niemals aus dem Request-Body — sonst kann ein Client Ihren Enterprise-Preis für einen Dollar wählen. Und beide URLs sind explizit; sich auf Defaults zu verlassen schickt Benutzer nach der Zahlung auf eine Stripe-eigene Seite. Die vollständigen Session-Optionen stehen in der Checkout-Sessions-API-Referenz.

Ein Checkout-Session-Ablauf von einem angemeldeten Benutzer zu einer von Stripe gehosteten Zahlungsseite
Ein Checkout-Session-Ablauf von einem angemeldeten Benutzer zu einer von Stripe gehosteten Zahlungsseite

Schritt 4: Der Webhook ist die Quelle der Wahrheit

Der Browser ist nicht vertrauenswürdig. Ein Client, der „Zahlung erfolgreich" behauptet, beweist nichts. Der von Stripe signierte Webhook ist das maßgebliche Signal. Verifizieren Sie den Roh-Body gegen den Stripe-Signature-Header, bevor Sie JSON parsen:

export async function POST(req: Request) {
  const sig = req.headers.get("stripe-signature");
  if (!sig) return new Response("missing signature", { status: 400 });

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      await req.text(),                  // exakte Roh-Bytes
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch {
    return new Response("invalid signature", { status: 400 });
  }

  if (await alreadyProcessed(event.id)) return new Response(null, { status: 200 });
  await markProcessed(event.id);

  switch (event.type) {
    case "checkout.session.completed":
      await grantPlan(event.data.object.client_reference_id, "pro");
      break;
    case "customer.subscription.deleted":
      await revokePlan(event.data.object.metadata.userId);
      break;
  }
  return new Response(null, { status: 200 });
}

Zuerst zu parsen und dann neu zu serialisieren verändert die Bytes und bricht die HMAC-Prüfung. Ein Verifikationsfehler — fehlender Header, schlechter HMAC, fehlerhaftes JSON — muss eine Ausnahme werfen und HTTP 400 liefern. Eine gefälschte Anfrage mit 200 zu bestätigen ist ein Sicherheitsfehler, kein harmloser No-op. Das Signaturschema ist in Webhook-Signaturverifikation erklärt, der vollständige Katalog unter Webhook-Eventtypen.

Ein ignoriertes Event ist etwas anderes als ein fehlgeschlagenes. Ein korrekt signiertes Event, das Sie nicht behandeln, sollte protokolliert und mit 200 plus „ignored"-Flag beantwortet werden. Verwenden Sie 200-ignored niemals für Verifikationsfehler.

Verifikation des rohen Webhook-Body gegen den Signatur-Header vor dem JSON-Parsing
Verifikation des rohen Webhook-Body gegen den Signatur-Header vor dem JSON-Parsing

Schritt 5: Den Webhook idempotent machen

Stripe versucht Webhooks erneut. Ohne Replay-Schutz wird eine Zahlung zu zwei Upgrades und eine Kündigung zur Phantom-Erstattung. Speichern Sie verarbeitete Event-IDs in einer Tabelle mit einer Unique-Constraint auf event_id, und fügen Sie vor dem Anwenden der Wirkung ein:

create table processed_events (
  event_id text primary key,
  received_at timestamptz not null default now()
);

Der Insert selbst ist die Sperre: Wenn ein paralleler Retry dieselbe ID verwendet, sagt Ihnen der Primärschlüsselkonflikt, dass Sie überspringen sollen. Führen Sie Prüfen-und-Markieren in einem einzigen atomaren Schritt aus statt als Lesen gefolgt von Schreiben, was ein Race-Fenster lässt. Hängen Sie userId bei der Session-Erstellung an die Abonnement-Metadaten, damit das Kündigungs-Event das richtige Konto ohne E-Mail-Suche findet.

Ein Punkt, den Sie in jedem Starter vorab prüfen sollten: Behandelt er den Kündigungs-Webhook überhaupt? Viele Templates behandeln nur checkout.session.completed und vergessen customer.subscription.deleted, sodass Kunden nach der Kündigung dauerhaft Zugriff behalten. Suchen Sie im Code nach beiden Eventtypen. Ist nur einer vorhanden, ergänzen Sie den anderen, bevor Sie die erste Zahlung annehmen.

Ein Idempotenz-Log, das jede Event-ID genau einmal anwendet
Ein Idempotenz-Log, das jede Event-ID genau einmal anwendet

Schritt 6: Das Feature-Gate

Lesen Sie auf jeder geschützten Route und jeder Server Action den Plan aus der Datenbank — niemals aus Client-State und niemals aus einem Cookie, das Sie nach dem Checkout gesetzt haben. Ist der Plan inaktiv, geben Sie 402 zurück. Ihr KI-Endpunkt, der ZIP-Download und Sitzplatzlimits hängen alle an dieser einen Prüfung:

export async function requirePro() {
  const user = await getSessionUser();
  if (!user) throw new HttpError(401);
  const { data } = await supabase
    .from("profiles")
    .select("plan")
    .eq("id", user.id)
    .single();
  if (data?.plan !== "pro") throw new HttpError(402, "Upgrade required");
}

Eine clientseitige Prüfung, die einen Button versteckt, ist UX, keine Sicherheit. Die Serverseite zählt. Wenn Sie das in einer Server Action statt in einem Route Handler machen, gilt dieselbe Regel; die Server-Actions-Dokumentation zeigt, wie Sie die Mutation auf dem Server halten.

Ein serverseitiges Feature-Gate, das bei inaktivem Plan 402 zurückgibt
Ein serverseitiges Feature-Gate, das bei inaktivem Plan 402 zurückgibt

Schritt 7: Kunden verwalten und kündigen lassen

Ein Kundenportal erspart Ihnen bei jeder Kündigung ein Support-Ticket. Erstellen Sie serverseitig eine Billing-Portal-Session und leiten Sie den Benutzer dorthin weiter. Das Portal übernimmt Kartenupdates, Planwechsel und Kündigungen, und Stripe sendet die passenden Webhooks, sodass Ihre Datenbank ohne zusätzlichen Code synchron bleibt. Die anteilige Abrechnung bei Wechsel innerhalb der Periode wird dort ebenfalls für Sie berechnet — rechnen Sie das nicht selbst aus Timestamps.

Schritt 8: Die gesamte Schleife testen

Nutzen Sie den Testmodus und die Karte 4242 4242 4242 4242 mit einem beliebigen zukünftigen Verfallsdatum und beliebiger CVC:

  1. Checkout abschließen; bestätigen Sie, dass der Plan in der Datenbank kippt.
  2. Im Portal kündigen; bestätigen Sie, dass er zurückkippt.
  3. Ein erfasstes checkout.session.completed-Event erneut senden; bestätigen Sie, dass es nur einmal angewendet wird.
  4. Ein Webhook mit beschädigter Signatur senden; bestätigen Sie 400, nicht 200.
  5. Einen Pro-Endpunkt als Free-User aufrufen; bestätigen Sie 402.

Für lokale Zustellung leiten Sie Stripe-Events mit der Stripe-CLI weiter (stripe listen --forward-to localhost:3000/api/webhooks) und kopieren Sie das ausgegebene Signatur-Secret in STRIPE_WEBHOOK_SECRET. Wenn Ihre CI bereits Previews deployt, ist das Testen gegen eine deployte Preview-URL mit eigenem Webhook-Endpoint und eigenem Secret sauberer.

Wenn die Schleife mit einer Env-Datei funktioniert, ist Ihre Abrechnung echt. Wenn ein Schritt eine manuelle Datenbankänderung zum „Fertigstellen" braucht, ist er nicht fertig.

Eine Testschleife mit Testkarte, Replay, fehlerhafter Signatur und 402-Prüfung
Eine Testschleife mit Testkarte, Replay, fehlerhafter Signatur und 402-Prüfung

Häufige Fehlerbilder

| Symptom | Wahrscheinliche Ursache | Korrektur | | --- | --- | --- | | 400 bei jedem Webhook | Falsches Signatur-Secret oder Body vor Verifikation geparst | Roh-Body und Secret des passenden Endpoints verwenden | | Plan kippt nie | Event behandelt, aber client_reference_id leer | Anmeldung vor Session-Erstellung verlangen | | Plan kippt zweimal | Keine Idempotenz bei Event-IDs | event_id-Eindeutigkeitstabelle, atomischer Insert vor Wirkung | | Checkout lokal, aber nicht in Produktion | Test-Key oder Test-Price-ID in der Prod-Env | Test und Live trennen, Keys beim Start validieren | | Gate lässt Free-User durch | Client-State als Quelle der Wahrheit | Plan bei jeder Anfrage aus der Datenbank lesen |

Wo ein Boilerplate hilft

Ein guter Boilerplate liefert Ihnen die Schritte 3–6 bereits verdrahtet und hält sie hinter einer anbieterunabhängigen Schnittstelle. Das zählt in dem Moment, in dem Sie für eine neue Region Creem, PayPal, Waffo oder Lemon Squeezy hinzufügen: Sie schreiben einen neuen Adapter statt Checkout- und Webhook-Logik in der ganzen Anwendung neu zu schreiben. Uncorne liefert fünf Provider-Adapter hinter einem Checkout- und Webhook-Vertrag, mit dem Stripe-Pfad oben als Referenzimplementierung.

Die Verifikationsregeln ändern sich nicht mit dem Anbieter. Verifizieren Sie die Signatur auf Roh-Bytes, deduplizieren Sie Event-IDs, schreiben Sie nur vom Server aus und halten Sie das Feature-Gate serverseitig. Lernen Sie sie zuerst mit Stripe; sie übertragen sich direkt. Die tiefere architektonische Begründung steht in wie man einen SaaS mit Next.js baut.

Die ehrliche Zusammenfassung

Stripe-Abonnements in Next.js sind vier bewegliche Teile: ein Produkt und Preis im Dashboard, eine Checkout-Route, die einen angemeldeten Benutzer verlangt, ein Webhook, der vor dem Parsen verifiziert und vor dem Schreiben dedupliziert, sowie ein serverseitiges Plan-Gate. Machen Sie diese vier richtig, und der Erfolgsfall wird fast langweilig — genau das wollen Sie von einer Abrechnung. Alles andere, von regionaler Preisgestaltung bis zum zweiten Gateway, ist nur ein Adapter über dieser Schleife.

FAQ

Soll ich den Webhook-Body vor der Verifikation parsen?+

Nein. Verifizieren Sie zuerst die exakten Roh-Bytes gegen den Stripe-Signature-Header und parsen Sie dann. Zuerst zu parsen und neu zu serialisieren verändert die Bytes und bricht die HMAC-Prüfung, die 400 liefern sollte.

Warum funktioniert die Berechtigung beim Guest-Checkout nicht?+

Der Webhook gewährt Zugriff nach Benutzer-ID oder Zahlungs-E-Mail. Wenn niemand angemeldet ist und die E-Mail zu keinem Konto passt, hat die Lizenz keinen Eigentümer. Verlangen Sie die Anmeldung vor der Erstellung der Checkout-Session.

Was bedeutet eine ignorierte Webhook-Antwort?+

Ein 200 mit ignored-Flag bedeutet, dass das Event korrekt signiert, aber nicht eines der von Ihnen behandelten ist. Es darf niemals für Verifikationsfehler verwendet werden, die 400 sind. Protokollieren Sie ignorierte Events, um sie von Fehlern zu unterscheiden.

Wie verhindere ich, dass ein wiederholter Webhook einen Nutzer zweimal hochstuft?+

Speichern Sie verarbeitete Event-IDs mit einer Unique-Constraint auf event_id und fügen Sie die ID atomisch ein, bevor Sie die Wirkung anwenden. Bei einem Retry sagt Ihnen der Primärschlüsselkonflikt, dass Sie überspringen sollen. Lesen-dann-Schreiben lässt ein Race-Fenster.

Sollte ich Stripe Checkout oder das eingebettete Zahlungselement nutzen?+

Beginnen Sie mit gehostetem Checkout: Das ist der kürzeste Weg zu Abonnements, und Stripe hostet die Zahlungs-UI. Wechseln Sie zum eingebetteten Element erst, wenn Sie die Zahlungserfahrung in Ihrer eigenen Seite steuern müssen. Die Webhook-Logik ist in beiden Fällen identisch.

Alle häufigen Fragen · Markdown-Version (für KI-Agenten)