Kunden-Wallets & Boni

Levy Fleets bietet ein flexibles Wallet- und Bonussystem, das es Kunden ermoeglicht, Guthaben fuer Fahrten zu speichern, und Betreibern die Moeglichkeit gibt, Kunden mit Werbeboni zu belohnen. Dieser Leitfaden behandelt alles von den verschiedenen Guthabenarten bis hin zur Verwaltung von Wallet-Transaktionen und Bonusguthaben.

Wallets vs. Boni verstehen

Das System verwaltet zwei separate Guthabenarten fuer jeden Kunden:

Wie Zahlungen angewendet werden

Beispiel: Kunde hat 5,00 $ Bonus, 10,00 $ Wallet und die Fahrt kostet 12,00 $

1. Bonus wird zuerst angewendet: 5,00 $ Bonus verbraucht, 0,00 $ Bonus verbleibend
2. Wallet wird als zweites angewendet: 7,00 $ vom Wallet, 3,00 $ Wallet verbleibend
3. Karte wird belastet: 0,00 $ (Fahrt vollstaendig durch Guthaben gedeckt)

Wenn die Fahrt stattdessen 20,00 $ kosten wuerde:

1. Bonus: 5,00 $ verbraucht, 0,00 $ verbleibend
2. Wallet: 10,00 $ verbraucht, 0,00 $ verbleibend
3. Karte belastet: 5,00 $

Mindestguthaben-Anforderungen

Um eine Fahrt zu starten, muessen Kunden ein Mindest-Wallet-Guthaben von 0,50 $ haben, es sei denn, sie qualifizieren sich fuer eine Wallet-Pruefungsbefreiung (siehe Fahrtberechtigung unten).

Fahrtberechtigung & Wallet-Pruefungsbefreiungen

Kunden koennen die Wallet-Guthaben-Pruefung ueberspringen, wenn ALLE der folgenden Punkte zutreffen:

1. Kunde hat ein aktives Abonnement ODER ein aktives Fahrtpaket mit verbleibenden Fahrten/Minuten
2. Kunde hat eine gespeicherte Zahlungsmethode hinterlegt

Dies ermoeglicht es Abonnement- und Paketkunden, auch mit 0 $ Wallet-Guthaben zu fahren, da ihre Fahrten durch ihren gekauften Plan abgedeckt sind.

Negative Guthaben

Wallet-Guthaben koennen in bestimmten Situationen negativ werden:

• Wenn Betreiber eine Gebuehr erheben, die das aktuelle Guthaben uebersteigt
• Wenn die Fahrtkosten das verfuegbare Guthaben uebersteigen und die Kartenbelastung fehlschlaegt

Zugriff auf Wallet-Informationen

Von der Kundenliste

Die Kundenliste zeigt Wallet- und Bonus-Guthaben in separaten Spalten:

• Wallet: Zeigt den aktuellen Wallet-Guthabenbetrag
• Bonus: Zeigt den aktuellen Bonusbetrag

Von der Kunden-Detailseite

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

• Wallet-Guthaben-Karte: Aktuelles Guthaben mit "Guthaben hinzufuegen"-Button
• Bonus-Guthaben-Karte: Aktueller Bonusbetrag
• Wallet-Aktivitaet anzeigen: Link zur detaillierten Transaktionshistorie

Wallet-Aktivitaetsseite

Greifen Sie auf die detaillierte Transaktionshistorie zu unter: Dashboard > Kunden > [Kunde] > Wallet-Aktivitaet

Diese Seite zeigt:

• Vollstaendige Liste der Wallet-Guthaben-Transaktionen
• Datum und Uhrzeit jeder Transaktion
• Transaktionsbeschreibung
• Quelle/Methode des Guthabens
• Betrag (Gutschriften in Gruen, Belastungen in Rot)
• Laufendes Guthaben nach jeder Transaktion

Wallet-Guthaben hinzufuegen

Manuelles Guthaben (Einzelner Kunde)

1. Navigieren Sie zur Detailseite des Kunden
2. Klicken Sie im Wallet-Bereich auf Guthaben hinzufuegen (oder den "+"-Button)
3. Geben Sie den Guthabenbetrag ein
4. Fuegen Sie optional eine Notiz hinzu, die den Grund erklaert
5. Klicken Sie auf Guthaben hinzufuegen, um es anzuwenden

