Kundenzahlungsmethoden

Das Zahlungsmethoden-System ermoglicht es Kunden, ihre Zahlungskarten fur die Nutzung von Levy Fleets-Diensten zu speichern und zu verwalten. Diese Anleitung behandelt, wie Administratoren Zahlungsmethoden im Namen von Kunden uber das Dashboard verwalten konnen, sowie wie das System Karten im Hintergrund behandelt.

Funktionsweise von Zahlungsmethoden

Speicherarchitektur

Zahlungsmethoden werden aus Sicherheits- und Effizienzgrunden an zwei Orten gespeichert:

1. Stripe - Die tatsachlichen Zahlungsmethodendaten (Kartennummer, Ablaufdatum, CVC) werden sicher von Stripe gespeichert
2. Levy-Datenbank - Nur nicht-sensible Metadaten werden lokal gespeichert:
   • Stripe-Zahlungsmethoden-ID
   • Kartenmarke (Visa, Mastercard, etc.)
   • Letzte 4 Ziffern
   • Kartentyp
   • Standardstatus

Diese Architektur gewahrleistet PCI-Konformitat bei gleichzeitiger Ermoglichung effizienter lokaler Abfragen.

Zahlungsmethoden-Ablauf

Wenn ein Kunde eine Karte hinzufugt:

Datenbankschema

Zahlungsmethoden-Tabelle

Zahlungsmethoden im Dashboard verwalten

Zugriff auf Zahlungsmethoden

1. Navigieren Sie zu Dashboard > Kunden
2. Klicken Sie auf einen Kunden, um sein Profil anzuzeigen
3. Finden Sie den Abschnitt Zahlungsmethoden

Karten anzeigen

Der Abschnitt Zahlungsmethoden zeigt an:

• Kartenmarke und letzte 4 Ziffern (z.B. "VISA **** 4242")
• Datum, an dem die Karte hinzugefugt wurde
• Standard-Badge fur die primare Karte
• Loschen-Button fur jede Karte

Eine Karte hinzufugen

Testmodus-Anzeige

Beim Hinzufugen von Karten fur Testkonten:

• Ein gelbes Banner zeigt "Testmodus aktiv"
• Verwenden Sie Stripe-Testkartennummern (siehe unten)
• Es werden keine echten Abbuchungen vorgenommen

Eine Karte loschen

1. Klicken Sie auf das Papierkorb-Symbol neben der Karte
2. Bestatigen Sie die Loschung im Dialog
3. Die Karte wird sowohl aus Stripe als auch aus der Datenbank entfernt

Testmodus

Wann der Testmodus aktiv ist

Der Testmodus wird automatisch aktiviert, wenn:

1. Super-Admin-Benutzer - Jeder Benutzer mit der Rolle super_admin
2. Interne Test-E-Mails - Kunden mit @levyelectric.com-E-Mail

Testmodus-Verhalten

Im Testmodus:

• Verwendet Test-Stripe-API-Schlussel
• Karten werden in Stripes Testumgebung gespeichert
• Es werden keine echten Abbuchungen vorgenommen
• Setup Intents verwenden Test-Endpunkte
• Das Dashboard zeigt "Testmodus aktiv" an

Test-Kartennummern

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

Standard-Zahlungsmethode

Automatische Standardauswahl

Wenn ein Kunde seine erste Zahlungsmethode hinzufugt, wird sie automatisch zum Standard. Dies stellt sicher, dass immer eine verwendbare Zahlungsmethode vorhanden ist fur:

• Wallet-Aufladungen
• Auto-Aufladeabbuchungen
• Zahlungswiederholungen

Wie der Standard bestimmt wird

1. Erste hinzugefugte Karte ist Standard
2. Wenn Standard-Karte geloscht wird, wird alteste verbleibende Karte zum Standard

Wie der Standard verwendet wird

Die Standard-Zahlungsmethode wird verwendet fur:

