Stripe-Integration einrichten

Levy Fleets verwendet Stripe als primaren Zahlungsabwickler fur alle Finanztransaktionen. Diese umfassende Anleitung behandelt die vollstandige Einrichtung und Konfiguration der Stripe-Integration fur Flottenbetreiber, einschliesslich API-Schlussel, Webhooks, Testmodus und erweiterte Funktionen.

Was Stripe abwickelt

Stripe unterstutzt alle zahlungsbezogenen Funktionen in Levy Fleets:

• Fahrtzahlungen und -einzuge - Abbuchung von Kunden fur Fahrten
• Wallet-Aufladungen - Manuelle und automatische Guthabenaufladungen
• Speicherung von Zahlungsmethoden - Sichere Speicherung von Kundenkarten
• Identitatsverifizierung - KYC uber Stripe Identity
• Ruckerstattungsabwicklung - Ruckzahlung von Geldern an Kunden
• Zahlungswiederholungen - Wiederherstellung fehlgeschlagener Zahlungen

Voraussetzungen

Bevor Sie die Stripe-Integration konfigurieren, stellen Sie sicher, dass Sie Folgendes haben:

1. Ein Stripe-Konto - Erstellen Sie eines unter stripe.com, falls Sie noch keines haben
2. Admin-Zugang zu Ihrem Levy Fleets Dashboard
3. Zugang zu Umgebungsvariablen - Vercel-Dashboard oder Serverkonfiguration
4. Verstandnis Ihres Zahlungsmodells - Wallet-basiert oder Nachzahlung

Umgebungsvariablen

Erforderliche Variablen

Konfigurieren Sie diese Umgebungsvariablen, damit Stripe funktioniert:

Optionale Variablen (Testmodus)

Fur Entwicklung und Tests:

Zusatzliche Variablen

Ihre Stripe-Schlussel abrufen

Webhook-Konfiguration

Webhooks ermoglichen es Stripe, Levy Fleets uber Zahlungsereignisse zu benachrichtigen. Konfigurieren Sie Ihren Webhook-Endpunkt, um diese Ereignisse zu empfangen:

Erforderliche Webhook-Ereignisse

Abbuchungsereignisse

• charge.succeeded - Erfolgreiche Zahlungen erfassen
• charge.failed - Fehlgeschlagene Zahlungsversuche verfolgen
• charge.captured - Erfasste Vorautorisierungen aufzeichnen
• charge.updated - Abbuchungsaktualisierungen synchronisieren
• charge.refunded - Ruckerstattungen verfolgen
• charge.expired - Abgelaufene Abbuchungen behandeln
• charge.pending - Ausstehende Abbuchungen verfolgen

Streitfall-Ereignisse

• charge.dispute.created
• charge.dispute.updated
• charge.dispute.closed
• charge.dispute.funds_withdrawn
• charge.dispute.funds_reinstated

Payment Intent-Ereignisse

• payment_intent.succeeded - Abgeschlossene Zahlungen verarbeiten

Setup Intent-Ereignisse

• setup_intent.succeeded - Neue Zahlungsmethoden speichern

Kundenereignisse

• customer.created - Stripe-Kunden mit Ihrer Datenbank verknupfen
• customer.updated - Kundenanderungen synchronisieren
• customer.deleted - Kundenloschung behandeln

Identitatsereignisse (bei Verwendung von ID-Verifizierung)

• identity.verification_session.requires_input
• identity.verification_session.processing
• identity.verification_session.canceled
• identity.verification_session.verified

Webhook-Sicherheit

Alle Webhooks werden automatisch uber den Signaturmechanismus von Stripe verifiziert. Das System protokolliert auch alle Webhook-Ereignisse in der Tabelle stripe_webhook_logs fur Prufungs- und Debugging-Zwecke.

Testmodus vs. Live-Modus

Automatische Testmodus-Auswahl

Das System verwendet automatisch den Testmodus fur:

1. Super-Admin-Benutzer - Alle Benutzer mit der Rolle super_admin verwenden automatisch den Testmodus
2. Interne E-Mails - Jeder Kunde mit einer @levyelectric.com-E-Mail verwendet den Testmodus