Das Guthaben erscheint sofort in:

• Wallet-Guthaben des Kunden
• Wallet-Aktivitaetshistorie
• Mobile App des Kunden

Haeufige Gruende fuer manuelles Guthaben

Gebuehren erheben & Guthaben reduzieren

Gebuehr erheben

Verwenden Sie "Gebuehr erheben", um Gebuehren fuer Schaeden, verlorene Ausruestung, Parkverstaoesse oder andere Strafen zu erheben.

So erheben Sie eine Gebuehr:

1. Navigieren Sie zur Kunden-Detailseite
2. Klicken Sie auf das Wallet-Dropdown in der Aktionsleiste
3. Waehlen Sie Gebuehr erheben
4. Geben Sie den Betrag ein
5. Fuegen Sie eine Beschreibung/Grund hinzu
6. Klicken Sie auf Gebuehr erheben

API-Endpunkt: POST /api/customers/charge

{
  "customerIdentityId": "customer-identity-uuid",
  "amount_usd": 25.00,
  "description": "Parking violation fee"
}

Guthaben reduzieren (Manuelle Belastung)

Verwenden Sie "Guthaben reduzieren" fuer Korrekturen, Anpassungen oder stille Belastungen, die den Kunden nicht benachrichtigen sollen.

So reduzieren Sie das Guthaben:

1. Navigieren Sie zur Kunden-Detailseite
2. Klicken Sie auf das Wallet-Dropdown in der Aktionsleiste
3. Waehlen Sie Guthaben reduzieren
4. Geben Sie den Betrag ein
5. Fuegen Sie einen Grund/Notiz hinzu
6. Klicken Sie auf Guthaben reduzieren

Wichtige Verhaltensweisen:

• Keine Benachrichtigung: Der Kunde wird nicht ueber die Abbuchung benachrichtigt
• Kann nicht negativ werden: Das Guthaben stoppt bei 0 $ (im Gegensatz zu "Gebuehr erheben")
• Erstellt Transaktionseintrag: Wird als Typ debit mit Referenz manual_reduce_balance protokolliert

API-Endpunkt: POST /api/customers/reduce-balance

{
  "customerUuid": "customer-uuid",
  "amount_usd": 10.00,
  "description": "Correction for duplicate credit"
}

Gebuehr erheben vs. Guthaben reduzieren

Massen-Wallet-Verarbeitung

Zum Hinzufuegen von Guthaben fuer mehrere Kunden gleichzeitig:

1. Navigieren Sie zu Dashboard > Kunden
2. Klicken Sie auf Massen-Wallet-Verarbeitung im Seitenkopf
3. Bereiten Sie Ihre CSV-Datei mit dem erforderlichen Format vor
4. Laden Sie die CSV-Datei hoch
5. Ueberpruefen Sie die Vorschau, die alle Aenderungen zeigt
6. Klicken Sie auf Verarbeiten, um alle Guthaben anzuwenden

CSV-Format fuer Massenverarbeitung:

identifier,identifier_type,amount,note
cust_abc123,id,10.00,Holiday promotion
user@email.com,email,5.00,Service credit
+15551234567,phone,7.50,Referral bonus
12345,customer_number,15.00,Loyalty reward

Unterstuetzte Kennungstypen:

• id: Interne UUID des Kunden
• email: E-Mail-Adresse des Kunden
• phone: Telefonnummer des Kunden (mit Laendervorwahl)
• customer_number: Vom System zugewiesene Kundennummer

Bonus-Guthaben hinzufuegen

Ueber API

Bonus-Guthaben werden typischerweise ueber den Bonus-API-Endpunkt hinzugefuegt:

Endpunkt: POST /api/customers/bonus

Anfragekoerper:

{
  "customerId": "customer-uuid-here",
  "amount": 5.00,
  "reason": "Referral bonus"
}

Antwort:

{
  "success": true,
  "newBalance": 5.00,
  "previousBalance": 0.00
}

Ueber Dashboard

Von der Kunden-Detailseite:

1. Suchen Sie den Bonus-Guthaben-Bereich
2. Klicken Sie auf Bonus hinzufuegen (falls verfuegbar)
3. Geben Sie den Bonusbetrag ein
4. Fuegen Sie einen Grund/Notiz hinzu
5. Klicken Sie auf Bonus anwenden