• Auto-Aufladung - Automatische Wallet-Auffullung
• Zahlungswiederholungen - Wiederherstellung negativer Wallet-Guthaben
• Off-Session-Abbuchungen - Jede Abbuchung, die ohne Kundenanwesenheit initiiert wird

Integration mit dem Zahlungswiederholungs-System

Zahlungsmethoden spielen eine kritische Rolle im automatischen Zahlungswiederholungs-System zur Wiederherstellung negativer Wallet-Guthaben.

Wie Zahlungsmethoden fur Wiederholungen verwendet werden

Wenn das Wallet eines Kunden negativ wird, erstellt das System einen Zahlungswiederholungs-Job, der:

1. Zuerst die Standard-Zahlungsmethode versucht
2. Durch andere Karten rotiert geordnet nach Erstellungsdatum (alteste zuerst)
3. Verfolgt, welche Methoden versucht wurden, um doppelte Versuche innerhalb desselben Planungsfensters zu vermeiden
4. Den Zyklus zurucksetzt, wenn zu einem neuen Tag oder einer neuen Woche gewechselt wird

Zahlungsmethoden-Rotationsreihenfolge

1. Standard-Zahlungsmethode (is_default = true)
2. Alteste Nicht-Standard-Karte
3. Zweitalteste Nicht-Standard-Karte
4. ... setzt sich durch alle Karten fort

Bedeutung mehrerer Karten

Kunden mit mehreren Zahlungsmethoden haben hohere Zahlungswiederherstellungsraten, weil:

• Wenn eine Karte abgelehnt wird, werden andere automatisch versucht
• Verschiedene Karten konnen unterschiedliche Kreditlimits haben
• Bankspezifische Probleme (temporare Sperren, Betrugsalarme) blockieren die Zahlung nicht vollstandig

Webhook-Integration

Zahlungsmethoden konnen auch uber Stripe-Webhooks erstellt werden, wenn Kunden Karten uber die mobile App hinzufugen:

setup_intent.succeeded

Wenn ein SetupIntent von der mobilen App abgeschlossen wird:

1. System sucht den Kunden nach Stripe-ID
2. Ruft Zahlungsmethodendetails von Stripe ab
3. Speichert Kartenmetadaten in der Datenbank
4. Setzt als Standard, wenn es die erste Karte ist

payment_intent.succeeded

Wenn eine Zahlung mit einer neuen Zahlungsmethode abgeschlossen wird:

1. System pruft, ob Zahlungsmethode bereits existiert
2. Falls nicht, speichert die neue Zahlungsmethode
3. Aktualisiert bei Bedarf den Standard des Kunden

Mobile App-Integration

Karten aus der App hinzufugen

Die mobile App verwendet Stripes natives SDK:

1. App fordert Ephemeral-Key vom Server an
2. Stripe CustomerSheet oder PaymentSheet wird prasentiert
3. Kunde gibt Kartendetails in nativer Stripe-UI ein
4. Bei Erfolg wird setup_intent.succeeded-Webhook ausgelost
5. Zahlungsmethode wird in der Datenbank gespeichert

Mobile Zahlungsaktionen

Sicherheitsuberlegungen

PCI-Konformitat

Das Zahlungsmethoden-System wahrt PCI-Konformitat durch:

1. Niemals rohe Kartendaten verarbeiten - Alle Kartenerfassung verwendet Stripe Elements/SDK
2. Nur Tokens speichern - Nur Stripe-Zahlungsmethoden-IDs werden gespeichert
3. Kartennummern maskieren - Nur letzte 4 Ziffern werden gespeichert
4. Sichere Ubertragung - Alle API-Aufrufe verwenden HTTPS
5. Webhook-Verifizierung - Alle Stripe-Webhooks werden signaturverifiziert

Zugriffskontrolle

Zahlungsmethodenoperationen erfordern authentifizierte Benutzer mit entsprechenden Rollen:

Loschverhalten

Beim Loschen einer Zahlungsmethode:

