Refunds & Notifications · Article 6.2
Automatyczny zwrot Stripe (Direct Charges przez Connect)
Gdy oryginalna zaliczka była opłacona przez Stripe, zwrot jest automatyczny. Clozo wystawia zwrot na połączonym koncie freelancera, obserwuje webhook `refund.updated` i zmienia notę kredytową na `succeeded` po potwierdzeniu przez Stripe — zazwyczaj w ciągu 3–5 dni roboczych środki trafiają do klienta.
Stripe Connect Direct Charges oznaczają, że oryginalne pieniądze zaliczki zostały obciążone na połączonym koncie freelancera (acct_xxx), nie na platformie Clozo. Zwroty muszą zatem być wystawiane na tym samym koncie — Clozo przekazuje stripe_account=connected_account_id przy wywołaniu Refund.create, aby Stripe trasował to poprawnie. Zwrot jest następnie śledzony przez stripe_refund_id w wierszu noty kredytowej, a listener webhooka na połączonym koncie zmienia status na jego stan końcowy, gdy Stripe zakończy przetwarzanie.
Step by step
Klient podpisuje aneks Δ_REFUND.
Pipeline po podpisaniu uruchamia się; wywoływane jest
_trigger_stripe_refund.Nota kredytowa przechodzi do
requestedw ciągu ~2 sekund.Baner oferty pokazuje „Zwrot w toku" z numerem noty kredytowej i „Spodziewany w ciągu 3–5 dni roboczych."
Stripe przetwarza zwrot.
Zwroty kartą zazwyczaj rozliczają się w 3–5 dni roboczych dla posiadacza karty; zwroty na konto bankowe (SEPA Direct Debit) mogą zajmować 5–7 dni roboczych. Panel połączonego konta w Stripe pokazuje zwrot w czasie rzeczywistym.
Webhook dociera.
Zdarzenie
refund.updateduruchamia się gdy Stripe finalizuje. Status zmienia się nasucceeded; e-mail „zwrot zakończony" wychodzi do klienta; oferta zamyka się doOpłaconajeśli nie ma innych zobowiązań.(Jeśli oferta była jedynym oczekującym) status wraca do
Opłacona.W przeciwnym razie pozostaje w bieżącym stanie z zarejestrowanym zwrotem.
Żywy baner „Zwrot w toku" z numerem noty kredytowej + oczekiwanym oknem. Przycisk Odśwież status (artykuł 8.7) jest widoczny jeśli chcesz wyciągnąć bieżący stan ze Stripe zamiast czekać na webhook. Gdy zwrot się rozliczy (webhook lub pull), baner przełącza się na zielony „Zwrot zakończony dnia [data]" z linkiem do PDF noty kredytowej. Wiersz Nota kredytowa na liście Dokumenty pokazuje status succeeded i pobieralny link.
Why this works this way
Dlaczego synchronizacja pull-based jako zabezpieczenie? Webhooks to best-effort. Stripe ponawia nieudany webhook z wykładniczym cofnięciem przez 3 dni, ale jeśli Twój endpoint jest niedostępny przez całe to okno, zdarzenie jest porzucane. Co gorsza, czasami dostarczenie webhooka jest cicho opóźnione o minuty — freelancer widzi baner „Zwrot w toku", który się nie aktualizuje, panikuje i kontaktuje się z pomocą techniczną. Przycisk Odśwież status (artykuł 8.7) pozwala freelancerowi wyciągnąć stan zwrotu bezpośrednio z API Stripe na żądanie, stosując tę samą logikę przejścia apply_refund_state_from_stripe. Zostało to dodane zgodnie z BUG-PROD-009 [D-115] — zarówno push jak i pull teraz dzielą jedną maszynę stanów, eliminując klasę błędów, gdzie UI i rzeczywistość się rozchodziły.
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
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
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.
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
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.