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

# Einzugsplan (Wallet)

> Ziehe wiederkehrende Abschläge automatisch auf das Guthabenkonto deiner Kunden ein und überwache Fälligkeiten und Verzug

Mit einem Einzugsplan lädst du das Guthabenkonto (Wallet) eines Kunden regelmäßig automatisch auf, zum Beispiel als monatlichen Abschlag bei einem Stromtarif. Der Plan erzeugt zu jedem Stichtag eine Rate, zieht sie über die hinterlegte Zahlungsmethode ein oder wartet auf eine Überweisung, und eskaliert bei Verzug.

Das Guthaben wächst planmäßig und wird erst mit der Jahres- oder Schlussrechnung verrechnet. Es entsteht keine monatliche Rechnung.

## Einzugsplan anlegen

<Steps>
  <Step title="Kunde öffnen">
    Navigiere zum gewünschten Kunden und öffne den Tab `Einzugsplan`.
  </Step>

  <Step title="Plan konfigurieren">
    Klicke auf `Einzugsplan anlegen` und lege fest:

    * **Betrag** je Rate
    * **Intervall**, zum Beispiel monatlich
    * **Stichtag**: der Tag im Monat, an dem eingezogen wird. Fällt der Tag nicht in den Monat (etwa der 31. im Februar), wird der letzte Tag des Monats verwendet.
    * **Raten**: optional die Anzahl der Raten, zum Beispiel 11 oder 12. Ohne Angabe läuft der Plan unbegrenzt.
    * **Methode**: `Zahlungsmethode belasten` zieht aktiv über die Zahlungsmethode des Kunden ein. `Überweisung erwarten` legt nur die Fälligkeit an und wartet auf den Zahlungseingang.
  </Step>

  <Step title="Speichern">
    Der Plan startet zum nächsten Stichtag. Pro Kunde gibt es einen Einzugsplan; erneutes Speichern ersetzt die Konfiguration.
  </Step>
</Steps>

## Raten und Status

Jede Rate durchläuft einen eigenen Status, den du im Kunden-Tab und in der globalen Übersicht unter `Einzüge` verfolgst:

| Status         | Bedeutung                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Geplant        | Die Rate ist angelegt und wartet auf Einzug oder Zahlungseingang                                    |
| Bezahlt        | Die Rate wurde eingezogen oder durch eine Aufladung gedeckt                                         |
| Fehlgeschlagen | Ein Einzugsversuch ist gescheitert, es folgt automatisch ein neuer Versuch                          |
| Überfällig     | Die erwartete Überweisung ist bis zum Stichtag nicht eingegangen                                    |
| Eskaliert      | Nach drei gescheiterten Versuchen wurde die Rate an den Mahnprozess übergeben und der Plan pausiert |

Bei jedem Fehlschlag und bei Verzug erhält der Kunde automatisch eine E-Mail-Erinnerung. Zusätzlich erscheint bei überfälligen und eskalierten Raten ein Eintrag in Signal, damit dein Team reagieren kann.

## Automatisierung über die API

Alle Funktionen stehen auch über die API bereit, zum Beispiel für die Anbindung eines EVU-Systems. Der Einzugsplan ist eine automatische Aufladung vom Typ `scheduled`; daneben gibt es den Typ `threshold`, der auflädt, sobald das Guthaben unter einen Schwellwert fällt. Beide Typen können je Kunde und Währung parallel existieren.

```bash theme={null}
curl -X POST https://api.fynn.eu/api/wallet/auto-top-up \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customer-id>",
    "currencyCode": "EUR",
    "type": "scheduled",
    "topUpAmount": 50.00,
    "interval": "P1M",
    "chargeDay": 15,
    "installments": 11,
    "method": "bank_transfer"
  }'
```

* `POST /api/wallet/auto-top-up` legt die Regel an. `topUpAmount` ist der Betrag je Rate in Euro, `interval` eine ISO-8601-Dauer in ganzen Monaten (`P1M`, `P3M`, ...), `method` entweder `payment_method` oder `bank_transfer`.
* `GET /api/wallet/auto-top-up?customerId=...` listet die Regeln des Kunden, inklusive Typ, Status und nächstem Stichtag.
* `PUT /api/wallet/auto-top-up/{ruleId}` ändert die Regel. Ein geänderter Stichtag oder ein geändertes Intervall berechnet die nächste Fälligkeit neu.
* `DELETE /api/wallet/auto-top-up/{ruleId}` kündigt den Einzugsplan; die Raten-Historie bleibt erhalten.
* `GET /api/wallet/charges?customerId=...&status=overdue` listet Raten inklusive Fälligkeit, Versuchen und letztem Fehler.
* `GET /api/wallet/top-ups?customerId=...` listet die Aufladungen des Guthabenkontos.

Über Webhooks bleibst du über Verzug informiert: `wallet.charge.failed` wird bei jedem gescheiterten Einzugsversuch ausgelöst, `wallet.charge.overdue` bei ausbleibender Überweisung zum Stichtag und bei der Übergabe an den Mahnprozess.

<Note>
  Der Einzugsplan ist ein eigenes Feature und setzt zusätzlich das Feature Wallet-Aufladung voraus. Wenn du den Einzugsplan nutzen möchtest, wende dich an den Fynn-Support, damit beide Features für deine Organisation aktiviert werden. Sperr- und Mahnprozesse nach § 19 StromGVV verbleiben bei dir als Versorger; Fynn liefert dir dafür die Webhooks und Erinnerungen.
</Note>