Stripe ist einer der beliebtesten Payment Provider für E-Commerce-Anwendungen. In diesem Tutorial zeige ich dir, wie du Stripe nahtlos in deine MedusaJS-Anwendung integrierst und Zahlungen verarbeitest.

Warum Stripe mit MedusaJS?

Stripe bietet eine robuste, sichere und benutzerfreundliche Lösung für die Zahlungsabwicklung. Die Integration mit MedusaJS ermöglicht es dir:

  • Kreditkartenzahlungen zu akzeptieren
  • Alternative Zahlungsmethoden wie Bancontact, iDEAL, giropay und mehr anzubieten
  • Automatische Zahlungsabwicklung mit Webhooks
  • Gespeicherte Zahlungsmethoden für wiederkehrende Kunden zu unterstützen
  • Apple Pay und Google Pay zu integrieren

Voraussetzungen

Bevor wir mit der Integration beginnen, stelle sicher, dass du:

  1. Eine funktionierende MedusaJS-Anwendung hast (siehe MedusaJS Setup Tutorial)
  2. Ein Stripe-Konto besitzt - Registrierung
  3. Zugriff auf deine Stripe API Keys hast

Stripe API Keys abrufen

  1. Logge dich in dein Stripe Dashboard ein
  2. Navigiere zu Developers > API keys
  3. Du findest dort:
    • Publishable key (beginnt mit pk_test_ oder pk_live_)
    • Secret key (beginnt mit sk_test_ oder sk_live_)

Wichtig: Für die Entwicklung verwende die Test Keys (mit _test_). Für Production benötigst du die Live Keys (mit _live_).

Schritt 1: Stripe Module Provider registrieren

Der Stripe Module Provider ist standardmäßig in deiner Medusa-Anwendung installiert. Um ihn zu aktivieren, musst du ihn in der Konfigurationsdatei registrieren.

medusa-config.ts anpassen

Öffne die medusa-config.ts Datei in deinem Medusa-Projekt und füge den Stripe Module Provider hinzu:

module.exports = defineConfig({
  // ... andere Konfigurationen
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/payment-stripe",
            id: "stripe",
            options: {
              apiKey: process.env.STRIPE_API_KEY,
            },
          },
        ],
      },
    },
  ],
})

Wichtig: Auch wenn das Payment Module standardmäßig geladen wird, musst du es erneut in der modules-Array hinzufügen, wenn du einen neuen Provider registrierst.

Erweiterte Konfigurationsoptionen

Der Stripe Module Provider unterstützt weitere Optionen:

{
  resolve: "@medusajs/medusa/payment-stripe",
  id: "stripe",
  options: {
    apiKey: process.env.STRIPE_API_KEY,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET, // Für Production
    automaticPaymentMethods: true, // Für Apple Pay, Google Pay
    capture: true, // Automatische Zahlungserfassung
    paymentDescription: "Bestellung bei meinem Shop", // Standard-Beschreibung
  },
}

Optionen im Detail:

  • apiKey (erforderlich): Dein Stripe Secret API Key
  • webhookSecret (optional, für Production): Webhook Secret für sichere Webhook-Verarbeitung
  • automaticPaymentMethods (optional): Aktiviert automatische Zahlungsmethoden wie Apple Pay und Google Pay
  • capture (optional): Ob Zahlungen automatisch erfasst werden sollen (Standard: false)
  • paymentDescription (optional): Standard-Beschreibung für Zahlungen

Schritt 2: Environment Variables setzen

Füge deine Stripe API Keys zur .env Datei hinzu:

STRIPE_API_KEY=sk_test_51J...

Für Production füge auch das Webhook Secret hinzu:

STRIPE_API_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

Sicherheitshinweis: Stelle sicher, dass deine .env Datei in .gitignore enthalten ist und niemals in dein Repository committed wird!

Schritt 3: Stripe in einer Region aktivieren

Nach der Konfiguration musst du Stripe als Zahlungsanbieter in mindestens einer Region aktivieren. Kunden können nur Zahlungsmethoden verwenden, die in ihrer Region verfügbar sind.

Über das Admin Dashboard

  1. Starte deine Medusa-Anwendung:
npm run dev
  1. Öffne das Admin Dashboard unter http://localhost:9000/app
  2. Logge dich mit deinem Admin-Account ein
  3. Navigiere zu Settings > Regions
  4. Klicke auf die Region, in der du Stripe aktivieren möchtest
  5. Klicke auf das Bearbeiten-Icon (oben rechts im ersten Abschnitt)
  6. Im sich öffnenden Seitenfenster findest du das Feld “Payment Providers”
  7. Wähle “Stripe (STRIPE)” aus dem Dropdown-Menü
  8. Klicke auf “Save”

Stripe ist jetzt als Zahlungsoption im Checkout verfügbar!

