Next.js & Stripe: Die ultimative Anleitung zur Abfrage, ob Ihr Stripe Checkout erfolgreich war

Sie haben also eine tolle E-Commerce-Anwendung mit Next.js erstellt und Stripe integriert, um Zahlungen zu akzeptieren. Herzlichen Glückwunsch! Aber was passiert, nachdem ein Kunde bezahlt hat? Wie können Sie zuverlässig feststellen, ob der Stripe Checkout erfolgreich war und die entsprechenden Maßnahmen ergreifen, z. B. die Bestellung erfüllen, den Benutzer benachrichtigen und die Datenbank aktualisieren?

Diese Anleitung führt Sie Schritt für Schritt durch die Implementierung einer robusten Strategie zur Überprüfung des Stripe Checkout-Erfolgs in Ihrer Next.js-Anwendung. Wir werden uns mit verschiedenen Ansätzen befassen, von der clientseitigen Überprüfung bis hin zu den empfohlenen serverseitigen Webhooks, um sicherzustellen, dass Ihre Anwendung Zahlungsinformationen korrekt verarbeitet und potenzielle Fehlerquellen vermeidet.

Warum ist die Überprüfung des Stripe Checkout-Erfolgs so wichtig?

Die Überprüfung des Stripe Checkout-Erfolgs ist mehr als nur eine Formsache; sie ist das Herzstück eines reibungslosen und vertrauenswürdigen E-Commerce-Erlebnisses. Ohne sie riskieren Sie:

• Unerfüllte Bestellungen: Ein Kunde bezahlt, aber Sie wissen nichts davon und versenden die Ware nicht.
• Falsche Bestandsverwaltung: Sie reduzieren den Lagerbestand nicht, obwohl eine Bestellung aufgegeben wurde.
• Schlechte Benutzererfahrung: Kunden bleiben im Unklaren über den Status ihrer Bestellung, was zu Frustration und potenziellen Rückerstattungsanträgen führt.
• Sicherheitslücken: Wenn Sie den Erfolg nicht ordnungsgemäß überprüfen, könnten böswillige Benutzer versuchen, Bestellungen zu simulieren oder Zahlungen zu manipulieren.

Clientseitige Überprüfung (mit Vorsicht)

Der einfachste Ansatz besteht darin, den Erfolg auf der Clientseite zu überprüfen, direkt im Browser des Benutzers. Stripe stellt dafür das stripe.confirmPayment– oder stripe.confirmCardPayment-Methoden zur Verfügung. Nachdem der Benutzer die Zahlung autorisiert hat, können Sie den Status des PaymentIntent überprüfen.

Hier ist ein Beispiel:

import { loadStripe } from '@stripe/stripe-js';
import { useEffect } from 'react';

const CheckoutSuccess = () => {
  useEffect(() => {
    const stripePromise = loadStripe('YOUR_STRIPE_PUBLIC_KEY');

    const checkPaymentStatus = async () => {
      const stripe = await stripePromise;

      const clientSecret = new URLSearchParams(window.location.search).get(
        'payment_intent_client_secret'
      );

      if (!clientSecret) {
        return;
      }

      const { error, paymentIntent } = await stripe.retrievePaymentIntent(clientSecret);

      if (error) {
        console.error('Fehler beim Abrufen des PaymentIntent:', error);
        // Fehlerbehandlung
      } else {
        if (paymentIntent.status === 'succeeded') {
          console.log('Zahlung erfolgreich!');
          // Hier können Sie die Benutzererfahrung aktualisieren, z. B. eine Erfolgsmeldung anzeigen.
        } else {
          console.log('Zahlung noch nicht erfolgreich:', paymentIntent.status);
          //  Status wie "processing" behandeln
        }
      }
    };

    checkPaymentStatus();
  }, []);

  return (
    <div>
      <h1>Zahlungsstatus</h1>
      <p>Überprüfen Sie den Zahlungsstatus...</p>
    </div>
  );
};

export default CheckoutSuccess;

