---
title: "Lastschrift (Betrieb)"
description: "Was Betreiber für die SEPA-Lastschrift der Communities brauchen: Worker, APP_SECRET, Stripe-Webhook, Bankleitzahlendatei der Bundesbank, app:bank:import-blz, app:debit:sync und app:doctor"
---

Communities können Beiträge und andere Forderungen per **SEPA-Lastschrift** einziehen (siehe [Lastschrift einrichten](/handbuch/owner/zahlungen/lastschrift) und das [Handbuch für die Kasse](/handbuch/kasse/ueberblick)). Für Betreiber gibt es dafür **keine eigenen Umgebungsvariablen**. Das Datei-Verfahren läuft ohne externe Dienste: Die Kasse lädt die SEPA-Datei herunter und reicht sie selbst bei der Bank ein. Die Stripe-Lastschrift zieht über das verbundene Stripe-Konto der Community ein und braucht dieselbe Stripe-Konfiguration wie Pläne, dazu einige zusätzliche Webhook-Ereignisse (siehe [Stripe-Lastschrift](#stripe-lastschrift)).

## Voraussetzungen

- **Worker:** Vorabinformationen und Absagen verschickt der Worker. Ohne laufenden Worker lässt sich keine SEPA-Datei herunterladen, weil QuickTribe die Datei erst freigibt, wenn alle Mitglieder angekündigt sind (siehe [Dienste und Logs](/betrieb#dienste-und-logs)).
- **Scheduler:** Täglich lässt der Worker Mandate ohne Einzug nach 36 Monaten verfallen und löscht abgelaufene Belege und Bankdaten – auch für gelöschte Communities. Die verschlüsselten SEPA-Dateien (mit Kontoinhaber und IBAN) im Upload-Speicher löscht QuickTribe, sobald sie sich nicht mehr herunterladen lassen: beim Bestätigen der Einreichung, beim Verwerfen bzw. Zurücknehmen sofort, sonst der tägliche Job nach der Frist für die Einreichung – spätestens am Einzugstag (Zeitzone der Lastschrift). Die Einzüge selbst bleiben 10 Jahre nach dem Ende des Jahres der letzten Eintragung. Läuft der Worker nicht, bleiben nie eingereichte Dateien entsprechend länger liegen.
- **E-Mail-Versand:** Vorabinformation, Absage, Rücklastschrift, Mahnung und Widerruf sind Pflicht-Mails ohne Abmeldemöglichkeit. Sie gehen in der Sprache des Mitglieds hinaus (Deutsch oder Englisch).
- **`APP_SECRET` nie ändern:** Bankverbindungen (in der Datenbank), die Bankverbindung des Vereins (Gläubiger) und gespeicherte SEPA-Dateien (im Speicher) sind mit einem Schlüssel aus `APP_SECRET` verschlüsselt. Nach einem Wechsel sind sie **nicht mehr lesbar** – Mitglieder und Kasse müssten alle Bankdaten neu eintragen. `app:doctor` erkennt das (siehe unten).

## Stripe-Lastschrift

Die Stripe-Lastschrift nutzt die Stripe-Anbindung der Pläne (`STRIPE_SECRET_KEY`, `STRIPE_EVENT_SECRET`, siehe [Konfiguration](/konfiguration#ereignisse-von-stripe-event-destination)). Zusätzlich nötig:

- **Ereignisse:** In der Event Destination zusätzlich `v1.setup_intent.succeeded`, `v1.setup_intent.setup_failed`, `v1.payment_intent.processing`, `v1.payment_intent.succeeded`, `v1.payment_intent.payment_failed`, `v1.payment_intent.canceled` und `v1.mandate.updated` auswählen (beim klassischen Webhook-Endpunkt dieselben Namen ohne `v1.`). `checkout.session.completed`, `charge.dispute.created`, `charge.dispute.closed` und `charge.refunded` stehen schon in der Liste der Pläne. QuickTribe ordnet jedes Ereignis über die gespeicherten Kennungen zu (Zahlung, Mandat, Einrichtung) – Ereignisse der Lastschrift berühren nie Pläne oder Kurse und umgekehrt.
- **Scheduler im Worker:** Stündlich legt der Worker fällige Einzüge an und reicht Einzüge am Einzugstag bei Stripe ein; täglich gleicht er eingereichte Einzüge ab, für die zehn Bankarbeitstage nach dem Einzugstag noch keine Meldung von Stripe da ist. Ohne Worker entstehen keine Einzüge.
- **SEPA-Lastschrift im Stripe-Konto:** Das schaltet der Owner der Community in seinem Stripe-Dashboard unter den Zahlungsmethoden frei, ebenso seine eigene Gläubiger-ID. Fehlt sie dort, bietet Stripe keine Lastschrift an und QuickTribe lehnt die Einrichtung eines Mandats mit einem Hinweis ab (siehe [Lastschrift einrichten](/handbuch/owner/zahlungen/lastschrift#stripe-lastschrift)).

Je Einzug legt QuickTribe genau eine Zahlung bei Stripe an: mit einem festen Idempotenzschlüssel, und vor jedem erneuten Versuch sucht es zuerst nach einer schon angelegten Zahlung. Ist Stripe kurz nicht erreichbar, bleibt der Einzug stehen und der nächste stündliche Lauf macht weiter.

Verpasste Ereignisse holt der Befehl `app:debit:sync` für eine Community nach – etwa nach einem Ausfall von Webhook oder Worker:

```bash
docker compose exec app php bin/console app:debit:sync <slug> --limit=100
```

Er reicht fällige Einzüge ein, gleicht alle bei Stripe eingereichten Einzüge ab, übernimmt Mandate aus abgeschlossenen Einrichtungen, deren Rückkehr und Webhook fehlten, und beendet Mandate, die Stripe als inaktiv führt. `--limit` (Standard 100, höchstens 500) begrenzt die Zahl der Abfragen je Bereich. Für Communities ohne Stripe-Lastschrift bricht er ab.

## Bankleitzahlendatei der Bundesbank

Für deutsche Konten ergänzt QuickTribe Bankname und BIC aus der **Bankleitzahlendatei der Deutschen Bundesbank** (Quelle: Deutsche Bundesbank). Die Datei liegt jedem Release bei (`resources/bank/blz.txt.gz`, unverändert gepackt, mit `QUELLE.txt` samt Gültigkeit und Prüfsumme); zur Laufzeit gibt es keinen Netzabruf.

Die Bundesbank veröffentlicht die Datei **vierteljährlich** (gültig jeweils ab Anfang März, Juni, September und Dezember). Mit jedem QuickTribe-Update kommt in der Regel die aktuelle Datei mit. Läuft sie ab, bevor du aktualisierst, meldet `app:doctor` eine Warnung. Neue oder geänderte Bankleitzahlen fehlen dann: Bei solchen Konten bleiben Bankname und BIC leer (für deutsche Konten ist die BIC keine Pflicht, die SEPA-Datei kommt ohne sie aus), und im Bestandsimport braucht eine Zeile mit unbekannter Bankleitzahl die BIC. Bestehende Daten und Einzüge funktionieren weiter.

### Neue Datei einspielen

1. Lade auf der [Download-Seite der Bundesbank](https://www.bundesbank.de/de/aufgaben/unbarer-zahlungsverkehr/serviceangebot/bankleitzahlen/download-bankleitzahlen-602592) die **Bankleitzahlendatei im TXT-Format** herunter (ungepackt oder als ZIP) und notiere die dort genannte Gültigkeit („gültig vom … bis …“).
2. Kopiere die Datei in den Container, zum Beispiel:

   ```bash
   docker compose cp blz-aktuell-txt-data.txt app:/tmp/blz.txt
   ```

3. Spiele sie ein:

   ```bash
   docker compose exec app php bin/console app:bank:import-blz /tmp/blz.txt --valid-from=07.12.2026 --valid-until=07.03.2027
   ```

Der Befehl prüft jede Zeile (feste Satzlänge 168 Zeichen, Bankleitzahl, Merkmal, BIC, Änderungskennzeichen usw.) und bricht bei einer falschen Datei mit den ersten fehlerhaften Zeilen ab, ohne etwas zu schreiben. Ist alles in Ordnung, legt er die Datei unverändert gepackt im Speicherverzeichnis ab (`<STORAGE_LOCAL_ROOT>/bank/blz.txt.gz` mit `QUELLE.txt`; in den Docker-Varianten im Volume `uploads`) und zeigt Zahl der Kreditinstitute, Gültigkeit und SHA-256-Prüfsumme. Die Datei übersteht Updates.

| Option | Bedeutung |
| --- | --- |
| `--valid-from`, `--valid-until` | Gültigkeit laut Bundesbank, `TT.MM.JJJJ` oder `JJJJ-MM-TT` – Pflicht. Abgelehnt werden eine schon abgelaufene Datei, eine Gültigkeit von mehr als 100 Tagen (eine Datei gilt ein Quartal – so fällt ein Tippfehler wie 2036 statt 2026 auf) und ein Beginn mehr als 100 Tage in der Zukunft. Beginnt die Gültigkeit erst später, nutzt QuickTribe die Datei trotzdem sofort und weist darauf hin. |
| `--dry-run` | nur prüfen und Prüfsumme ausgeben, nichts schreiben |
| `--target=<verzeichnis>` | anderes Zielverzeichnis. `--target=resources/bank` ersetzt die mitgelieferte Datei – nur für die Pflege des Quellcodes, in Installationen nicht nötig. |

Es gilt immer die Datei, die **länger gültig** ist: die eingespielte, solange sie neuer ist als die mitgelieferte. Bringt ein späteres Update eine neuere Datei mit, gilt automatisch diese; die alte Einspielung stört nicht. Die Anwendung liest die neue Datei sofort, der Worker nach seinem nächsten Auftrag.

<Note>
Bei der Installation ohne Docker rufst du den Befehl als `www-data` auf (`runuser -u www-data -- php bin/console app:bank:import-blz …`). Läuft er als `root`, übergibt er die Dateien dem Eigentümer des Speicherverzeichnisses.
</Note>

## Systemprüfung

`php bin/console app:doctor` prüft für die Lastschrift zwei Punkte. Ein „!“ ist ein Hinweis, der den Exit-Code nicht ändert; ein „✘“ ist ein Fehler.

| Abschnitt | ✔ | ! Hinweis | ✘ Fehler |
| --- | --- | --- | --- |
| **Bankleitzahlen** | Datei vorhanden und lesbar: Herkunft (mitgeliefert oder eingespielt), Zahl der Kreditinstitute, gültig bis | abgelaufen (mit Datum) oder Gültigkeit unbekannt – neue Datei einspielen oder aktualisieren | Datei fehlt, ist nicht lesbar oder leer |
| **Lastschrift** | je Community mit eingeschalteter Lastschrift: SEPA-Datei bzw. Stripe-Lastschrift nutzbar | Gläubiger unvollständig oder Gläubiger-ID ungültig, Stripe-Lastschrift gewählt, aber das Stripe-Konto kann nicht belasten – das klärt der Owner der Community | Bankverbindung des Gläubigers oder der Mitglieder nicht entschlüsselbar (meist geänderter `APP_SECRET`) |

Ausgegeben werden nur die Adressen (Slugs) der Communities – nie IBAN, Gläubiger-ID oder andere Bankdaten.
