Skip to main content
Kostenlos starten

Refunds & Notifications · Article 6.10

Fehlgeschlagene Erstattungen & Wiederherstellung – häufige Stripe-Fehlergründe

Eine fehlgeschlagene Gutschrift hat eine `refund_failure_reason`-Zeichenkette von Stripe. Die meisten Gründe fallen in eine kleine Gruppe; hier steht, was jeder bedeutet und welche Wiederherstellung empfohlen wird.

Fehlgeschlagene Erstattungen sind selten, aber hochgradig belastend, wenn sie eintreten – der Kunde erwartet sein Geld, Sie haben in einem Nachtrag zugesagt, es zu erstatten, und die Stripe-API hat gerade nein gesagt. Die meisten Fehler passen in einen kleinen Katalog mit bekannten Lösungen. Dieser Artikel geht jeden durch, in der Reihenfolge der Häufigkeit, mit dem praktischen Schritt zur Lösung.

Step by step

  1. Fehlergrund im Erstattungs-Banner lesen.

    Er wird wörtlich von Stripe gespeichert; der obige Katalog deckt ca. 90 % der Fälle ab.

  2. Zur Wiederherstellung zuordnen.

    Vorübergehend → Erneut versuchen. Strittig → Warten. Alles andere → auf manuelles SEPA umsteigen.

  3. Erstattung bei Bedarf außerbörslich ausstellen.

    Kunden per E-Mail kontaktieren, IBAN bestätigen, Mittel transferieren, auf Markierung als erstattet mit Bankreferenz klicken.

  4. Bestätigen, dass die Gutschrift im Status manuell ist (oder erfolgreich, wenn erneuter Versuch funktioniert hat).

    Beide sind Endzustände; beide schließen die Gutschrift für Buchführungszwecke.

  5. Bestätigen, dass das Angebot ggf. geschlossen wurde.

    Wenn die Gutschrift sich klärt UND keine anderen Rechnungen ausstehende amount_due haben, wechselt close_proposal_if_settled das Angebot auf Paid. Falls das Angebot das einzige mit der Gutschrift ist, wird dies automatisch ausgelöst.

Ein rotes Banner Erstattung fehlgeschlagen mit dem zitierten Fehlergrund plus Schaltflächen für „Erneut versuchen" und „Als erstattet markieren". Nach der Wiederherstellung wechselt das Banner zu grün ("Erstattung über Stripe abgeschlossen" oder "Erstattung über manuelle Überweisung abgeschlossen").

Why this works this way

Stripe gibt Fehlergründe über das failure_reason-Feld des Refund-Objekts aus. Wir erfassen es in CreditNote.refund_failure_reason (auf 500 Zeichen gekürzt), wenn _trigger_stripe_refund eine Ausnahme auslöst oder wenn der Webhook status: "failed" meldet. Die Zeichenkette des Grundes wird wörtlich im Erstattungs-Banner angezeigt, damit Sie handeln können, ohne in Stripe-Protokolle zu schauen.

### Fehlerkatalog

#### charge_disputed

Bedeutung: Die ursprüngliche Anzahlungsbelastung hat eine offene Streitigkeit (die Bank des Karteninhabers hat eine Rückbuchung angefordert). Stripe blockiert Erstattungen für strittige Belastungen, um Doppelzahlungen zu verhindern.

Wiederherstellung: Warten Sie, bis die Streitigkeit geklärt ist (typischerweise 30–90 Tage). Wenn Sie die Streitigkeit gewinnen, bleibt die Belastung beglichen und Sie können die Erstattung erneut versuchen. Wenn Sie verlieren, hat der Karteninhaber das Geld bereits über die Rückbuchung erhalten – die Stripe-Erstattung wird nicht mehr benötigt; markieren Sie die Gutschrift manuell als erstattet mit dem Grund „Rückbuchung vom Karteninhaber gewonnen – Mittel über Streitigkeit zurückgegeben", damit Ihr Prüfpfad sauber ist.

#### balance_insufficient

Bedeutung: Ihr Stripe-Kontostand (oder der Saldo des verbundenen Kontos bei Direktbelastungen) liegt unter dem Erstattungsbetrag. Häufig, wenn Sie die meisten Plattformmittel auf Ihr Bankkonto ausgezahlt haben.

Wiederherstellung: Aufstocken des verbundenen Kontos durch Reduzierung ausstehender Auszahlungen im Stripe-Dashboard ODER Ausstellung der Erstattung außerbörslich per SEPA (schneller) und manuelle Markierung als erstattet. Stripe wiederholt nicht automatisch, wenn sich Ihr Saldo erholt; die Erstattung ist dauerhaft fehlgeschlagen, bis Sie über Clozo erneut versuchen.

#### card_account_closed / expired_or_invalid_card

Bedeutung: Die Karte des Karteninhabers ist nicht mehr gültig (geschlossenes Konto, abgelaufene Karte, ersetzte Karte mit gleicher Nummer, aber anderem CVV). Stripe stellt die Erstattung in die Warteschlange und kann eventuell erfolgreich sein, wenn die Bank des Karteninhabers Karten-Update-Dienste hat, aber das Timing ist unvorhersehbar (Tage bis nie).

Wiederherstellung: Nicht warten. Kunden per E-Mail kontaktieren, nach einem SEPA-fähigen Bankkonto fragen, Erstattung per SEPA ausstellen, manuell als erstattet markieren mit dem Grund „Originalkarte geschlossen – per SEPA auf IBAN XXXX erstattet." Dies ist bei weitem der häufigste nicht-transiente Fehler, und der manuelle Weg ist die sauberste Lösung.

#### lost_or_stolen_card

Bedeutung: Karteninhaber hat die Karte als verloren oder gestohlen gemeldet, nachdem er Sie bezahlt hatte. Stripe blockiert Erstattungen, um zu verhindern, dass Geld an ein kompromittiertes Konto gesendet wird.

Wiederherstellung: Gleich wie bei geschlossener Karte – auf SEPA umsteigen, Kunden nach Ziel-IBAN fragen. Explizit im Gutschriftgrund dokumentieren ("Originalkarte als verloren/gestohlen gemeldet – per SEPA auf verifizierte IBAN erstattet").

#### Generischer failed-Fehler ohne spezifischen Grund / Stripe-API-Ausfall

Bedeutung: Vorübergehend oder nicht dokumentiert. Könnte ein temporäres Stripe-Problem, ein Netzwerkfehler auf unserer Seite oder ein subtiles Kontokonfigurationsproblem sein.

Wiederherstellung: Einmal nach 30 Sekunden erneut versuchen (Artikel 8.8). Wenn der erneute Versuch genauso fehlschlägt, auf manuelles SEPA + Markierung als erstattet umsteigen. Über Support melden, wenn es blockiert – wir analysieren die Stripe-Protokolle, um die zugrunde liegende Ursache zu identifizieren.

Troubleshooting

Keep reading

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

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.

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

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

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.