Wichtiger Hinweis: Verwenden Sie die clientseitige Überprüfung NUR für die Benutzeroberfläche. Verlassen Sie sich niemals ausschließlich auf sie, um Ihre Bestellungen auszuführen oder Ihre Datenbank zu aktualisieren. Die clientseitige Überprüfung kann leicht manipuliert werden, was zu Problemen mit der Datensicherheit führt. Sie ist nützlich, um dem Benutzer sofortiges Feedback zu geben, aber die eigentliche Validierung muss auf dem Server erfolgen.

Serverseitige Überprüfung mit Webhooks (die empfohlene Methode)

Die zuverlässigste Methode zur Überprüfung des Stripe Checkout-Erfolgs ist die Verwendung von Stripe Webhooks. Webhooks sind HTTP-Callbacks, die Stripe an Ihre Anwendung sendet, wenn bestimmte Ereignisse auftreten, z. B. wenn eine Zahlung erfolgreich war oder fehlgeschlagen ist. Dies ermöglicht es Ihrer Anwendung, in Echtzeit auf Zahlungsereignisse zu reagieren, ohne ständig die Stripe-API abfragen zu müssen.

Schritt 1: Einen Webhook-Endpunkt in Next.js erstellen

Erstellen Sie in Ihrem Next.js-Projekt eine API-Route, die als Ihr Webhook-Endpunkt dient. Dies könnte beispielsweise unter /pages/api/webhook.js liegen.

import Stripe from 'stripe';
import { buffer } from 'micro';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export const config = {
  api: {
    bodyParser: false,
  },
};

