Wallet & Zahlungen

Diese Anleitung behandelt das Kunden-Wallet-System, Zahlungsmethoden, Auto-Auflade-Funktionalitat und Zahlungsabwicklung. Das Verstandnis dieser Systeme ist fur Betreiber bei der Fehlerbehebung von Abrechnungsproblemen und fur Kunden bei der Verwaltung ihrer Zahlungspraferenzen unerlasslich.

---

Ubersicht

Das Zahlungssystem besteht aus drei Hauptkomponenten:

1. Kunden-Wallet - Ein Guthabenkonto fur Fahrtzahlungen
2. Zahlungsmethoden - Gespeicherte Kredit-/Debitkarten, die mit Stripe verknupft sind
3. Auto-Aufladung - Automatische Wallet-Auffullung bei niedrigem Guthaben

Fahrten werden vom Wallet-Guthaben bezahlt. Wenn das Guthaben nicht ausreicht, kann das System automatisch die Standard-Zahlungsmethode des Kunden belasten.

---

Kunden-Wallet

Funktionsweise des Wallets

Jeder Kunde hat ein Wallet-Guthaben, das:

• Guthaben in USD speichert
• Zur Bezahlung von Fahrten verwendet wird
• Manuell oder automatisch aufgeladen werden kann
• Gutschriften aus Aktionscodes, Empfehlungen und Treuepunkt-Einlosung erhalt

Wallet-Guthaben-Fluss:

Gutschriften REIN:
  - Manuelle Aufladung (Kunde fugt Guthaben hinzu)
  - Auto-Aufladung (automatisch bei niedrigem Stand)
  - Aktionscode-Einlosung
  - Empfehlungspramien
  - Treuepunkt-Einlosung
  - Kundendienst-Gutschriften

Abbuchungen RAUS:
  - Fahrtgebuhren
  - Abonnement-Kaufe
  - Paket-Kaufe

Wallet-Guthaben-Anzeige

Kunden sehen ihr Wallet-Guthaben:

• Auf dem Startbildschirm der mobilen App
• Vor dem Starten einer Fahrt
• Auf Fahrtquittungen
• In den Kontoeinstellungen

Format: Immer in Dollar mit 2 Dezimalstellen angezeigt (z.B. "25,00 $")

Mindestguthaben-Anforderungen

Um eine Fahrt zu starten, mussen Kunden haben:

• Positives Wallet-Guthaben, ODER
• Gultige Zahlungsmethode fur Auto-Aufladung, ODER
• Aktives Abonnement/Paket, das die Fahrt abdeckt

---

Manuelle Aufladung

Kunden-Auflade-Ablauf

1. Kunde offnet Wallet-/Zahlungsbereich
2. Wahlt oder gibt Aufladebetrag ein
3. Wahlt Zahlungsmethode
4. Bestatigt Zahlung
5. Wallet-Guthaben wird sofort aktualisiert

Aufladebeträge

Betreiber konnen voreingestellte Betrage konfigurieren:

Auflade-Verarbeitung

Aufladungen werden uber Stripe verarbeitet:

1. PaymentIntent mit Betrag erstellen
2. Mit Zahlungsmethode des Kunden bestatigen
3. Bei Erfolg: Wallet-Guthaben erhohen
4. Wallet-Transaktionsdatensatz erstellen
5. Bestatigung senden (E-Mail/Push)

---

Auto-Aufladung

Funktionsweise der Auto-Aufladung

Auto-Aufladung belastet automatisch den Kunden, wenn sein Wallet-Guthaben unter einen Schwellenwert fallt:

Wenn wallet_balance ≤ threshold:
  Standard-Zahlungsmethode mit Aufladebetrag belasten
  Guthaben zum Wallet hinzufugen

Wann sie auslost:

• Vor Fahrtbeginn (wenn Guthaben unzureichend)
• Nach Fahrtende (wenn Guthaben negativ wurde)
• Wahrend der Fahrt (fur Echtzeit-Abrechnung)

Konfigurationsanforderungen

Auto-Aufladung erfordert BEIDES:

1. Kunden-Opt-in - Kunde aktiviert Auto-Aufladung in seinen Einstellungen
2. Unterkonto aktiviert - Betreiber aktiviert Auto-Aufladung fur den Standort

Konfigurationsoptionen

Unterkonto-Einstellungen:

Beispielkonfiguration:

• Schwellenwert: 5,00 $ (500 Cents)
• Aufladebetrag: 15,00 $ (1500 Cents)

