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:
- Eine funktionierende MedusaJS-Anwendung hast (siehe MedusaJS Setup Tutorial)
- Ein Stripe-Konto besitzt - Registrierung
- Zugriff auf deine Stripe API Keys hast
Stripe API Keys abrufen
- Logge dich in dein Stripe Dashboard ein
- Navigiere zu Developers > API keys
- Du findest dort:
- Publishable key (beginnt mit
pk_test_oderpk_live_) - Secret key (beginnt mit
sk_test_odersk_live_)
- Publishable key (beginnt mit
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 KeywebhookSecret(optional, für Production): Webhook Secret für sichere Webhook-VerarbeitungautomaticPaymentMethods(optional): Aktiviert automatische Zahlungsmethoden wie Apple Pay und Google Paycapture(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
- Starte deine Medusa-Anwendung:
npm run dev
- Öffne das Admin Dashboard unter
http://localhost:9000/app - Logge dich mit deinem Admin-Account ein
- Navigiere zu Settings > Regions
- Klicke auf die Region, in der du Stripe aktivieren möchtest
- Klicke auf das Bearbeiten-Icon (oben rechts im ersten Abschnitt)
- Im sich öffnenden Seitenfenster findest du das Feld “Payment Providers”
- Wähle “Stripe (STRIPE)” aus dem Dropdown-Menü
- 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
- Gehe zu deinem Stripe Dashboard
- Navigiere zu Developers > Webhooks
- Klicke auf “Add endpoint”
- Gib deine Webhook-URL ein (z.B.
https://deine-domain.com/hooks/payment/stripe_stripe/stripe) - Wähle die folgenden Events aus:
payment_intent.succeededpayment_intent.payment_failedcharge.succeededcharge.failed(seit Medusa v2.8.5)
- Klicke auf “Add endpoint”
- Kopiere das Webhook Secret (beginnt mit
whsec_) - Füge es zu deiner
.envDatei hinzu:
STRIPE_WEBHOOK_SECRET=whsec_...
- 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:
- Setze
automaticPaymentMethods: truein der Stripe-Konfiguration - Implementiere die entsprechenden UI-Elemente in deinem Storefront
- 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.tsregistriert ist - Stelle sicher, dass
STRIPE_API_KEYin der.envDatei 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
webhookSecretkorrekt gesetzt ist - Teste die Webhook-URL mit Stripe CLI lokal
Problem: CORS-Fehler im Storefront
Lösung:
- Füge deine Storefront-URL zu
STORE_CORSin der.envDatei 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
- Erstelle ein Produkt im Admin Dashboard
- Füge es zum Warenkorb hinzu
- Gehe zum Checkout
- Wähle Stripe als Zahlungsmethode
- Verwende eine Test-Kreditkarte
- Überprüfe im Stripe Dashboard, ob die Zahlung registriert wurde
Best Practices
-
Sicherheit:
- Verwende niemals Live Keys in der Entwicklung
- Speichere Secrets sicher (z.B. in Environment Variables)
- Implementiere Rate Limiting für Webhook-Endpunkte
-
Error Handling:
- Implementiere umfassendes Error Handling im Storefront
- Zeige benutzerfreundliche Fehlermeldungen
- Logge Fehler für Debugging
-
Monitoring:
- Überwache Webhook-Events im Stripe Dashboard
- Setze Alerts für fehlgeschlagene Zahlungen
- Überprüfe regelmäßig die Medusa-Logs
-
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:
- Weitere Zahlungsmethoden aktivieren: Bancontact, iDEAL, giropay, etc.
- Gespeicherte Zahlungsmethoden implementieren: Für wiederkehrende Kunden
- Subscriptions einrichten: Für wiederkehrende Zahlungen
- Custom Payment Flows: Anpassen des Checkout-Prozesses
- 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! 💳