export default async function handler(req, res) {
  if (req.method === 'POST') {
    const buf = await buffer(req);
    const sig = req.headers['stripe-signature'];

    let event;

    try {
      event = stripe.webhooks.constructEvent(buf, sig, process.env.STRIPE_WEBHOOK_SECRET);
    } catch (err) {
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    if (event.type === 'checkout.session.completed') {
      const session = event.data.object;

      // Hier kommt Ihre Logik zur Auftragsabwicklung!
      // Zugriff auf session.metadata zum Abrufen von Auftragsinformationen.
      // Aktualisieren Sie Ihre Datenbank, erfüllen Sie die Bestellung usw.
      console.log('Checkout Session abgeschlossen:', session);

      try {
        // Logik zur Auftragserfüllung
        await fulfillOrder(session);
        res.status(200).json({ received: true });
      } catch (error) {
        console.error("Fehler bei der Auftragserfüllung:", error);
        return res.status(500).send('Fehler bei der Auftragserfüllung');
      }

    } else {
      res.status(200).json({ received: true });
    }
  } else {
    res.setHeader('Allow', 'POST');
    res.status(405).end('Method Not Allowed');
  }
}

async function fulfillOrder(session) {
    // Hier Ihre Auftragsabwicklungslogik
    // Beispiel: Datenbank aktualisieren, E-Mail senden usw.
    console.log("Auftrag für Session erfüllt:", session.id);

    // Annahme, dass Ihre Bestelldaten in session.metadata enthalten sind
    const orderId = session.metadata.orderId;

    // TODO:  Abrufen der Bestellinformationen aus der Datenbank anhand der orderId
    // TODO:  Aktualisieren Sie den Bestellstatus in der Datenbank auf "erfüllt"

    //TODO: Senden einer Bestätigungs-E-Mail an den Kunden.
}

Erläuterung:

• stripe.webhooks.constructEvent: Diese Funktion von Stripe ist entscheidend. Sie verifiziert, dass der Webhook tatsächlich von Stripe stammt und nicht von einem Angreifer. Sie verwendet Ihr STRIPE_WEBHOOK_SECRET, um die Signatur zu validieren.
• checkout.session.completed: Dies ist der Webhook-Ereignistyp, der ausgelöst wird, wenn ein Checkout erfolgreich abgeschlossen wurde.
• session.metadata: Hier können Sie zusätzliche Informationen über die Bestellung speichern, wenn Sie die Checkout-Sitzung erstellen (z. B. die Bestell-ID). Dadurch können Sie die Bestellung später leichter zuordnen.
• fulfillOrder: Dies ist die Funktion, in der Sie Ihre eigentliche Logik zur Auftragsabwicklung implementieren. Dies beinhaltet das Aktualisieren Ihrer Datenbank, das Reduzieren des Lagerbestands, das Senden von E-Mails usw.
• bodyParser: false: Stripe sendet Webhook-Daten als rohen Body. Daher müssen wir den Next.js-Body-Parser deaktivieren.

Schritt 2: Webhook in Stripe einrichten

Sie müssen Stripe mitteilen, an welche URL Ihre Webhooks gesendet werden sollen. Gehen Sie zum Stripe-Dashboard, navigieren Sie zum Abschnitt „Entwickler” -> „Webhooks” und klicken Sie auf „Endpunkt hinzufügen”.

• Endpunkt-URL: Geben Sie die vollständige URL zu Ihrer API-Route an (z. B. https://your-domain.com/api/webhook).
• Ereignisse auswählen: Wählen Sie mindestens das Ereignis „checkout.session.completed” aus. Sie können auch andere relevante Ereignisse auswählen, wie z. B. „checkout.session.async_payment_succeeded”, „checkout.session.async_payment_failed” oder „payment_intent.succeeded”.

Nach dem Speichern Ihres Webhook-Endpunkts zeigt Stripe ein Webhook-Signierungsgeheimnis an. Dies ist der Wert, den Sie als STRIPE_WEBHOOK_SECRET in Ihren Umgebungsvariablen speichern müssen. Dieses Geheimnis wird verwendet, um die Authentizität der von Stripe gesendeten Webhooks zu überprüfen.

Schritt 3: .env-Datei konfigurieren

Stellen Sie sicher, dass Ihre .env.local-Datei die folgenden Umgebungsvariablen enthält (ersetzen Sie die Platzhalter durch Ihre tatsächlichen Werte):

STRIPE_SECRET_KEY=sk_live_your_stripe_secret_key
STRIPE_PUBLIC_KEY=pk_live_your_stripe_public_key
STRIPE_WEBHOOK_SECRET=whsec_your_stripe_webhook_secret

Zusätzliche Überlegungen

• Fehlerbehandlung: Implementieren Sie eine robuste Fehlerbehandlung in Ihrem Webhook-Endpunkt. Protokollieren Sie Fehler, versuchen Sie, fehlgeschlagene Aufträge wiederherzustellen, und benachrichtigen Sie sich selbst über Probleme.
• Idempotenz: Webhooks können manchmal mehrmals gesendet werden. Implementieren Sie eine Idempotenz-Strategie, um sicherzustellen, dass Sie einen Auftrag nur einmal verarbeiten, selbst wenn Sie den gleichen Webhook mehrmals erhalten. Dies kann durch Verfolgen der bereits verarbeiteten Webhook-IDs in Ihrer Datenbank erfolgen.
• Sicherheit: Schützen Sie Ihre Webhook-Endpunkte. Stellen Sie sicher, dass nur Stripe Anfragen an sie senden kann. Verwenden Sie das Webhook-Signierungsgeheimnis, um jede Anfrage zu überprüfen.
• Testen: Testen Sie Ihre Webhook-Integration gründlich. Verwenden Sie die Stripe-CLI, um Webhooks lokal zu simulieren, oder verwenden Sie das Stripe-Dashboard, um Webhooks manuell auszulösen.
• Asynchrone Zahlungen: Berücksichtigen Sie Szenarien wie SEPA oder Banküberweisungen, die eine asynchrone Bestätigung erfordern können. Hören Sie auf Webhooks wie checkout.session.async_payment_succeeded und checkout.session.async_payment_failed, um diese Fälle abzudecken.

Fazit

Die zuverlässige Überprüfung des Stripe Checkout-Erfolgs ist entscheidend für den Betrieb eines erfolgreichen E-Commerce-Geschäfts mit Next.js. Obwohl die clientseitige Überprüfung für unmittelbares Feedback nützlich sein kann, ist die serverseitige Überprüfung mit Stripe Webhooks der Goldstandard. Durch die Implementierung einer robusten Webhook-basierten Strategie können Sie sicherstellen, dass Ihre Anwendung Zahlungsinformationen genau verarbeitet, Bestellungen zuverlässig erfüllt und Ihren Kunden ein reibungsloses und vertrauenswürdiges Erlebnis bietet.