Refunds & Notifications · Article 6.10

Nieudane zwroty i odtworzenie — typowe przyczyny błędów Stripe

Nota kredytowa ze statusem `failed` ma ciąg `refund_failure_reason` od Stripe. Większość przyczyn należy do małego zestawu; oto co każda oznacza i zalecane odtworzenie.

Nieudane zwroty zdarzają się rzadko, ale są stresujące — klient oczekuje pieniędzy, podpisałeś aneks je obiecujący, a API Stripe właśnie odmówiło. Większość błędów pasuje do małego katalogu ze znанymi metodami odtworzenia. Ten artykuł omawia każdą z nich według częstości, z praktycznym krokiem do rozwiązania.

Step by step

Przeczytaj przyczynę błędu w banerze Zwrot.
Jest przechowywana dosłownie ze Stripe; powyższy katalog obejmuje ~90% tego, co zobaczysz.
Dopasuj do odtworzenia.
Przejściowe → Ponów. Sporne → czekaj. Cokolwiek innego → przełącz na ręczne SEPA.
Zrealizuj zwrot poza systemem jeśli potrzeba.
Napisz e-mail do klienta, aby potwierdzić IBAN, przelej środki, kliknij Oznacz jako zwrócony z referencją bankową.
Potwierdź, że nota kredytowa ma status manual (lub succeeded, jeśli Ponów zadziałało).
Oba są końcowe; oba zamykają notę kredytową dla celów księgowych.
Potwierdź zamknięcie oferty jeśli dotyczy.
Gdy nota kredytowa się rozliczy I żadne inne faktury nie mają zaległego amount_due, close_proposal_if_settled zmienia status oferty na Paid. Jeśli oferta jest jedyną z notą kredytową, dzieje się to automatycznie.

Czerwony baner Zwrot nie powiódł się z cytowaną przyczyną błędu plus przyciski Ponów i Oznacz jako zwrócony. Po odtworzeniu baner zmienia się na zielony („Zwrot zrealizowany przez Stripe" lub „Zwrot zrealizowany przez przelew ręczny").

Why this works this way

Stripe ujawnia przyczyny błędów przez pole failure_reason obiektu Refund. Rejestrujemy je w CreditNote.refund_failure_reason (skrócone do 500 znaków), gdy _trigger_stripe_refund zgłasza wyjątek lub gdy webhook raportuje status: "failed". Ciąg przyczyny jest wyświetlany dosłownie w banerze Zwrot, abyś mógł podjąć działanie bez zagłębiania się w logi Stripe.

### Katalog błędów

#### charge_disputed

Co oznacza: oryginalna opłata zaliczkowa ma otwarty spór (bank posiadacza karty zażądał obciążenia zwrotnego). Stripe blokuje zwroty na spornych opłatach, aby zapobiec podwójnej płatności.

Odtworzenie: poczekaj na rozstrzygnięcie sporu (zazwyczaj 30-90 dni). Jeśli wygrasz spór, opłata pozostaje rozliczona i możesz ponowić zwrot. Jeśli przegrasz, posiadacz karty już otrzymał pieniądze przez obciążenie zwrotne — zwrot Stripe nie jest już potrzebny; oznacz notę kredytową jako zwróconą ręcznie z powodem „Obciążenie zwrotne wygrał posiadacz karty — środki zwrócone przez spór", aby ścieżka audytu była czysta.

#### balance_insufficient

Co oznacza: saldo Twojego konta Stripe (lub saldo konta połączonego w przypadku Direct Charges) jest niższe niż kwota zwrotu. Częste, gdy wypłaciłeś większość środków platformy na swoje konto bankowe.

Odtworzenie: doładuj konto połączone zmniejszając oczekujące wypłaty w panelu Stripe LUB zrealizuj zwrot poza systemem przez SEPA (szybciej) i Oznacz jako zwrócony ręcznie. Stripe nie ponowi automatycznie, gdy saldo się odzyska; zwrot jest trwale nieudany do czasu kliknięcia Ponów w Clozo.

#### card_account_closed / expired_or_invalid_card

Co oznacza: karta posiadacza karty jest już nieważna (zamknięte konto, wygasła karta, zastąpiona karta z tym samym numerem ale innym CVV). Stripe będzie kolejkować zwrot i może ostatecznie się powieść, jeśli bank posiadacza ma usługi aktualizacji kart, ale czas jest nieprzewidywalny (od dni do nigdy).

Odtworzenie: nie czekaj. Napisz e-mail do klienta, poproś o numer IBAN do odbioru SEPA, zrealizuj zwrot przez SEPA, Oznacz jako zwrócony ręcznie z powodem „Oryginalna karta zamknięta — zwrócono przez SEPA na IBAN XXXX". To zdecydowanie najczęstszy nietranzytywny błąd i ręczna ścieżka jest najczystszym odtworzeniem.

#### lost_or_stolen_card

Co oznacza: posiadacz karty zgłosił kartę jako zgubioną lub skradzioną po zapłaceniu Ci. Stripe blokuje zwroty, aby uniknąć wysyłania pieniędzy na skompromitowane konto.

Odtworzenie: tak samo jak zamknięta karta — przełącz na SEPA, poproś klienta o docelowy IBAN. Dokumentuj wyraźnie w powodzie noty kredytowej ("Oryginalna karta zgłoszona jako zgubiona/skradziona — zwrócono przez SEPA na zweryfikowany IBAN").

#### Ogólne failed bez konkretnego powodu / awaria API Stripe

Co oznacza: przejściowe lub nieudokumentowane. Może to być tymczasowy problem Stripe, chwilowy błąd sieciowy po naszej stronie lub subtelny problem konfiguracji konta.

Odtworzenie: Ponów raz po 30 sekundach (artykuł 8.8). Jeśli ponowienie zawiedzie tak samo, przełącz na ręczne SEPA + Oznacz jako zwrócony. Zgłoś przez pomoc techniczną, jeśli Cię blokuje — przyjrzymy się logom Stripe, aby zidentyfikować podstawową przyczynę.

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.