Schritt 4: Verfügbare Stripe-Zahlungsmethoden

Der Stripe Module Provider registriert verschiedene Zahlungsanbieter. Jeder Provider hat eine eindeutige ID im Format {provider_id}_{module_id}.

Wenn du die Stripe Module Provider ID auf "stripe" gesetzt hast, werden folgende Provider registriert:

Provider Name Provider ID
Basic Stripe Payment stripe_stripe
Bancontact Payments bancontact_stripe
BLIK Payments blik_stripe
giropay Payments giropay_stripe
iDEAL Payments ideal_stripe
Przelewy24 Payments przelewy24_stripe
PromptPay Payments promptpay_stripe

Du kannst jeden dieser Provider separat in deinen Regionen aktivieren, je nachdem, welche Zahlungsmethoden du anbieten möchtest.

Schritt 5: Webhooks für Production konfigurieren

Für Production-Anwendungen ist es essentiell, Stripe Webhooks einzurichten. Webhooks informieren deine Medusa-Anwendung über Änderungen und Updates zu Zahlungen, die asynchron verarbeitet werden.

Warum Webhooks wichtig sind

Webhooks sind wichtig, wenn:

  • Zahlungen asynchron verarbeitet werden
  • Zahlungen auf der Stripe-Seite verwaltet werden
  • Der Checkout-Prozess unterbrochen wurde und die Zahlung trotzdem verarbeitet wurde

Webhook URL

Die Webhook-URL für MedusaJS folgt diesem Format:

https://deine-domain.com/hooks/payment/{provider_id}/stripe

Für die Standard-Stripe-Zahlung wäre die URL:

https://deine-domain.com/hooks/payment/stripe_stripe/stripe

Für verschiedene Zahlungsmethoden:

Stripe Payment Type Webhook Endpoint URL
Basic Stripe Payment /hooks/payment/stripe_stripe/stripe
Bancontact Payments /hooks/payment/bancontact_stripe/stripe
BLIK Payments /hooks/payment/blik_stripe/stripe
giropay Payments /hooks/payment/giropay_stripe/stripe
iDEAL Payments /hooks/payment/ideal_stripe/stripe
Przelewy24 Payments /hooks/payment/przelewy24_stripe/stripe
PromptPay Payments /hooks/payment/promptpay_stripe/stripe

