Refunds & Notifications · Article 6.4
Erstattungsstufen: ausgestellt → angefordert → erfolgreich (oder manuell)
Die Gutschrift durchläuft von der Erstellung bis zur Abwicklung bis zu vier Zustände. Jeder Zustand entspricht einem bestimmten Punkt im Erstattungslebenszyklus mit vorhersehbaren UI-Badges und E-Mail-Auslösern.
Die Fünf-Zustands-Maschine auf CreditNote.refund_status ist die einzige Wahrheitsquelle für den Erstattungsfortschritt. Sowohl die Freelancer-UI als auch die Kunden-E-Mails lesen daraus. Das Verständnis der Bedeutung jedes Zustands — und welche Übergänge von welchem Zustand aus möglich sind — ist der schnellste Weg zur Diagnose von „Warum steckt meine Erstattung fest?"-Fragen.
Step by step
Das Erstattungsbanner des Angebots beobachten.
Es spiegelt den Status der Gutschrift mit lesbarem Text wider: -
ausstehend(Stripe-Ablauf) → „Erstattung in Bearbeitung — Stripe wird überprüft" -ausstehend(SEPA-Ablauf) → „Manuelle Erstattung — Banküberweisung bestätigen" -angefordert→ „Erstattung in Bearbeitung — voraussichtlich in 3–5 Werktagen. Status prüfen." -fehlgeschlagen→ „Erstattung fehlgeschlagen: [Grund]. Wiederholen oder manuell markieren." -erfolgreich→ „Erstattung abgeschlossen am [Datum] via Stripe." -manuell→ „Erstattung abgeschlossen am [Datum] via manuelle Überweisung."Die richtige Aktion je nach Zustand verwenden.
ausstehendStripe-Ablauf: Warten oder wiederholen.ausstehendSEPA-Ablauf: Überweisung durchführen + als erstattet markieren.angefordert: Status aktualisieren (Artikel 8.7), wenn das Banner länger als 5 Minuten statisch bleibt.fehlgeschlagen: Wiederholen (Artikel 8.8) oder manuell markieren (Artikel 8.9).Über die Timeline prüfen.
Jeder Zustandsübergang erzeugt ein Timeline-Ereignis (
refund_initiated,refund_completedusw.) mit Metadaten (Betrag, Methode). Nützlich für Steuerprüfer oder wenn Sie jemals eine Transaktion anfechten müssen.
Why this works this way
Zustandsübergänge:
| Von | Zu | Auslöser | Nebeneffekte |
|---|---|---|---|
| (keiner) | ausstehend | Gutschrift erstellt in _build_credit_note nach Unterzeichnung | Dokumente (Storno + Berichtigung + Gutschrift) erstellt; Kunde sieht E-Mail „Erstattung eingeleitet" |
ausstehend | angefordert | _trigger_stripe_refund erfolgreich (Refund.create akzeptiert) | stripe_refund_id und refund_initiated_at befüllt; Banner zeigt „Erstattung in Bearbeitung, voraussichtlich in 3–5 Werktagen" |
ausstehend | fehlgeschlagen | _trigger_stripe_refund hat eine Ausnahme ausgelöst oder die Abbuchung war nicht bestätigt | refund_failure_reason befüllt; Banner bietet „Wiederholen" + „Manuell als erstattet markieren" |
ausstehend | manuell | Freelancer hat auf „Als erstattet markieren" geklickt (SEPA-Ablauf) | refund_completed_at und manual_refund_reason befüllt; Kunde erhält E-Mail „Erstattung abgeschlossen"; Angebot wird ggf. geschlossen |
angefordert | erfolgreich | Webhook refund.updated mit status=succeeded ODER Pull-basierte Synchronisierung hat succeeded zurückgegeben | refund_completed_at befüllt; E-Mail „Erstattung abgeschlossen"; Angebot geschlossen |
angefordert | fehlgeschlagen | Webhook mit status=failed/canceled | refund_failure_reason befüllt; Banner bietet „Wiederholen" + „Manuell als erstattet markieren" |
fehlgeschlagen | angefordert | Freelancer hat auf „Stripe-Erstattung wiederholen" geklickt (Artikel 8.8) | Fehlerursache gelöscht; zurück zu Stripe |
fehlgeschlagen | manuell | Freelancer hat auf „Als erstattet markieren" geklickt (nach außerbankmäßiger SEPA-Überweisung) | Wie ausstehend → manuell |
erfolgreich und manuell sind Endzustände — beide zeigen an, dass der Geldtransfer abgewickelt wurde, nur über verschiedene Kanäle. Der Prüfpfad bewahrt, welcher Kanal verwendet wurde; das für Benutzer sichtbare Verhalten ist identisch (Abschluss-E-Mail, Angebot als bezahlt markiert, falls zutreffend, Gutschrift-PDF zugänglich).
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
Stripe automatic refund (Direct Charges via Connect)
When the original deposit was paid via Stripe, the refund is automatic. Clozo issues a Refund on the freelancer's connected account, watches for the `refund.updated` webhook, and flips the credit note to `succeeded` once Stripe confirms — typically within 3–5 business days for the cash to reach the client.
Refunds & Notifications
SEPA / out-of-band refund: when automation can't help
When the original deposit was paid via SEPA bank transfer (or any non-Stripe channel), Clozo can't refund automatically — Stripe API has nothing to refund. You issue the SEPA transfer manually from your bank, then click `Mark refunded` to update the credit note and notify the client.
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.