Stripe-Datensynchronisation

Die Stripe-Datensynchronisationsfunktion ermöglicht die Synchronisation von Zahlungsdaten zwischen Stripe und Levy Fleets. Dies umfasst den Import historischer Zahlungen aus CSV-Exporten und Echtzeit-Synchronisation über die Stripe-API. Diese Anleitung behandelt alle Aspekte der Stripe-Integration für das Zahlungsdatenmanagement.

Zugriff auf Stripe-Import

Navigieren Sie zu Admin > Stripe-Import, um auf die Stripe-Datensynchronisationsoberfläche zuzugreifen.

Voraussetzungen:

• Admin-Zugriff auf das System
• Konfigurierte Stripe-Integration
• Gültige Stripe-API-Zugangsdaten (für API-Sync)

Übersicht

Synchronisationsmethoden

Erfasste Daten

Bei der Synchronisation von Stripe-Zahlungen werden folgende Daten gespeichert:

Zahlungsdetails:

• Zahlungs-ID, Betrag, Währung, Status
• Erstellungszeitstempel, Erfassungsstatus
• Erstattungsinformationen (Betrag, Datum)
• Payment Intent ID

Karteninformationen:

• Karten-ID, Marke, letzte 4 Ziffern
• Ablaufmonat/-jahr
• Kartenfingerabdruck, Finanzierungstyp
• AVS- und CVC-Verifizierungsstatus

Kundeninformationen:

• Stripe-Kunden-ID
• Kunden-E-Mail und Telefon
• Kundenbeschreibung

Fahrtenmetadaten (aus Zahlungsmetadaten):

• Fahrten-ID, Benutzer-ID, Kunden-ID
• Start-/Endkoordinaten
• Distanz und Dauer
• Zahlungstyp und verwendete Guthaben

---

Dashboard-Statistiken

Die Stripe-Import-Seite zeigt vier Metrikkarten:

Diese Metriken werden nach jeder Synchronisationsoperation aktualisiert.

---

CSV-Import

Aus Stripe exportieren

CSV importieren

1. Gehen Sie in Levy Fleets zu Admin > Stripe-Import
2. Suchen Sie den Bereich "CSV importieren"
3. Ziehen Sie Ihre CSV-Datei per Drag-and-Drop oder klicken Sie zum Durchsuchen
4. Klicken Sie auf "CSV importieren (Hintergrund)"
5. Der Import-Job beginnt mit der Verarbeitung

Dateigrößenhandhabung

Für sehr große Dateien (10+ MB):

• Datei wird im Browser geparst
• Daten werden in 500-Zeilen-Stapeln an den Server gesendet
• Fortschritt wird für jeden Stapel angezeigt

Importfortschritt

Der Import läuft im Hintergrund:

• Fortschrittsbalken zeigt Prozent der Fertigstellung
• Statusaktualisierungen alle 2 Sekunden (Polling)
• Benachrichtigung bei Abschluss
• Fehleranzahl wird angezeigt, falls Probleme auftreten

Zugeordnete CSV-Spalten

Wichtige Spalten aus Stripe-Export:

Plus 40+ zusätzliche Spalten für vollständige Zahlungsdaten.

---

API-Sync

Manuelle Synchronisation

1. Finden Sie auf der Stripe-Import-Seite den Bereich "Manuelle Synchronisation"
2. Klicken Sie auf "Letzte 24 Stunden synchronisieren"
3. Das System ruft Zahlungen von der Stripe-API ab
4. Ergebnisse werden angezeigt: importiert, aktualisiert, Fehler

Was synchronisiert wird

• Alle in den letzten 24 Stunden erstellten Zahlungen
• Paginiertes Abrufen (100 pro Anfrage)
• Automatische Handhabung großer Ergebnismengen
• Upserts (fügt neue ein, aktualisiert bestehende)

Synchronisationsergebnisse

Nach Abschluss der Synchronisation:

• Importiert: Neue hinzugefügte Zahlungen
• Aktualisiert: Bestehende aktualisierte Zahlungen
• Fehler: Zahlungen, die nicht synchronisiert werden konnten

---

Webhook-Integration

Wie Webhooks funktionieren

Stripe sendet Echtzeit-Benachrichtigungen an Levy Fleets:

