Kunden-Wallets & Bonus-Guthaben

Jeder Kunde hat ein einziges Wallet-Guthaben (wallet_balance), das Fahrten finanziert. Dieser Leitfaden erklaert, wie das Wallet funktioniert, wie Betreiber es anpassen koennen, wie die automatische Aufladung konfiguriert wird und wie Rueckerstattungen mit dem Wallet interagieren.

Das Wallet-Guthaben

Jeder Kunde hat genau einen effektiven Saldo: das Wallet-Guthaben. Alle manuellen Anpassungen (Gutschriften, Boni, Gebuehren, Abbuchungen) und automatisierten Ablaeufe (Fahrtkosten, Rueckerstattungen, automatische Aufladungen) erhoehen oder verringern diesen einen Saldo.

In der Kundenliste und auf der Kunden-Detailseite sehen Sie ausserdem eine Bonus-Spalte. Dies ist ein veraltetes, rein anzeigendes Feld, das durch Kundenimporte befuellt wird — es wird bei der Fahrtzahlung nicht separat verbraucht und nicht durch die "Bonus hinzufuegen"-Aktion im Dashboard veraendert. Behandeln Sie es als historischen Kontext, nicht als aktiven Saldo.

Wie Zahlungen auf eine Fahrt angewendet werden

Mindestguthaben zum Starten einer Fahrt

Kunden muessen mindestens 0,50 $ im Wallet haben, um eine Fahrt zu starten — es sei denn, sie erfuellen die Ausnahmebedingungen.

Ausnahme fuer die Guthabenpruefung (Fahrt mit 0 $ Guthaben starten): Der Kunde muss beide Bedingungen erfuellen

1. ein aktives Abonnement oder ein aktives Fahrtenpaket mit verbleibenden Fahrten/Minuten, und
2. eine gespeicherte Zahlungsmethode.

Negatives Guthaben

Das Wallet darf negativ werden. Das passiert, wenn:

• eine Gebuehr (Charge Fee) berechnet wird, die das aktuelle Guthaben uebersteigt.
• die Fahrtkosten das Guthaben uebersteigen und die Kartenzahlung fehlschlaegt.
• der Betreiber Guthaben reduzieren (Reduce Balance) mit einem Betrag groesser als das aktuelle Guthaben verwendet.

Wenn eine Gebuehr dazu fuehrt, dass das Guthaben von positiv auf negativ wechselt, erhaelt der Kunde automatisch eine Push-Benachrichtigung ueber das negative Guthaben.

Zugriff auf Wallet-Informationen

Kundenliste

Die Liste zeigt fuer jeden Kunden das Wallet-Guthaben und (falls vorhanden) den veralteten Bonus-Betrag in getrennten Spalten.

Kunden-Detailseite

Navigieren Sie zu Dashboard > Kunden > [Kunde], um Folgendes zu sehen:

• Aktuelles Wallet-Guthaben und Bonus-Betrag
• Ein Wallet-Dropdown in der Aktionsleiste mit: Bonus hinzufuegen, Gebuehr berechnen, Guthaben reduzieren
• Einen Link Wallet-Aktivitaet anzeigen zur vollstaendigen Transaktionshistorie

Wallet-Aktivitaetsseite

Die Aktivitaetsseite listet jede Zeile aus wallet_transactions fuer den Kunden auf, einschliesslich:

• Datum und Beschreibung
• Reference-Typ (ride, topup, manual_bonus, manual_charge, manual_reduce_balance, stripe_charge, usw.)
• Betrag (Gutschriften gruen, Abbuchungen rot)
• Laufender balance_after

Wallet-Guthaben hinzufuegen

Das Dashboard bietet drei Aktionen im Wallet-Dropdown des Kunden. Alle drei schreiben in das einzelne wallet_balance und erzeugen eine wallet_transactions-Zeile.

Bonus hinzufuegen

Werbe- oder Kulanz-Gutschrift. Erhoeht das Wallet-Guthaben.

• Transaktion: type: 'credit', reference_type: 'manual_bonus'
• Benachrichtigung: keine
• API: POST /api/customers/bonus

{
  "customer_uuid": "customer-uuid",
  "amount_usd": 5.00
}

Zulaessige Identifikations-Felder (mindestens eins angeben): customer_uuid, customer_number, auth_uid, email oder customer_identifier.

Typische Gruende fuer Gutschriften

Gebuehren berechnen & Guthaben reduzieren

Gebuehr berechnen (Charge Fee)

Fuer Schaeden, verlorene Ausruestung, Parkverstoesse und aehnliche Strafen.