Webhook in Stripe einrichten

  1. Gehe zu deinem Stripe Dashboard
  2. Navigiere zu Developers > Webhooks
  3. Klicke auf “Add endpoint”
  4. Gib deine Webhook-URL ein (z.B. https://deine-domain.com/hooks/payment/stripe_stripe/stripe)
  5. Wähle die folgenden Events aus:
    • payment_intent.succeeded
    • payment_intent.payment_failed
    • charge.succeeded
    • charge.failed (seit Medusa v2.8.5)
  6. Klicke auf “Add endpoint”
  7. Kopiere das Webhook Secret (beginnt mit whsec_)
  8. Füge es zu deiner .env Datei hinzu:
STRIPE_WEBHOOK_SECRET=whsec_...
  1. Aktualisiere deine medusa-config.ts:
{
  resolve: "@medusajs/medusa/payment-stripe",
  id: "stripe",
  options: {
    apiKey: process.env.STRIPE_API_KEY,
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  },
}

Webhook lokal testen

Für lokale Tests kannst du Stripe CLI verwenden:

# Stripe CLI installieren
# Dann Webhook weiterleiten
stripe listen --forward-to localhost:9000/hooks/payment/stripe_stripe/stripe

Die CLI zeigt dir ein Webhook Secret an, das du für lokale Tests verwenden kannst.

Schritt 6: Storefront-Integration

Wenn du ein eigenes Storefront entwickelst (z.B. mit Next.js), benötigst du auch den Stripe Publishable Key.

Environment Variable im Storefront

Füge den Publishable Key zu deinen Storefront-Umgebungsvariablen hinzu:

# Next.js Storefront
NEXT_PUBLIC_STRIPE_KEY=pk_test_...

# Oder für andere Frameworks
STRIPE_PUBLISHABLE_KEY=pk_test_...

Wichtig: Der Publishable Key kann sicher im Frontend verwendet werden, da er nur für die Initialisierung von Stripe-Elementen verwendet wird.

Erweiterte Features

Gespeicherte Zahlungsmethoden

Der Stripe Module Provider unterstützt gespeicherte Zahlungsmethoden. Kunden können ihre Zahlungsinformationen speichern und bei zukünftigen Bestellungen wiederverwenden.

Die Implementierung erfordert zusätzliche Anpassungen im Storefront. Weitere Details findest du in der offiziellen Medusa-Dokumentation.

Apple Pay und Google Pay

Um Apple Pay und Google Pay zu aktivieren:

  1. Setze automaticPaymentMethods: true in der Stripe-Konfiguration
  2. Implementiere die entsprechenden UI-Elemente in deinem Storefront
  3. Stelle sicher, dass deine Domain für Apple Pay verifiziert ist

Zahlungsbeschreibungen anpassen

Du kannst benutzerdefinierte Beschreibungen für Zahlungen festlegen:

// In medusa-config.ts
{
  options: {
    paymentDescription: "Bestellung #{order_number} bei meinem Shop",
  },
}

Oder dynamisch im Cart Context:

// Im Storefront
const cart = await medusa.carts.create({
  // ... andere Optionen
  context: {
    payment_description: "Spezielle Bestellung",
  },
})

Häufige Probleme und Lösungen

Problem: Stripe erscheint nicht in den Payment Providers

Lösung:

  • Überprüfe, ob der Stripe Module Provider korrekt in medusa-config.ts registriert ist
  • Stelle sicher, dass STRIPE_API_KEY in der .env Datei gesetzt ist
  • Starte den Medusa-Server neu

Problem: Zahlungen werden nicht verarbeitet

Lösung:

  • Überprüfe, ob Stripe in der Region aktiviert ist
  • Stelle sicher, dass du den richtigen API Key verwendest (Test vs. Live)
  • Überprüfe die Stripe-Logs im Dashboard auf Fehler

Problem: Webhook-Events werden nicht empfangen

Lösung:

  • Überprüfe, ob die Webhook-URL korrekt ist
  • Stelle sicher, dass deine Anwendung öffentlich erreichbar ist (für Production)
  • Überprüfe, ob das webhookSecret korrekt gesetzt ist
  • Teste die Webhook-URL mit Stripe CLI lokal

Problem: CORS-Fehler im Storefront

Lösung:

  • Füge deine Storefront-URL zu STORE_CORS in der .env Datei hinzu:
STORE_CORS=http://localhost:3000,https://deine-domain.com

Problem: SSL-Fehler bei Webhooks

Lösung:

  • Stelle sicher, dass deine Production-URL HTTPS verwendet
  • Überprüfe, ob dein SSL-Zertifikat gültig ist
  • Für lokale Tests verwende Stripe CLI

Testen der Integration

Test-Kreditkarten

Stripe bietet Test-Kreditkarten für die Entwicklung:

  • Erfolgreiche Zahlung: 4242 4242 4242 4242
  • Abgelehnte Zahlung: 4000 0000 0000 0002
  • 3D Secure erforderlich: 4000 0025 0000 3155

Weitere Test-Karten findest du in der Stripe-Dokumentation.

Zahlungsfluss testen

  1. Erstelle ein Produkt im Admin Dashboard
  2. Füge es zum Warenkorb hinzu
  3. Gehe zum Checkout
  4. Wähle Stripe als Zahlungsmethode
  5. Verwende eine Test-Kreditkarte
  6. Überprüfe im Stripe Dashboard, ob die Zahlung registriert wurde

Best Practices

  1. Sicherheit:
    • Verwende niemals Live Keys in der Entwicklung
    • Speichere Secrets sicher (z.B. in Environment Variables)
    • Implementiere Rate Limiting für Webhook-Endpunkte
  2. Error Handling:
    • Implementiere umfassendes Error Handling im Storefront
    • Zeige benutzerfreundliche Fehlermeldungen
    • Logge Fehler für Debugging
  3. Monitoring:
    • Überwache Webhook-Events im Stripe Dashboard
    • Setze Alerts für fehlgeschlagene Zahlungen
    • Überprüfe regelmäßig die Medusa-Logs
  4. Testing:
    • Teste alle Zahlungsmethoden vor dem Go-Live
    • Teste Webhook-Events mit Stripe CLI
    • Führe umfassende Integrationstests durch

Nächste Schritte

Nach erfolgreicher Stripe-Integration kannst du:

  1. Weitere Zahlungsmethoden aktivieren: Bancontact, iDEAL, giropay, etc.
  2. Gespeicherte Zahlungsmethoden implementieren: Für wiederkehrende Kunden
  3. Subscriptions einrichten: Für wiederkehrende Zahlungen
  4. Custom Payment Flows: Anpassen des Checkout-Prozesses
  5. Analytics integrieren: Zahlungsstatistiken tracken

Fazit

Die Integration von Stripe in MedusaJS ist unkompliziert und bietet dir eine solide Grundlage für die Zahlungsabwicklung in deinem E-Commerce-Shop. Mit diesem Setup kannst du verschiedene Zahlungsmethoden anbieten und sicher Zahlungen verarbeiten.

Falls du Fragen hast oder auf Probleme stößt, schaue in die offizielle Medusa-Dokumentation oder die Stripe-Dokumentation.

Viel Erfolg mit deiner Stripe-Integration! 💳