Bonus vs. Wallet: Wann was verwenden

Wallet-Transaktionstypen

Gutschrift-Transaktionen

Gutschriften erhoehen das Wallet-Guthaben:

Belastungs-Transaktionen

Belastungen verringern das Wallet-Guthaben:

Details zur Wallet-Aktivitaet

Jede Transaktion auf der Wallet-Aktivitaetsseite zeigt:

Datumsspalte

• Transaktionszeitstempel
• Angezeigt in der Zeitzone des Benutzers
• Nach Datum sortierbar

Beschreibungsspalte

• Menschenlesbare Beschreibung der Transaktion
• Zeigt Transaktionstyp (Gutschrift/Belastung-Label)
• Kann zusaetzlichen Kontext enthalten

Quellenspalte

Zeigt an, woher die Transaktion stammt:

• Manuell: Vom Betreiber im Dashboard hinzugefuegt
• Stripe: Kartenbelastung oder Rueckerstattung
• System: Automatisiert (Aktion, Empfehlung, etc.)
• Fahrt: Mit einer bestimmten Fahrt verknuepft
• Masse: Aus Massenverarbeitungsvorgang

Betragsspalte

• Gruen mit +: Gutschrift (Geld hinzugefuegt)
• Rot mit -: Belastung (Geld entfernt)
• Angezeigt in der Waehrung des Kunden

Guthaben-nach-Spalte

• Zeigt das laufende Guthaben nach dieser Transaktion
• Nuetzlich fuer Pruefung und Abstimmung

Automatisches Aufladesystem

Die automatische Aufladefunktion fuellt das Wallet eines Kunden automatisch auf, wenn sein Guthaben unter einen konfigurierten Schwellenwert faellt.

Wie die automatische Aufladung funktioniert

1. Das Wallet-Guthaben des Kunden faellt unter den Schwellenwert
2. Das System erkennt niedriges Guthaben beim Fahrtstart oder bei der Zahlung
3. Eine automatische Belastung wird auf die Standard-Zahlungsmethode des Kunden verarbeitet
4. Das Wallet wird mit dem konfigurierten Aufladebetrag gutgeschrieben
5. Der Kunde erhaelt eine Push-Benachrichtigung zur Bestaetigung der Aufladung

Konfigurationsanforderungen

Kundeneinstellungen:

• auto_topup_enabled: Der Kunde muss dies in seinen App-Einstellungen aktivieren

Subaccount-Einstellungen:

• auto_topup_enabled: Subaccount muss die automatische Aufladefunktion aktiviert haben
• auto_topup_amount_cents: Aufzuladender Betrag (Standard: 15,00 $ / 1500 Cent)
• auto_topup_threshold_cents: Guthaben-Ausloesepunkt (Standard: 5,00 $ / 500 Cent)

Standardkonfiguration

Beispiel: Mit den Standardeinstellungen belastet das System automatisch die Karte des Kunden mit 15,00 $ und schreibt seinem Wallet gut, wenn sein Guthaben unter 5,00 $ faellt.

Ausloeser fuer automatische Aufladung

Die automatische Aufladung wird ausgeloest waehrend:

• Fahrtstart (wenn das Guthaben geprueft wird)
• Zahlungsverarbeitung (wenn das Wallet aufgebraucht ist)

Sicherheitsmechanismen

Das System beinhaltet mehrere Schutzmassnahmen:

1. Datenbanksperren: Verhindern, dass gleichzeitige automatische Aufladeversuche doppelt belasten
2. Idempotenzschluessel: Stripe-Idempotenzschluessel verhindern doppelte Belastungen selbst bei Netzwerkproblemen
3. Schwellenwertpruefung: Loest nur aus, wenn das Guthaben tatsaechlich unter dem Schwellenwert liegt
4. Testmodus: Konten mit @levyelectric.com-E-Mails verwenden den Stripe-Testmodus

Automatische Aufladetransaktionen anzeigen

Automatische Aufladetransaktionen erscheinen in der Wallet-Aktivitaet des Kunden mit:

• Typ: stripe_topup oder auto_topup
• Beschreibung: "Automatische Aufladung" oder "Automatische Wallet-Aufladung"
• Quelle: Systemgeneriert