Dies ermoglicht sicheres Testen ohne Risiko von Produktionsabbuchungen.

Testmodus-Verhalten

Im Testmodus:

• Alle Stripe-API-Aufrufe verwenden Test-Geheimschlussel
• Zahlungsmethoden verwenden Test-Kartennummern
• Es wird kein echtes Geld abgebucht
• Der Testmodus wird in der Dashboard-Oberflache angezeigt

Test-Kartennummern

Verwenden Sie diese Testkarten fur die Entwicklung:

Verwenden Sie ein beliebiges gultiges zukunftiges Ablaufdatum und eine beliebige 3-stellige CVC (4 Stellen fur Amex).

Zahlungssystem-Konfiguration

Unterkonto-Zahlungseinstellungen

Jedes Unterkonto kann sein Zahlungssystem unter Einstellungen > Zahlungen konfigurieren:

Wallet-System vs. Nachzahlung

Auto-Auflade-System

Die Auto-Aufladung belastet automatisch die Karte eines Kunden, wenn sein Wallet-Guthaben unter einen Schwellenwert fallt.

Anforderungen

Damit die Auto-Aufladung funktioniert:

1. Unterkonto-Einstellung - Auto-Aufladung auf dem Unterkonto aktiviert
2. Kundenpraferenz - Kunde muss sich fur Auto-Aufladung anmelden
3. Zahlungsmethode - Kunde muss eine Standard-Zahlungsmethode haben
4. Stripe-Kunde - Kunde muss eine verknupfte Stripe-Kunden-ID haben

Funktionsweise

1. Fahrt endet oder periodische Prufung lauft
2. System pruft, ob Wallet-Guthaben bei oder unter dem Schwellenwert liegt
3. System erwirbt eine Sperre, um doppelte Abbuchungen zu verhindern
4. Stripe PaymentIntent wird mit Idempotenzschlussel erstellt
5. Bei Erfolg wird Wallet-Guthaben gutgeschrieben
6. Sperre wird freigegeben

Verhinderung doppelter Abbuchungen

Das System verwendet zwei Mechanismen zur Verhinderung doppelter Abbuchungen:

1. Datenbanksperre - Spalten verfolgen Sperrstatus und Ablauf
2. Stripe-Idempotenzschlussel - Eindeutiger Schlussel pro Auto-Aufladeversuch

Zahlungswiederholungs-System

Wenn das Wallet eines Kunden negativ wird, versucht das System automatisch, den ausstehenden Betrag einzuziehen.

Wiederholungszeitplan

Zahlungsmethoden-Rotation

Bei Wiederholungen durchlauft das System alle gespeicherten Zahlungsmethoden:

1. Zuerst Standard-Zahlungsmethode - Versucht die bevorzugte Karte des Kunden
2. Dann andere Karten nach Alter - Alteste Karten werden zuerst versucht
3. Zyklus zurucksetzen - Bei jedem neuen Planungsfenster werden alle Methoden erneut versucht

Automatischer Erlass

Guthaben unter 0,50 $ werden automatisch erlassen (Stripe-Minimum ist 0,50 $ fur USD-Abbuchungen).

Identitatsverifizierung (Stripe Identity)

Levy Fleets integriert Stripe Identity fur die Kundenidentitatsverifizierung.

Verifizierungsmodi

Konfigurieren Sie die Identitatsverifizierung auf Unterkonto-Ebene:

Risikobasierte Verifizierung

Bei Verwendung des risikobasierten Modus:

1. Stripe Radar bewertet Zahlungen (0-100)
2. Risikostufen: normal (10), elevated (50), highest (75)
3. Wenn Punktzahl >= Schwellenwert, ist Verifizierung erforderlich
4. Kunde ist bis zur Verifizierung gesperrt

Verifizierungsabbuchungen (temporare Sperren)

Das System kann temporare Autorisierungssperren auf Kundenkarten setzen, um die Gultigkeit der Zahlungsmethode zu verifizieren.

Sperrrichtlinien

Funktionsweise von Sperren

