Wallet-Verwaltung

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.

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

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

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:

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, 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 (oder Alle auswaehlen), klicken Sie auf Process, und das System versucht, die gespeicherte Zahlungsmethode jedes Kunden um den Betrag zu belasten, der noetig ist, um das Guthaben auf null zu bringen.

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.

Transaktionshistorie

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.
• Unterkonto-Einstellung: auto_topup_enabled am Unterkonto, mit auto_topup_amount_cents und auto_topup_threshold_cents.

Standardwerte

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.

Best Practices

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.
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.

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.

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, eskalieren Sie das — customers.wallet_balance ist moeglicherweise nicht synchron.

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.
• Gleichen Sie die Wallet-Aktivitaet des Kunden mit einem passenden ride_refund-Eintrag ab.