• Transaktion: type: 'debit', reference_type: 'manual_charge'
• Kann negativ werden: ja
• Benachrichtigung: Push-Benachrichtigung, wenn das Guthaben von positiv auf negativ wechselt
• Berechtigung: erfordert customer:charge — Analysten und Service-Techniker sind gesperrt
• API: POST /api/customers/charge

{
  "customer_uuid": "customer-uuid",
  "amount_usd": 25.00
}

Guthaben reduzieren (Reduce Balance)

Fuer stille Korrekturen und Anpassungen, die den Kunden nicht benachrichtigen sollen.

• Transaktion: type: 'debit', reference_type: 'manual_reduce_balance'
• Kann negativ werden: ja (gleiches Verhalten wie Charge Fee)
• Benachrichtigung: nie
• Berechtigung: erfordert customer:charge
• API: POST /api/customers/reduce-balance

{
  "customer_uuid": "customer-uuid",
  "amount_usd": 10.00
}

Charge Fee vs. Reduce Balance

Rueckerstattungen: Immer gegen die Fahrt

Verwenden Sie je nach Situation einen dieser beiden Endpoints:

Tarifanpassung — wenn der Kunde zu viel berechnet wurde (z. B. fuer Zeit abgerechnet, die er nicht genutzt hat):

POST /api/rides/[id]/adjust-fare
{
  "newTotalCost": 8.50,
  "reason": "Anpassung an tatsaechliche Fahrtdauer"
}

Dies berechnet die Steuer neu, passt die Fahrt an, schreibt dem Wallet bei Ueberzahlung gut und aktualisiert net_deposited.

Rueckerstattung — wenn der Tarif korrekt ist, der Kunde aber Geld zurueckbekommen soll:

POST /api/rides/[id]/refunds
{
  "destination": "wallet",
  "mode": "full",
  "reason": "Kompensation fuer Fahrer"
}

destination kann wallet oder card sein. mode kann full oder partial (mit amount) sein. Die API erstattet gegen das, was tatsaechlich gezahlt wurde (Karte oder Wallet), erfasst es in ride_refunds und aktualisiert net_deposited.

Fuer Kulanz-Gutschriften, die nicht an eine bestimmte Fahrt gebunden sind, verwenden Sie Bonus hinzufuegen auf der Kunden-Detailseite.

Massen-Wallet-Verarbeitung

Die Aktion Bulk Wallet Processing in der Kundenliste ist kein Tool zum Hochladen von Gutschriften. Es ist ein Inkasso-Tool, das gespeicherte Zahlungsmethoden fuer Kunden mit negativem Wallet-Guthaben belastet.

• Waehlen Sie Kunden manuell aus oder verwenden Sie Alle auswaehlen, um alle aktuell gefilterten Kunden mit negativem Guthaben und hinterlegtem Stripe-Kunden zu erfassen.
• Klicken Sie auf Process — das System versucht, die gespeicherte Zahlungsmethode jedes Kunden um den Betrag zu belasten, der noetig ist, um das Guthaben auf null zu bringen.
• Die Ergebnisse zeigen fuer jeden Kunden scheduled, skipped, already_exists oder error.

Es gibt derzeit keinen CSV-Upload-Flow zum Massen-Gutschreiben — fuegen Sie Gutschriften einzeln ueber das Dashboard hinzu oder scripten Sie den Endpoint /api/customers/bonus.

Wallet-Transaktionen

Jede Aenderung an wallet_balance erzeugt eine wallet_transactions-Zeile. Transaktionen haben einen type (credit oder debit) und einen reference_type, der die Quelle kategorisiert.

Gaengige reference_type-Werte

Die Wallet-Aktivitaets-UI gruppiert und beschriftet diese fuer Betreiber — die obigen Rohwerte sehen Sie in der Datenbank und in API-Antworten.

Automatische Aufladung (Auto Top-up)

Die automatische Aufladung ergaenzt das Wallet eines Kunden automatisch, wenn es unter einen Schwellenwert faellt, und belastet dabei die Standard-Zahlungsmethode.

Funktionsweise

1. Das Wallet-Guthaben des Kunden faellt unter den Schwellenwert (typischerweise bei einer Pruefung beim Fahrtstart oder bei der Zahlung).
2. Das System belastet die Standard-Zahlungsmethode mit dem konfigurierten Aufladebetrag.
3. Dem Wallet wird gutgeschrieben.
4. Der Kunde erhaelt eine Push-Benachrichtigung zur Bestaetigung der Aufladung.

Konfiguration (beides muss zutreffen)

• Kundeneinstellung: auto_topup_enabled im Kundendatensatz — Kunden opten waehrend der Registrierung ein (wir praesentieren Auto-Aufladen als Moeglichkeit, das Fahrzeug mitten in der Fahrt nicht deaktiviert zu bekommen; nahezu alle Kunden aktivieren es).
• Unterkonto-Einstellung: auto_topup_enabled am Unterkonto, mit auto_topup_amount_cents und auto_topup_threshold_cents.