1. Ereignis tritt in Stripe auf (Zahlung, Bezahlung usw.)
2. Stripe sendet POST an /api/webhooks/stripe
3. Levy Fleets validiert die Signatur
4. Ereignis wird verarbeitet und Daten werden aktualisiert
5. Antwort wird an Stripe gesendet

Unterstützte Webhook-Ereignisse

Zahlungsereignisse:

Dispute-Ereignisse:

Payment Intent-Ereignisse:

Kundenereignisse:

Identitätsverifizierungsereignisse:

Webhooks konfigurieren

---

Import-Job-Verfolgung

Bereich aktive Jobs

Die Seite zeigt aktuell verarbeitete Imports an:

Job-Karte zeigt:

• Dateiname und Größe
• Startzeit
• Fortschrittsbalken (verarbeitet/Gesamtzeilen)
• Status-Badge

Statusindikatoren:

Zeilenanzahlen:

• Importiert: Neue erstellte Datensätze
• Aktualisiert: Bestehende aktualisierte Datensätze
• Übersprungen: Übersprungene Zeilen (Duplikate, ungültig)
• Fehler: Fehlgeschlagene Zeilen

Vergangene Jobs anzeigen

Die Import-Jobs-API verfolgt:

• Job-ID und Typ
• Dateiname und Größe
• Start- und Abschlusszeiten
• Zeilenverarbeitungsstatistiken
• Fehlerdetails (JSONB)

---

Konfliktbehandlung

Duplikatvermeidung

Zahlungen werden durch Stripe-Zahlungs-ID identifiziert:

• stripe_charges.id ist der Primärschlüssel
• ON CONFLICT (id) DO UPDATE verhindert Duplikate
• Aktualisierungen aktualisieren bestehende Datensätze mit neuen Daten

Kundenabgleich

Bei der Synchronisation werden Kunden abgeglichen nach:

1. Stripe-Kunden-ID
2. E-Mail-Adresse
3. Metadaten customer_id

Datenzusammenführung

Bei Konflikt (bestehende Zahlung):

• Betragsfelder werden aktualisiert
• Status wird aktualisiert
• Erstattungsinfo wird aktualisiert
• Zeitstempel werden beibehalten
• Metadaten werden zusammengeführt

---

Konfiguration

Erforderliche Umgebungsvariablen

# Stripe-API-Schlüssel
STRIPE_SECRET_KEY=sk_live_...       # Live-Geheimschlüssel
STRIPE_WEBHOOK_SECRET=whsec_...      # Webhook-Signaturgeheimnis

# Optional
STRIPE_TEST_SECRET_KEY=sk_test_...   # Testmodus-Schlüssel

API-Version

Das System verwendet Stripe-API-Version 2023-10-16. Diese ist in der Konfiguration festgelegt und sollte mit Ihren Stripe-Dashboard-Einstellungen übereinstimmen.

---

Speichern von Zahlungsmethoden

Wenn payment_intent.succeeded- oder setup_intent.succeeded-Ereignisse verarbeitet werden:

1. Zahlungsmethoden-ID und Stripe-Kunden-ID werden extrahiert
2. Kunde wird über stripe_customer_id gesucht
3. Neue Zahlungsmethode wird in payment_methods-Tabelle gespeichert mit:
   • customer_uuid - Verknüpfung zum Kundendatensatz
   • stripe_payment_method_id - Stripes Zahlungsmethoden-ID
   • type - Kartentyp (normalerweise 'card')
   • last4 - Letzte 4 Ziffern zur Anzeige
   • brand - Kartenmarke (Visa, Mastercard usw.)

---

Wallet-Aufladungen

Wenn ein payment_intent.succeeded-Ereignis eine Wallet-Aufladung anzeigt:

Payment Intent-Typen (aus metadata.type):

• wallet_topup - Manuelle Wallet-Aufladung durch Kunden
• auto_topup - Automatische Aufladung bei niedrigem Guthaben ausgelöst
• ride_payment - Direkte Fahrtenzahlung

Verarbeitungsschritte für wallet_topup:

1. Kunde wird über Metadaten aufgelöst (customer_uuid, customer_number oder user_id)
2. Aktuelles Wallet-Guthaben wird aus Kundendatensatz abgerufen
3. Zahlungsbetrag wird zum Guthaben addiert
4. wallet_transactions-Datensatz wird mit Typ credit erstellt
5. Kundenguthaben wird aktualisiert

Transaktionstypen:

