Refunds & Notifications · Article 6.8
Stripe-Erstattung wiederholen — nach vorübergehenden Fehlern
Eine fehlgeschlagene Stripe-Erstattung kann in der Regel wiederholt werden — die meisten Fehler sind vorübergehend (Ratenlimits, kurze Stripe-Ausfälle oder ein Anzahlungs-Webhook, der nach der Post-Unterzeichnungs-Pipeline eingegangen ist). Die Schaltfläche „Wiederholen" ruft `_trigger_stripe_refund` erneut auf der Gutschrift auf.
Stripes Erstattungs-API ist zuverlässig, aber der Weg von „Änderung unterzeichnet" zu „Stripe akzeptiert die Erstattungsanfrage" hat mehrere bewegliche Teile. Drei häufige Wege, auf denen das ursprüngliche _trigger_stripe_refund scheitern kann:
1. Webhook-Race — der payment_intent.succeeded-Webhook der ursprünglichen Anzahlung war noch nicht eingegangen, als die Änderung unterzeichnet wurde; gemäß [D-113] verweigert der Auslöser die Erstattung, bis der Webhook die Abbuchung bestätigt. Wenn der Freelancer es bemerkt, ist der Webhook eingegangen; ein Neuversuch besteht die Abbuchungsbestätigungsprüfung und läuft durch.
2. Stripe vorübergehend — Ratenlimit erreicht, kurzer Ausfall, Netzwerkproblem. Der Neuversuch löst dies meist.
3. Pre-D-113-Deployments — ein älterer Code-Pfad, der bestimmte Stripe-Abbuchungskonfigurationen nicht erkannte. Der Neuversuch auf dem neuen Code findet den PaymentIntent korrekt.
Step by step
Eine
fehlgeschlageneGutschrift bemerken.Das Erstattungsbanner zeigt „Erstattung fehlgeschlagen: [Grund]." mit den Optionen „Wiederholen" und „Als erstattet markieren".
Zuerst den Fehlergrund lesen.
Einige Gründe können durch einen Neuversuch nicht behoben werden: „charge_disputed" (die ursprüngliche Abbuchung hat einen offenen Streit — Erstattungen sind blockiert), „balance_insufficient" (Ihr Stripe-Guthaben ist zu gering), „card_account_closed" (das Kartenkonto des Karteninhabers ist geschlossen). Der Neuversuch hilft bei diesen nicht; für Lösungswege je Fehlertyp siehe Artikel 8.10.
Auf
Stripe-Erstattung wiederholenklicken.Der Server führt
_trigger_stripe_refunderneut aus.Etwa 2 Sekunden warten.
Banner-Aktualisierung: Erfolg → „Erstattung in Bearbeitung, voraussichtlich in 3–5 Werktagen"; Fehler → aktualisierter Fehlergrund (oft ein neuer Fehlercode, wenn das zugrundeliegende Problem anders ist).
Bei anhaltendem Fehler auf manuell wechseln.
Nach außerbankmäßiger Erstattungsüberweisung auf
Als erstattet markierenklicken (Artikel 8.9).
Why this works this way
Implementierung (CreditNoteRetryStripeRefundView in amendment_views.py:775):
1. Neuversuch ablehnen, wenn der Status `erfolgreich` / `manuell` / `angefordert` ist. Gibt 409 mit details.status zurück, damit das Frontend den richtigen Fehler anzeigen kann. Ein Neuversuch ist nur bei ausstehend oder fehlgeschlagen sinnvoll.
2. Veraltete Fehler-Metadaten löschen. refund_failure_reason = "", speichern. Der Neuversuch beginnt sauber.
3. `_trigger_stripe_refund(cn, cn.amount_gross)` erneut aufrufen. Die Funktion löst keine Ausnahmen aus (sie erfasst alle Ausnahmen und protokolliert sie auf der Gutschriftszeile), sodass der Neuversuchs-Endpunkt immer 200 mit dem resultierenden Status zurückgibt.
4. Den aufgelösten Status der Gutschrift zurückgeben. Das Frontend aktualisiert das Banner / die Zeile an Ort und Stelle.
Was der Neuversuch nicht tut: das Stripe-Konto, den Kontoinhaber oder den Betrag ändern. Diese werden aus Gutschrift + Angebot + Änderung + Connect-Setup abgeleitet — der Neuversuch unternimmt lediglich dieselbe Aktion erneut mit geleerten Fehlerstatus.
Troubleshooting
Keep reading
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
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
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.
Refunds & Notifications
Mark refunded manually — for SEPA and out-of-band proof
When a refund is issued outside Stripe — SEPA bank transfer, cash, PayPal, mailed cheque — `Mark refunded` is how you record it in Clozo. Reason field is mandatory (typically a bank reference). The credit note moves to `manual` status and the client receives a confirmation email.