Standardwerte

Beispiel: Faellt das Guthaben unter 5,00 $, belastet das System 15,00 $ und schreibt diese dem Wallet gut.

Sicherheit

• Datenbank-Locks verhindern, dass gleichzeitige Auto-Aufladeversuche doppelt belasten.
• Stripe-Idempotenz-Keys verhindern doppelte Belastungen bei Netzwerk-Retries.
• Der Schwellenwert wird nach dem Lock erneut geprueft.
• Konten mit @levyelectric.com laufen gegen den Stripe-Testmodus.

Fehlersuche bei der automatischen Aufladung

1. Pruefen Sie, dass beim Kunden auto_topup_enabled gesetzt ist.
2. Pruefen Sie, dass das Unterkonto auto_topup_enabled sowie sinnvolle Amount/Threshold-Werte hat.
3. Bestaetigen Sie, dass der Kunde eine gueltige Standard-Zahlungsmethode hat.
4. Pruefen Sie Stripe auf Ablehnungen.
5. Suchen Sie in wallet_transactions nach aktuellen topup-Eintraegen.

Berichte

Zusammenfassungs-Metriken

Die Kopfzeile der Kundenliste zeigt den Gesamtwert aller Wallets und Boni ueber die aktuell gefilterte Ansicht.

Audits von Guthaben-Aenderungen

• Oeffnen Sie die Seite Wallet-Aktivitaet eines Kunden, um jede Transaktion mit Zeitstempel und balance_after zu sehen.
• Gleichen Sie ride-Debits mit dem Fahrt-Datensatz ab — der net_deposited-Wert der Fahrt sollte mit Wallet-Debit + Kartenbelastung minus etwaiger Rueckerstattungen uebereinstimmen.
• Fuer manuelle Anpassungen wird die user.id des Betreibers als reference_id in manual_bonus- / manual_charge-Transaktionen gespeichert; das Dashboard loest dies zu einem Mitarbeiternamen auf.

Best Practices

Fuer Betreiber

1. Dokumentieren Sie jede manuelle Anpassung — die Betreiber-Identitaet wird gespeichert, aber ein Grund in der Beschreibung hilft bei spaeteren Audits.
2. Verwenden Sie den Fahrt-Rueckerstattungs-Flow fuer Fahrtprobleme — kompensieren Sie Fahrtprobleme niemals mit einer direkten Gutschrift, sonst stimmen Partner-Auszahlungen und Steuerberechnung nicht mehr.
3. Reservieren Sie Bonus hinzufuegen fuer Promotions und Kulanz, die nicht an eine bestimmte Fahrt gebunden sind.
4. Rechte einschraenken — nur Admin-Rollen und hoeher sollten customer:charge haben.

Fuer den Kundenservice

1. Pruefen Sie das aktuelle Guthaben und die letzten Wallet-Aktivitaeten, bevor Sie Gutschriften hinzufuegen oder entfernen.
2. Bei einer Anpassung wegen eines Fahrtproblems oeffnen Sie die Fahrt und verwenden Sie Tarifanpassung oder Rueckerstattung anstelle des Wallet-Dropdowns.
3. Kommunizieren Sie dem Kunden: Gutschriften werden bei der naechsten Fahrt automatisch angewendet.

Fehlersuche

Gutschrift erscheint nicht in der Kunden-App

• Bestaetigen Sie, dass die Transaktion in der Wallet-Aktivitaet des Kunden steht.
• Bitten Sie den Kunden, die App zu beenden und neu zu oeffnen.
• Pruefen Sie, dass Sie den richtigen Kunden angepasst haben (customer_number / E-Mail pruefen).

Wallet-Guthaben sieht falsch aus

• Pruefen Sie die letzten Transaktionen auf unerwartete Abbuchungen oder doppelte Gutschriften.
• Pruefen Sie die Fahrthistorie auf automatische Abbuchungen (reference_type: 'ride').
• Stimmt das Guthaben nicht mit der Summe der Transaktionen ueberein, ist moeglicherweise customers.wallet_balance nicht mit wallet_transactions synchron — eskalieren Sie das.

Kunde sagt, seine Fahrt-Rueckerstattung sei nicht angekommen

• Oeffnen Sie die Fahrt-Detailseite und pruefen Sie den Bereich Rueckerstattungen.
• Bestaetigen Sie, dass die Rueckerstattung ueber /api/rides/[id]/refunds oder /api/rides/[id]/adjust-fare verarbeitet wurde (keine direkte Gutschrift).
• Gleichen Sie die Wallet-Aktivitaet des Kunden mit einem passenden ride_refund-Eintrag ab.