Fehlerbehebung bei automatischer Aufladung

Automatische Aufladung funktioniert nicht?

1. Ueberpruefen Sie, ob der Kunde die automatische Aufladung in den App-Einstellungen aktiviert hat
2. Bestaetigen Sie, dass der Subaccount die automatische Aufladung aktiviert hat
3. Pruefen Sie, ob der Kunde eine gueltige Standard-Zahlungsmethode hat
4. Ueberpruefen Sie, ob die Zahlungsmethode nicht abgelehnt wurde
5. Pruefen Sie auf bestehende ausstehende automatische Aufladetransaktionen

Integration mit Zahlungsmethoden

Zahlungshierarchie

Wenn ein Kunde einen Kauf taetigt:

1. Pruefung auf aktive Abonnements mit enthaltenen Fahrten
2. Bonus-Guthaben anwenden (falls verfuegbar)
3. Wallet-Guthaben anwenden (falls verfuegbar)
4. Automatische Aufladung ausloesen (falls aktiviert und Guthaben unter Schwellenwert)
5. Zahlungsmethode belasten (fuer verbleibenden Betrag)

Teilweise Wallet-Nutzung

Wenn eine Fahrt mehr kostet als verfuegbares Guthaben:

• Guthaben wird vollstaendig verbraucht
• Verbleibender Betrag wird von der Karte abgebucht
• Transaktion wird als "Teilweise Wallet-Zahlung" angezeigt

Stripe-Integration

Wallet-Guthaben interagiert mit Stripe-Zahlungen:

• Rueckerstattungen: Koennen statt auf die Karte ins Wallet gehen
• Fehlgeschlagene Belastungen: Kein Wallet-Guthaben verbraucht
• Streitfaelle: Koennen zu Wallet-Belastung fuehren

Wallet-Guthaben in der mobilen App

Kunden sehen ihre Wallet-Informationen in der App:

Guthabenanzeige

• Aktuelles Wallet-Guthaben prominent angezeigt
• Bonus-Guthaben kann separat angezeigt werden
• Kombiniertes "Guthaben" in einigen Ansichten

Guthaben hinzufuegen (falls aktiviert)

• Kunde kann Wallet-Guthaben per Karte hinzufuegen
• Konfigurierbare Mindest-/Hoechstbetraege
• Sofortige Gutschrift bei erfolgreicher Belastung

Transaktionshistorie

• Kunden koennen die aktuelle Wallet-Aktivitaet einsehen
• Beschraenkt auf Gutschriften und Belastungen, die das Guthaben betreffen
• Zeigt Datum, Beschreibung und Betrag

Subaccount-Wallet-Richtlinien

Verschiedene Subaccounts koennen unterschiedliche Wallet-Richtlinien haben:

Wallet-Aufladeeinstellungen

• Aktiviert/Deaktiviert: Kunden-Selbstaufladung erlauben
• Mindestbetrag: Kleinster erlaubter Aufladebetrag
• Hoechstbetrag: Groesster erlaubter Aufladebetrag
• Vorgeschlagene Betraege: Schnellauswahloptionen in der App

Guthabenlimits

• Maximales Guthaben: Verhindern, dass ueberschuessiges Guthaben angesammelt wird
• Warnung bei niedrigem Guthaben: Benachrichtigen, wenn das Guthaben zur Neige geht

Berichte und Analysen

Zusammenfassende Metriken

Der Seitenkopf der Kundenliste zeigt:

• Gesamter Wallet-Wert: Summe aller Wallet-Guthaben
• Gesamte Boni: Summe aller Bonus-Guthaben

Exportoptionen

Wallet-Daten fuer die Analyse exportieren:

1. Zur Kundenliste navigieren
2. Gewuenschte Filter anwenden
3. Auf Export klicken (falls verfuegbar)
4. Felder einschliesslich Wallet- und Bonus-Spalten auswaehlen

Wallet-Aenderungen pruefen

Fuer die Finanzpruefung:

1. Auf die individuelle Kunden-Wallet-Aktivitaet zugreifen
2. Transaktionshistorie mit Zeitstempeln ueberpruefen
3. Mit Fahrthistorie abgleichen
4. Manuelle Gutschriften gegen Betreiberprotokolle pruefen

