Refunds & Notifications · Article 6.2
Automatische Stripe-Erstattung (Direct Charges via Connect)
Wenn die ursprüngliche Anzahlung per Stripe geleistet wurde, erfolgt die Erstattung automatisch. Clozo stellt eine Erstattung auf dem verbundenen Konto des Freiberuflers aus, wartet auf den `refund.updated`-Webhook und setzt die Gutschrift auf `succeeded`, sobald Stripe bestätigt – typischerweise erreicht das Geld den Kunden innerhalb von 3–5 Werktagen.
Stripe Connect Direct Charges bedeuten, dass die ursprüngliche Anzahlung auf dem verbundenen Konto des Freiberuflers (acct_xxx) belastet wurde, nicht auf dem Clozo-Plattformkonto. Erstattungen müssen daher auf demselben Konto ausgestellt werden – Clozo übergibt stripe_account=connected_account_id beim Refund.create-Aufruf, damit Stripe sie korrekt weiterleitet. Die Erstattung wird dann über stripe_refund_id auf der Gutschriftzeile verfolgt, und ein Webhook-Listener auf dem verbundenen Konto setzt den Status auf den Endzustand, wenn Stripe die Verarbeitung abschließt.
Step by step
Kunde unterzeichnet den Δ_REFUND-Nachtrag.
Post-Sign-Pipeline läuft;
_trigger_stripe_refundwird aufgerufen.Gutschrift wechselt innerhalb von ca. 2 Sekunden zu
angefordert.Das Angebots-Banner zeigt „Erstattung läuft" mit der Gutschriftnummer und „Voraussichtlich in 3–5 Werktagen."
Stripe verarbeitet die Erstattung.
Kartenerstattungen landen typischerweise in 3–5 Werktagen beim Karteninhaber; Bankkonto-Erstattungen (SEPA-Lastschrift) können 5–7 Werktage dauern. Das verknüpfte Konto-Dashboard bei Stripe zeigt die Erstattung in Echtzeit.
Webhook trifft ein.
Das Ereignis
refund.updatedwird ausgelöst, wenn Stripe abschließt. Status wechselt zusucceeded; E-Mail „Erstattung abgeschlossen" geht an den Kunden; Angebot schließt aufBezahlt, wenn keine weiteren Verpflichtungen bestehen.(Wenn das Angebot das einzige Ausstehende war) Status kehrt zu
Bezahltzurück.Andernfalls verbleibt es in seinem aktuellen Status mit der erfassten Erstattung.
Ein Live-Banner „Erstattung läuft" mit Gutschriftnummer und voraussichtlichem Zeitfenster. Eine Schaltfläche „Status aktualisieren" (Artikel 8.7) ist sichtbar, wenn Sie den aktuellen Status von Stripe abrufen möchten, statt auf den Webhook zu warten. Sobald die Erstattung abgeschlossen ist (Webhook oder Pull), wechselt das Banner zu einem grünen „Erstattung abgeschlossen am [Datum]" mit einem Link zur Gutschrift-PDF. Die Gutschriftzeile im Dokumente-Dropdown zeigt Status succeeded und einen herunterladbaren Link.
Why this works this way
Warum Pull-basierte Synchronisierung als Absicherung? Webhooks sind Best-Effort. Stripe wiederholt einen fehlgeschlagenen Webhook mit exponentiellem Backoff über 3 Tage, aber wenn Ihr Endpunkt das gesamte Fenster nicht erreichbar ist, wird das Ereignis verworfen. Schlimmer noch, manchmal wird die Webhook-Zustellung für Minuten still verzögert – der Freiberufler sieht ein „Erstattung läuft"-Banner, das sich nicht aktualisiert, gerät in Panik und kontaktiert den Support. Die Schaltfläche „Status aktualisieren" (Artikel 8.7) ermöglicht es dem Freiberufler, den Erstattungsstatus bei Bedarf direkt von der Stripe-API abzurufen und dieselbe apply_refund_state_from_stripe-Übergangslogik anzuwenden. Dies wurde gemäß BUG-PROD-009 [D-115] hinzugefügt – Push und Pull teilen jetzt eine einzige Zustandsmaschine, wodurch die Klasse von Bugs beseitigt wurde, bei der UI und Realität auseinanderliefen.
Troubleshooting
Keep reading
Refunds & Notifications
When refunds happen: the Δ_REFUND amendment branches
A refund in Clozo is always tied to a Δ_REFUND amendment branch — partial (revised total smaller than deposit paid) or full (revised total at zero). The amendment is the legal trigger; the refund is the cash consequence.
Refunds & Notifications
Refund stages: issued → requested → succeeded (or manual)
The credit note moves through up to four states from creation to settled. Each state corresponds to a specific point in the refund lifecycle, with predictable UI badges and email triggers.
Refunds & Notifications
Refresh status — pull-based sync when the Stripe webhook didn't land
Webhooks aren't perfect. When a credit note appears stuck in `requested` despite Stripe having processed the refund, click `Refresh status` to pull the current state from Stripe directly. Same transition logic as the webhook; no risk of double-firing side-effects.
Refunds & Notifications
Retry Stripe refund — when transient failures clear
A failed Stripe refund can usually be retried — most failures are transient (rate limits, brief Stripe outages, or deposit-paid webhook arriving after the post-sign pipeline ran). The Retry button calls `_trigger_stripe_refund` afresh on the credit note.
Refunds & Notifications
Failed refunds & recovery — common Stripe failure reasons
A `failed` credit note has a `refund_failure_reason` string from Stripe. Most reasons fall into a small set; here's what each means and the recommended recovery.