Wenn das Wallet auf 5 $ oder darunter fallt, belastet das System automatisch 15 $.

Auto-Auflade-Ablauf

1. Prufen, ob Kunde Auto-Aufladung erlaubt (customer.auto_topup_enabled)
2. Prufen, ob Unterkonto Auto-Aufladung erlaubt (subaccount.auto_topup_enabled)
3. Schwellenwert und Betrag aus Unterkonto-Einstellungen abrufen
4. Wenn wallet_balance ≤ threshold:
   a. Sperre erwerben (doppelte Abbuchungen verhindern)
   b. Standard-Zahlungsmethode des Kunden abrufen
   c. Stripe PaymentIntent erstellen
   d. Zahlung bestatigen (off_session)
   e. Wallet-Guthaben erhohen
   f. Transaktion aufzeichnen
   g. Sperre freigeben

Nebenlaufigkeitsschutz

Das System verhindert doppelte Abbuchungen durch eine Datenbanksperre:

Sperr-Ablauf:

1. Versuchen, Sperre zu erwerben (2-Minuten-TTL)
2. Wenn Sperre erworben, mit Abbuchung fortfahren
3. Wenn Sperre existiert (anderer Prozess belastet), warten und auf Guthabenerhohung prufen
4. Sperre nach Abschluss freigeben

Fehlerbehandlung

---

Zahlungsmethoden

Zahlungsmethoden speichern

Zahlungsmethoden werden uber Stripe gespeichert:

1. Kunde gibt Kartendetails ein
2. Karte wird von Stripe.js tokenisiert (PCI-konform)
3. PaymentMethod wird an Stripe Customer angehangt
4. Referenz wird in lokaler Datenbank gespeichert

Zahlungsmethoden-Tabelle

Standard-Zahlungsmethode

Eine Zahlungsmethode ist als Standard markiert:

• Wird fur Auto-Aufladung verwendet
• Wird fur manuelle Aufladung verwendet (ausser eine andere wird ausgewahlt)
• Wird fur Abonnement-Abbuchungen verwendet

Standard festlegen:

1. Kunde wahlt "Als Standard festlegen" in der App
2. System aktualisiert is_default-Flag
3. Synchronisiert mit Stripes invoice_settings.default_payment_method

Zahlungsmethoden verwalten

Karte hinzufugen:

1. Kunde tippt auf "Zahlungsmethode hinzufugen"
2. Stripe Elements erfasst Kartendetails
3. Karte wird validiert und tokenisiert
4. PaymentMethod wird erstellt und gespeichert

Karte entfernen:

1. Kunde wahlt zu entfernende Karte
2. System pruft, ob es nicht die einzige Karte ist (wenn Auto-Aufladung aktiviert)
3. PaymentMethod wird von Stripe Customer getrennt
4. Lokaler Datensatz wird geloscht

Karte aktualisieren: Karten konnen nicht aktualisiert werden - Kunde muss neue Karte hinzufugen und alte entfernen.

---

Wallet-Transaktionen

Transaktionstypen

Transaktionsdatensatz

Transaktionshistorie anzeigen

Kunden konnen ihre Transaktionshistorie anzeigen:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  WALLET-HISTORIE

  Heute
  ─────
  Fahrt abgeschlossen              -7,35 $
  Guthaben: 17,65 $

  Gestern
  ─────────
  Auto-Aufladung                   +15,00 $
  Guthaben: 25,00 $

  Fahrt abgeschlossen              -8,50 $
  Guthaben: 10,00 $

  23. Dez.
  ─────────
  Aktionscode HOLIDAY10            +10,00 $
  Guthaben: 18,50 $

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Fahrtzahlungs-Ablauf

Guthabenprofung bei Fahrtstart

Wenn ein Kunde eine Fahrt startet:

1. Wallet-Guthaben prufen - Ist es uber 0 $?
2. Auto-Auflade-Berechtigung prufen - Ist sie aktiviert und hat Zahlungsmethode?
3. Abdeckung prufen - Deckt Abonnement/Paket die Fahrt ab?

Wenn keines der oben genannten erfullt ist, kann die Fahrt nicht gestartet werden.

Zahlung bei Fahrtende

Wenn eine Fahrt endet:

1. Endgultige Fahrtgebuhr berechnen
2. Aktuelles Wallet-Guthaben prufen
3. Wenn Guthaben >= Gebuhr:
   - Vom Wallet abziehen
   - Transaktion aufzeichnen
