Refunds & Notifications · Article 6.4
Etapy zwrotu: wystawiony → requested → succeeded (lub ręczny)
Nota kredytowa przechodzi przez do czterech stanów od utworzenia do rozliczenia. Każdy stan odpowiada konkretnemu punktowi w cyklu życia zwrotu, z przewidywalnymi odznakamymi UI i wyzwalaczami e-maili.
Pięcioetapowa maszyna stanów na CreditNote.refund_status to jedyne źródło prawdy dla postępu zwrotu. Zarówno UI freelancera jak i e-maile klienta czytają z niej. Rozumienie znaczenia każdego stanu — i które przejścia są możliwe z których — to najszybsza droga do diagnozowania pytań „dlaczego mój zwrot jest zablokowany?".
Step by step
Obserwuj baner Zwrot oferty.
Odzwierciedla status noty kredytowej z czytelną dla człowieka kopią: -
pending(przepływ Stripe) → „Zwrot w toku — sprawdzanie Stripe" -pending(przepływ SEPA) → „Ręczny zwrot — potwierdź przelew bankowy" -requested→ „Zwrot w toku — spodziewany w 3–5 dniach roboczych. Sprawdź status." -failed→ „Zwrot nieudany: [powód]. Ponów lub oznacz ręcznie." -succeeded→ „Zwrot zakończony [data] przez Stripe." -manual→ „Zwrot zakończony [data] przez przelew ręczny."Użyj właściwej akcji per stan.
pendingprzepływ Stripe: czekaj lub ponów.pendingprzepływ SEPA: wyślij przelew + oznacz jako zwrócono.requested: Odśwież status (artykuł 8.7) jeśli baner pozostaje statyczny przez >5 minut.failed: Ponów (artykuł 8.8) lub oznacz ręcznie (artykuł 8.9).Audytuj przez Oś czasu.
Każde przejście stanu emituje zdarzenie na Osi czasu (
refund_initiated,refund_completeditp.) z metadanymi (kwota, metoda). Przydatne dla inspektorów podatkowych lub jeśli kiedykolwiek musisz zakwestionować transakcję.
Why this works this way
Przejścia stanów:
| Z | Do | Wyzwalacz | Efekty uboczne |
|---|---|---|---|
| (brak) | pending | Nota kredytowa tworzona w _build_credit_note post-sign | Dokumenty (Storno + Berichtigung + Gutschrift) tworzone; klient widzi e-mail „Zwrot zainicjowany" |
pending | requested | _trigger_stripe_refund się powiodło (Refund.create zaakceptowany) | stripe_refund_id i refund_initiated_at wypełnione; baner czyta „Zwrot w toku, spodziewany w 3–5 dniach roboczych" |
pending | failed | _trigger_stripe_refund zgłosiło wyjątek lub obciążenie nie było potwierdzone | refund_failure_reason wypełniony; baner oferuje Ponów + Oznacz ręcznie jako zwrócono |
pending | manual | Freelancer kliknął Oznacz jako zwrócono (przepływ SEPA) | refund_completed_at i manual_refund_reason wypełnione; klient dostaje e-mail „zwrot zakończony"; oferta zamyka się jeśli dotyczy |
requested | succeeded | Webhook refund.updated ze status=succeeded LUB synchronizacja pull zwróciła succeeded | refund_completed_at wypełniony; e-mail „zwrot zakończony"; oferta się zamyka |
requested | failed | Webhook ze status=failed/canceled | refund_failure_reason wypełniony; baner oferuje Ponów + Oznacz ręcznie jako zwrócono |
failed | requested | Freelancer kliknął Ponów zwrot Stripe (artykuł 8.8) | Powód awarii wyczyszczony; z powrotem do Stripe |
failed | manual | Freelancer kliknął Oznacz jako zwrócono (po wystawieniu SEPA poza pasmem) | Tak samo jak pending → manual |
succeeded i manual są terminalne — oba wskazują, że gotówkowa część się rozliczyła, po prostu przez różne kanały. Ścieżka audytu zachowuje który kanał; zachowanie widoczne dla użytkownika jest identyczne (e-mail zamknięcia, oferta Opłacona jeśli dotyczy, PDF noty kredytowej dostępny).
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.