Communities können Beiträge und andere Forderungen per SEPA-Lastschrift einziehen (siehe Lastschrift einrichten und das Handbuch für die Kasse). 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).

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).
  • 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). 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).
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:
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 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:
  3. Spiele sie ein:
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. 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.
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.

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. Ausgegeben werden nur die Adressen (Slugs) der Communities – nie IBAN, Gläubiger-ID oder andere Bankdaten.