4. Wenn Guthaben < Gebuhr UND Auto-Aufladung aktiviert:
   - Zuerst Auto-Aufladung verarbeiten
   - Dann Fahrtgebuhr abziehen
5. Wenn Guthaben < Gebuhr UND keine Auto-Aufladung:
   - Verfugbares Guthaben abziehen
   - Ausstehenden Betrag aufzeichnen
   - Zahlungswiederholung planen

Zahlungswiederholungs-System

Wenn ein Kunde einen ausstehenden Betrag hat:

1. Wiederholung planen - Zur Hintergrund-Wiederholungswarteschlange hinzufugen
2. Wiederholungsversuche - Versuchen, im Laufe der Zeit einzuziehen
3. Benachrichtigung - Kunden uber fehlgeschlagene Zahlung informieren
4. Kontobeschrankung - Neue Fahrten blockieren, bis Guthaben ausgeglichen

Wiederholungszeitplan:

---

Betreiber-Dashboard

Kunden-Wallet anzeigen

In der Kundendetailansicht:

Manuelle Wallet-Anpassungen

Betreiber konnen Wallet-Guthaben anpassen:

Guthaben hinzufugen:

• Kundendienst-Gesten
• Ruckerstattungen fur Serviceprobleme
• Werbeguthaben

Guthaben entfernen:

• Betrugskorrekturen
• Fehlerkorrekturen

Alle Anpassungen erfordern:

• Betrag
• Grund/Beschreibung
• Betreiber-Authentifizierung

Transaktionsexport

Wallet-Transaktionen exportieren fur:

• Buchhaltungsabstimmung
• Kundenstreitigkeiten
• Prufungszwecke

---

Stripe-Integration

Test- vs. Live-Modus

Das System unterstutzt beide Stripe-Modi:

Testmodus-Auswahl:

• @levyelectric.com-E-Mails verwenden Testmodus
• Alle anderen Kunden verwenden Live-Modus

Verwendete Stripe-Objekte

Webhooks

Stripe-Webhooks aktualisieren lokale Datensatze:

---

Sicherheitsuberlegungen

PCI-Konformitat

• Kartennummern beruhren niemals unsere Server
• Alle Kartenerfassung uber Stripe.js/Elements
• Nur tokenisierte Referenzen speichern

Datenschutz

• Wallet-Guthaben im Ruhezustand verschlusselt
• Transaktionshistorie-Zugang kontrolliert
• Zahlungsmethoden-Zugang beschrankt

Betrugspravention

• Geschwindigkeitsbegrenzungen fur Aufladungen
• Erkennung ungewohnlicher Aktivitaten
• Manuelle Uberprufungsschwellenwerte

---

Technische Referenz

Datenbanktabellen

customers (Wallet-Felder)

payment_methods

wallet_transactions

subaccounts (Auto-Auflade-Felder)

Kernfunktionen

API-Endpunkte

---

Fehlerbehebung

Auto-Aufladung funktioniert nicht

1. Kundeneinstellung prufen - Ist auto_topup_enabled true?
2. Unterkonto-Einstellung prufen - Ist Auto-Aufladung fur Standort aktiviert?
3. Zahlungsmethode verifizieren - Gibt es eine Standard-Karte?
4. Stripe-Kunden prufen - Ist stripe_customer_id gultig?
5. Sperrstatus uberprufen - Gibt es eine veraltete Sperre, die blockiert?

Zahlung fehlgeschlagen

1. Stripe-Fehler prufen - Karte abgelehnt? Abgelaufen? 3DS erforderlich?
2. Zahlungsmethode verifizieren - Ist sie noch in Stripe gultig?
3. Kontostatus uberprufen - Ist Stripe-Konto aktiv?
4. Idempotenz prufen - Wurde dieselbe Abbuchung zweimal versucht?

Wallet-Guthaben falsch

1. Transaktionshistorie uberprufen - Welche Transaktionen sind aufgetreten?
2. Auf ausstehende Abbuchungen prufen - Gibt es laufende Zahlungen?
3. Fahrtgebuhren verifizieren - Wurden Fahrten korrekt abgerechnet?
4. Auf Duplikate prufen - Gibt es doppelte Transaktionen?

Kann Fahrt nicht starten

1. Wallet-Guthaben prufen - Ist es 0 $ oder negativ?
2. Auto-Aufladung verifizieren - Ist sie aktiviert und funktional?
3. Zahlungsmethode prufen - Gibt es eine gultige Karte?
4. Ausstehenden Betrag uberprufen - Gibt es unbezahlte Gebuhren?

---