• credit - Geld zum Wallet hinzugefügt
• debit - Geld vom Wallet ausgegeben

---

Fahrtzahlungsaktualisierungen

Wenn eine Fahrtenzahlung abgeschlossen wird:

1. ride_uuid wird aus Metadaten extrahiert
2. Fahrtendatensatz wird gesucht
3. total_cost wird mit Zahlungsbetrag aktualisiert
4. Fahrt wird als bezahlt markiert

---

Risikoscore-Verarbeitung

Aus Zahlungsergebnissen werden Risikodaten erfasst:

Risikostufen-Zuordnung:

• normal = Score 10
• elevated = Score 50
• highest = Score 75

Kunden mit hohem Risiko können zur Identitätsverifizierung markiert werden.

---

Sicherheit

Webhook-Validierung

Alle Webhooks werden validiert:

1. Signatur-Header wird extrahiert
2. stripe.webhooks.constructEvent() verifiziert die Signatur
3. Ungültige Signaturen geben 400-Fehler zurück
4. Verhindert gefälschte Ereignisse

API-Schlüssel-Sicherheit

• STRIPE_SECRET_KEY niemals im Client-Code offenlegen
• Nur Umgebungsvariablen verwenden
• Schlüssel bei Kompromittierung rotieren
• Wenn möglich eingeschränkte Schlüssel verwenden

Datenspeicherung

• Kartennummern werden nicht gespeichert (nur letzte 4)
• Sensible Daten werden im Ruhezustand verschlüsselt
• PCI-Compliance wird durch Stripe gewährleistet

---

Fehlerbehebung

CSV-Import schlägt fehl

Mögliche Ursachen:

• Ungültiges CSV-Format
• Falsche Spaltenüberschriften
• Datei zu groß
• Netzwerk-Timeout

Lösungen:

• Überprüfen, ob Export von Stripe ist
• Prüfen, ob Datei nicht beschädigt ist
• Große Dateien in kleinere Teile aufteilen
• Mit stabiler Verbindung erneut versuchen

API-Sync gibt keine Daten zurück

Mögliche Ursachen:

• Keine Zahlungen in den letzten 24 Stunden
• API-Schlüssel ungültig oder abgelaufen
• Stripe-Konto hat keine Daten

Lösungen:

• Datumsbereich erweitern
• API-Schlüssel in Umgebung überprüfen
• Stripe-Dashboard auf Zahlungen prüfen

Webhooks werden nicht verarbeitet

Mögliche Ursachen:

• Webhook-Geheimnis stimmt nicht überein
• Endpunkt-URL falsch
• Server nicht erreichbar
• Ereignistyp nicht abonniert

Lösungen:

• STRIPE_WEBHOOK_SECRET überprüfen
• Endpunkt-URL im Stripe-Dashboard prüfen
• Sicherstellen, dass Server erreichbar ist
• Erforderliche Ereignistypen hinzufügen

Doppelte Zahlungen erscheinen

Ursache: Gleiche Zahlung mehrfach verarbeitet

Hinweis: Dies sollte aufgrund der Upsert-Logik nicht passieren. Falls doch:

• Unique-Constraint auf Zahlungs-ID prüfen
• Überprüfen, ob Datenbank-Migrationen aktuell sind

---

Bewährte Praktiken

Regelmäßige Synchronisation

1. Tägliche manuelle Synchronisation: API-Sync jeden Morgen ausführen
2. Wöchentlicher CSV-Export: Historische Daten wöchentlich importieren
3. Webhook-Überwachung: Webhook-Logs regelmäßig prüfen

Datenverifizierung

Nach der Synchronisation:

1. Anzahlen mit Stripe-Dashboard vergleichen
2. Aktuelle Zahlungen stichprobenartig prüfen
3. Überprüfen, ob Kundenabgleich funktioniert

Leistung

1. Imports außerhalb der Spitzenzeiten: Große CSV-Imports bei geringem Verkehr ausführen
2. Webhooks überwachen: Webhook-Verarbeitung schnell halten
3. Datenbankindizes: Sicherstellen, dass richtige Indizes existieren

---

Nächste Schritte

• Super-Admin-Funktionen - Erfahren Sie mehr über Plattformadministration
• Datenimport-Tools - Andere Datentypen importieren
• Kontoeinrichtung - Zahlungseinstellungen konfigurieren