API-Referenz

Kunden-Wallet-Guthaben abrufen

Endpunkt: GET /api/customers/{id}

Gibt Kundenobjekt zurueck, einschliesslich:

{
  "id": "customer-uuid",
  "wallet_balance": 25.00,
  "bonus": 10.00
}

Wallet-Guthaben hinzufuegen (API)

Endpunkt: POST /api/customers/{id}/wallet

Anfrage:

{
  "amount": 10.00,
  "reason": "Service credit",
  "type": "credit"
}

Bonus-Guthaben hinzufuegen (API)

Endpunkt: POST /api/customers/bonus

Anfrage:

{
  "customerId": "customer-uuid",
  "amount": 5.00,
  "reason": "Promotional bonus"
}

Wallet-Transaktionen abrufen

Endpunkt: GET /api/customers/{id}/wallet/transactions

Abfrageparameter:

• limit: Anzahl der Transaktionen (Standard 50)
• offset: Paginierungs-Offset
• type: Nach Gutschrift/Belastung filtern

Best Practices

Fuer Betreiber

1. Alle manuellen Gutschriften dokumentieren: Immer einen Grund/Notiz hinzufuegen
2. Bonus fuer Aktionen verwenden: Wallet fuer Rueckerstattungen/Entschaedigungen reservieren
3. Regelmaessige Pruefungen: Grosse oder ungewoehnliche Gutschriften regelmaessig ueberpruefen
4. Konsistente Richtlinien: Aehnliche Gutschriften fuer aehnliche Probleme anwenden
5. Zugriff beschraenken: Berechtigungen zum Hinzufuegen von Guthaben angemessen einschraenken

Fuer den Kundendienst

1. Guthaben zuerst pruefen: Vor dem Hinzufuegen von Guthaben das aktuelle Guthaben ueberpruefen
2. Probleme referenzieren: Gutschriften mit Support-Tickets oder Fahrt-IDs verknuepfen
3. Dem Kunden erklaeren: Erklaeren, wie Guthaben angewendet wird
4. Erwartungen setzen: Guthaben wird automatisch auf die naechste Fahrt angewendet

Fuer Finanzteams

1. Regelmaessig abstimmen: Wallet-Gutschriften mit genehmigten Entschaedigungen abgleichen
2. Massenoperationen ueberwachen: Grosse Batch-Gutschriften ueberpruefen
3. Nach Grund verfolgen: Gutschriften fuer Berichte kategorisieren
4. Haftungsbewusstsein: Wallet-Guthaben sind eine Unternehmensverbindlichkeit

Fehlerbehebung

Guthaben erscheint nicht in der Kunden-App

• Ueberpruefen Sie, ob das Guthaben angewendet wurde (Wallet-Aktivitaet pruefen)
• Lassen Sie den Kunden die App aktualisieren oder erzwingen Sie Schliessen/Wiederoeffnen
• Pruefen Sie, ob das Guthaben auf das richtige Kundenkonto ging
• Ueberpruefen Sie, ob der Kunde im richtigen Konto angemeldet ist

Wallet-Guthaben wird falsch angezeigt

• Pruefen Sie aktuelle Transaktionen auf unerwartete Belastungen
• Ueberpruefen Sie, ob keine doppelten Gutschriften angewendet wurden
• Ueberpruefen Sie die Fahrthistorie auf automatische Abzuege
• Pruefen Sie auf systemgenerierte Anpassungen

Fehler bei der Massenverarbeitung

• Ueberpruefen Sie, ob das CSV-Format der erwarteten Struktur entspricht
• Pruefen Sie, ob der Kennungstyp fuer jede Zeile korrekt ist
• Stellen Sie sicher, dass die Kundenkennungen gueltig sind
• Ueberpruefen Sie Fehlermeldungen auf spezifische Fehler

Kunde sagt, Guthaben wurde nicht auf die Fahrt angewendet

• Pruefen Sie die Zahlungsaufschluesselung in den Fahrtdetails
• Ueberpruefen Sie, ob das Guthaben vor Fahrtbeginn auf dem Konto war
• Bestaetigen Sie die Reihenfolge der Anwendung von Bonus vs. Wallet
• Pruefen Sie, ob das Guthaben abgelaufen ist (nur Bonus)