1. Autorisierung erstellt - Keine tatsachliche Abbuchung, nur eine Sperre
2. Karte validiert - Bestatigt, dass Karte aktiv ist und Guthaben hat
3. Sperre freigegeben - Automatisch nach der Fahrt oder innerhalb von 7 Tagen freigegeben
4. Nie erfasst - Verifizierungssperren werden nie in tatsachliche Abbuchungen umgewandelt

Datenbankintegration

Wichtige Tabellen

Cron-Jobs

Mehrere Cron-Jobs unterstutzen das Zahlungssystem:

Alle Cron-Endpunkte erfordern den CRON_SECRET-Header zur Authentifizierung.

Lokale Entwicklung

Testen mit Stripe CLI

Testereignisse auslosen

# Ein charge.succeeded-Ereignis auslosen
stripe trigger charge.succeeded

# Ein payment_intent.succeeded-Ereignis auslosen
stripe trigger payment_intent.succeeded

Uberwachung und Debugging

Webhook-Protokolle prufen

Zeigen Sie aktuelle Webhook-Aktivitaten in Ihrer Datenbank an:

SELECT
  event_type,
  status,
  COUNT(*) as count,
  MAX(processed_at) as last_seen
FROM stripe_webhook_logs
WHERE processed_at > NOW() - INTERVAL '24 hours'
GROUP BY event_type, status
ORDER BY last_seen DESC;

Analyse fehlgeschlagener Zahlungen

SELECT
  decline_reason,
  COUNT(*) as count,
  SUM(amount) / 100.0 as total_usd
FROM stripe_charges
WHERE status = 'failed'
  AND created_at > NOW() - INTERVAL '7 days'
GROUP BY decline_reason
ORDER BY count DESC;

Fehlerbehebung

Haufige Probleme

"Webhook-Signaturverifizierung fehlgeschlagen"

Ursache: Falsches STRIPE_WEBHOOK_SECRET oder Anderung des Anfragetexts

Losung:

1. Uberprufen Sie, ob das Geheimnis mit Ihrem Stripe-Dashboard ubereinstimmt
2. Stellen Sie sicher, dass keine Middleware den Anfragetext andert
3. Prufen Sie den korrekten Header-Namen: stripe-signature

"Kunde nicht gefunden" in Stripe

Ursache: Kunde wurde in Stripe geloscht oder nie synchronisiert

Losung:

1. Prufen Sie stripe_customer_id in der Kundentabelle
2. Uberprufen Sie, ob die ID im Stripe-Dashboard existiert
3. Loschen Sie die ID und lassen Sie das System sie neu erstellen

Zahlungen werden nicht synchronisiert

Ursache: Webhook-Endpunkt falsch konfiguriert oder fehlerhaft

Losung:

1. Prufen Sie stripe_webhook_logs auf Fehler
2. Uberprufen Sie die Webhook-URL im Stripe-Dashboard
3. Senden Sie fehlgeschlagene Ereignisse vom Stripe-Dashboard erneut
4. Prufen Sie Anwendungsprotokolle auf Fehler

Testmodus funktioniert nicht

Ursache: Test-Schlussel nicht konfiguriert

Losung:

1. Fugen Sie STRIPE_TEST_SECRET_KEY und STRIPE_TEST_PUBLISHABLE_KEY hinzu
2. Uberprufen Sie, ob Schlussel mit sk_test_ und pk_test_ beginnen
3. Prufen Sie, ob Benutzer eine @levyelectric.com-E-Mail oder super_admin-Rolle hat

Bewährte Sicherheitspraktiken

1. Niemals vollstandige Kartennummern protokollieren - Nur last4 wird gespeichert
2. Webhook-Geheimnisse rotieren - Regelmasig andern
3. Separate Test-/Live-Schlussel verwenden - Niemals Umgebungen mischen
4. Radar aktivieren - Stripes Betrugserkennung
5. Auf Anomalien uberwachen - Alarme fur ungewohnliche Aktivitaten einrichten
6. PCI-Konformitat - Niemals rohe Kartendaten serverseitig verarbeiten

Nachste Schritte

• Zahlungsmethoden - Kundenzahlungsmethoden verwalten
• Automatische Ruckerstattungen - Wie automatische Ruckerstattungen funktionieren
• Schadensgebuhren - Kunden fur Schaden belasten