1. Stripe-Trennung - Karte wird vom Stripe-Kunden getrennt
2. Lokale Loschung - Datensatz aus Datenbank entfernt
3. Standard-Neuzuweisung - Wenn Standard geloscht wurde, wird nachstalteste zum Standard
4. Beide Umgebungen versucht - System versucht sowohl Live- als auch Test-Stripe fur Bereinigung

Fehlerbehebung

Haufige Probleme

"Stripe-Formular konnte nicht initialisiert werden"

Ursache: Setup Intent-Erstellung fehlgeschlagen

Losungen:

1. Prufen Sie, ob Stripe-API-Schlussel korrekt sind
2. Uberprufen Sie, ob Kunde eine Stripe-Kunden-ID hat
3. Prufen Sie das Stripe-Dashboard auf Ratenlimits

Karte erscheint nach dem Hinzufugen nicht

Ursache: Registrierung nach SetupIntent fehlgeschlagen

Losungen:

1. Prufen Sie die Browser-Konsole auf Fehler
2. Uberprufen Sie, ob Webhook setup_intent.succeeded empfangt
3. Prufen Sie die Datenbank auf verwaiste Zahlungsmethoden

"Keine Zahlungsmethode hinterlegt" bei Auto-Aufladung

Ursache: Kunde hat keine Zahlungsmethoden oder keinen Standard

Losungen:

1. Prufen Sie payment_methods-Tabelle fur den Kunden
2. Uberprufen Sie, dass mindestens eine Karte is_default = true hat
3. Fugen Sie eine Zahlungsmethode hinzu, wenn keine existiert

Testmodus funktioniert nicht

Ursache: Test-Schlussel nicht konfiguriert

Losungen:

1. Uberprufen Sie, ob STRIPE_TEST_SECRET_KEY gesetzt ist
2. Uberprufen Sie, ob STRIPE_TEST_PUBLISHABLE_KEY gesetzt ist
3. Stellen Sie sicher, dass Benutzer super_admin ist oder Kunde @levyelectric.com-E-Mail hat

Diagnoseabfragen

Zahlungsmethoden eines Kunden auflisten

SELECT
  pm.id,
  pm.brand,
  pm.last4,
  pm.is_default,
  pm.created_at,
  c.email
FROM payment_methods pm
JOIN customers c ON c.id = pm.customer_uuid
WHERE c.id = 'kunden-uuid-hier'
ORDER BY pm.created_at;

Kunden ohne Zahlungsmethoden finden

SELECT
  c.id,
  c.email,
  c.full_name,
  c.stripe_customer_id
FROM customers c
LEFT JOIN payment_methods pm ON pm.customer_uuid = c.id
WHERE pm.id IS NULL
  AND c.stripe_customer_id IS NOT NULL
ORDER BY c.created_at DESC
LIMIT 50;

Auf doppelte Zahlungsmethoden prufen

SELECT
  stripe_payment_method_id,
  COUNT(*) as count
FROM payment_methods
GROUP BY stripe_payment_method_id
HAVING COUNT(*) > 1;

Bewahrte Praktiken

Fur Betreiber

1. Mehrere Karten fordern - Kunden mit Backup-Karten haben weniger Zahlungsausfalle
2. Abgelehnte Karten uberwachen - Mit Kunden nachfassen, deren Karten fehlschlagen
3. Testmodus verwenden - Immer Kartenablaufe mit Testkarten testen, bevor in Produktion

Fur den Kundensupport

1. Vor dem Hinzufugen verifizieren - Kundenidentitat vor dem Hinzufugen von Zahlungsmethoden bestatigen
2. Den Prozess erklaren - Kunden helfen zu verstehen, warum Karten benotigt werden
3. Probleme dokumentieren - Kartenbezogene Probleme zur Fehlerbehebung aufzeichnen

Nachste Schritte

• Stripe-Einrichtung - Stripe-Integration konfigurieren
• Automatische Ruckerstattungen - Wie automatische Ruckerstattungen funktionieren
• Schadensgebuhren - Kunden fur Schaden belasten