> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet aufladen

> Lade das Kundenguthaben manuell oder automatisch auf, um Rechnungen vorab zu bezahlen

Mit der **Wallet-Aufladung** können Kunden ihr Guthaben gezielt auffüllen — entweder manuell über die Web-App oder automatisch per Regel, wenn das Guthaben unter einen bestimmten Schwellenwert fällt.

## Manuelle Aufladung

Eine manuelle Aufladung startet einen Zahlungsvorgang, der den gewünschten Betrag vom Kunden einzieht und als Guthaben verbucht.

<Tabs>
  <Tab title="Web-App">
    <Steps>
      <Step title="Kundendetails öffnen">
        Navigiere zu **Kunden** und wähle den gewünschten Kunden aus.
      </Step>

      <Step title="Debitorenkonto-Tab öffnen">
        Klicke auf den Tab **Debitorenkonto** in der Kundendetailansicht.
      </Step>

      <Step title="Aufladen klicken">
        Klicke auf den Button **Aufladen** in der Wallet-Guthaben-Karte.
      </Step>

      <Step title="Betrag eingeben">
        Gib den gewünschten Aufladebetrag ein. Optional kannst du eine bestimmte Zahlungsmethode auswählen — andernfalls wird die Standard-Zahlungsmethode des Kunden verwendet.
      </Step>

      <Step title="Aufladung bestätigen">
        Klicke auf **Aufladen**. Fynn erstellt einen Zahlungsvorgang (PaymentIntent), der den Betrag einzieht.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://coreapi.io/api/wallet/top-up \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "customerId": "CUSTOMER_ID",
        "amount": 100.00,
        "currencyCode": "EUR"
      }'
    ```

    Siehe [API-Dokumentation](/api-reference/guides/wallet-top-up) für alle Parameter und Optionen.
  </Tab>
</Tabs>

### Status einer Aufladung

Jede Aufladung durchläuft einen Zahlungsstatus:

| Status             | Beschreibung                                           | Badge |
| ------------------ | ------------------------------------------------------ | ----- |
| **Ausstehend**     | Zahlung wurde gestartet, aber noch nicht abgeschlossen | Gelb  |
| **Abgeschlossen**  | Zahlung war erfolgreich, Guthaben wurde gutgeschrieben | Grün  |
| **Fehlgeschlagen** | Zahlung konnte nicht eingezogen werden                 | Rot   |

<Note>
  Nach einer erfolgreichen Aufladung wird das Guthaben sofort verfügbar und kann automatisch auf offene Rechnungen angerechnet werden, sofern die [automatische Anrechnung](/guide/invoices/wallet-balance#automatische-anrechnung-auf-offene-rechnungen) aktiviert ist.
</Note>

### Aufladungshistorie

Im Debitorenkonto-Tab findest du die Karte **Aufladungen** mit einer Übersicht aller bisherigen Aufladungen — inklusive angefordertem Betrag, gutgeschriebenem Betrag und Status.

## Automatische Aufladung

Mit automatischen Aufladungsregeln lässt sich das Guthaben eines Kunden automatisch auffüllen, wenn es unter einen definierten Schwellenwert fällt.

### Regel erstellen

<Steps>
  <Step title="Debitorenkonto öffnen">
    Navigiere zum Tab **Debitorenkonto** des gewünschten Kunden.
  </Step>

  <Step title="Regel hinzufügen">
    Klicke in der Karte **Automatische Aufladung** auf **Regel hinzufügen**.
  </Step>

  <Step title="Parameter konfigurieren">
    Konfiguriere die Regel:

    | Parameter           | Beschreibung                                                                          |
    | ------------------- | ------------------------------------------------------------------------------------- |
    | **Währung**         | Die Währung, für die die Regel gilt (z.B. EUR)                                        |
    | **Schwellenwert**   | Wenn das Guthaben unter diesen Betrag fällt, wird aufgeladen                          |
    | **Aufladebetrag**   | Der Betrag, der automatisch aufgeladen wird                                           |
    | **Zahlungsmethode** | Optional: Spezifische Zahlungsmethode (Standard: Standard-Zahlungsmethode des Kunden) |
  </Step>

  <Step title="Regel speichern">
    Klicke auf **Erstellen**. Die Regel ist sofort aktiv.
  </Step>
</Steps>

<Info>
  Pro Kunde und Währung kann jeweils nur eine automatische Aufladungsregel existieren.
</Info>

### Wie funktioniert die automatische Aufladung?

1. **Trigger**: Bei jeder Guthaben-Abbuchung (z.B. Anrechnung auf eine Rechnung) prüft Fynn, ob das Guthaben unter den Schwellenwert gefallen ist
2. **Aufladung starten**: Falls ja, wird automatisch eine Aufladung über den konfigurierten Betrag gestartet
3. **Zahlung einziehen**: Der Betrag wird über die konfigurierte (oder Standard-) Zahlungsmethode eingezogen
4. **Guthaben gutschreiben**: Nach erfolgreicher Zahlung wird das Guthaben aufgeladen

```
Beispiel:
- Schwellenwert: 10,00 €
- Aufladebetrag: 100,00 €
- Aktuelles Guthaben: 50,00 €
- Neue Rechnung: 45,00 € (Guthaben wird angerechnet)
- Guthaben danach: 5,00 € → unter Schwellenwert!
- Automatische Aufladung: 100,00 € wird eingezogen
- Guthaben nach Aufladung: 105,00 €
```

### Regeln verwalten

In der Karte **Automatische Aufladung** kannst du bestehende Regeln:

* **Aktivieren/Deaktivieren**: Regel vorübergehend ein- oder ausschalten
* **Bearbeiten**: Schwellenwert, Betrag oder Zahlungsmethode ändern
* **Löschen**: Regel dauerhaft entfernen

### Sicherheitsmechanismen

Fynn schützt vor ungewollten Mehrfach-Aufladungen:

* **Aufladung durch Aufladung wird nicht getriggert**: Eine Guthaben-Aufladung (Top-Up) löst keine erneute Schwellenwert-Prüfung aus
* **Fehlerzähler**: Nach aufeinanderfolgenden fehlgeschlagenen Aufladungen wird eine Warnung angezeigt. So erkennst du frühzeitig, wenn eine Zahlungsmethode nicht mehr funktioniert
* **Feature-Flag**: Die Wallet-Aufladung muss für deinen Account aktiviert sein

<Warning>
  Wenn die Zahlungsmethode eines Kunden nicht mehr gültig ist (z.B. abgelaufene Kreditkarte), schlägt die automatische Aufladung fehl. Prüfe regelmäßig Regeln mit Fehlerwarnungen.
</Warning>

## Häufige Fragen

<AccordionGroup>
  <Accordion title="Kann ich das Guthaben auch ohne Aufladung manuell erhöhen?">
    Ja. Neben der Aufladung per Zahlungseinzug kannst du auch manuell Guthaben hinzufügen — z.B. über eine Gutschrift oder manuelle Buchung. Die Aufladung unterscheidet sich dadurch, dass sie automatisch eine Zahlung vom Kunden einzieht.
  </Accordion>

  <Accordion title="Was passiert, wenn die Zahlung fehlschlägt?">
    Die Aufladung wird als **Fehlgeschlagen** markiert. Das Guthaben bleibt unverändert. Bei automatischen Aufladungen wird der Fehlerzähler erhöht, und bei der nächsten Guthaben-Abbuchung wird erneut versucht aufzuladen.
  </Accordion>

  <Accordion title="Kann ich mehrere Regeln für verschiedene Währungen haben?">
    Ja. Du kannst pro Währung eine automatische Aufladungsregel erstellen. So lassen sich z.B. EUR- und USD-Guthaben mit unterschiedlichen Schwellenwerten verwalten.
  </Accordion>

  <Accordion title="Werden automatische Aufladungen sofort verarbeitet?">
    Die Aufladung wird sofort ausgelöst, sobald das Guthaben unter den Schwellenwert fällt. Die tatsächliche Gutschrift erfolgt, sobald die Zahlung erfolgreich eingezogen wurde.
  </Accordion>

  <Accordion title="Kann ich die automatische Aufladung vorübergehend deaktivieren?">
    Ja. Du kannst eine Regel deaktivieren, ohne sie zu löschen. Die Regel bleibt gespeichert und kann jederzeit wieder aktiviert werden.
  </Accordion>
</AccordionGroup>