Refunds & Notifications · Article 6.8
Ponów zwrot Stripe — gdy przejściowe błędy znikną
Nieudany zwrot Stripe można zazwyczaj ponowić — większość błędów to przejściowe (limity szybkości, krótkie przestoje Stripe lub webhook deposit-paid docierający po uruchomieniu potoku post-sign). Przycisk Ponów wywołuje `_trigger_stripe_refund` od nowa na nocie kredytowej.
API zwrotów Stripe jest niezawodne, ale ścieżka od „aneks podpisuje się" do „Stripe akceptuje żądanie zwrotu" ma wiele ruchomych części. Trzy częste sposoby, w jakie oryginalne _trigger_stripe_refund może się nie powieść:
1. Wyścig webhooków — webhook payment_intent.succeeded oryginalnego depozytu jeszcze nie dotarł gdy aneks został podpisany; zgodnie z [D-113] wyzwalacz odmawia zwrotu dopóki webhook nie potwierdzi obciążenia. Zanim freelancer to zauważy, webhook dotarł; ponowienie przechodzi sprawdzenie potwierdzenia obciążenia i kontynuuje.
2. Przejściowy problem Stripe — trafiony limit szybkości, krótka przerwa w działaniu, zakłócenie sieci. Ponowienie zazwyczaj to naprawia.
3. Wdrożenia sprzed D-113 — starsza ścieżka kodu, która nie rozpoznawała pewnych konfiguracji obciążeń Stripe. Ponowienie na nowym kodzie poprawnie znajduje PaymentIntent.
Step by step
Zauważ notę kredytową ze stanem
failed.Baner zwrotu czyta „Zwrot nieudany: [powód]." z opcjami Ponów i Oznacz jako zwrócono.
Najpierw przeczytaj powód błędu.
Niektórych powodów nie można naprawić ponowieniem: „charge_disputed" (oryginalne obciążenie ma otwarte spory — zwroty są zablokowane), „balance_insufficient" (Twoje saldo Stripe jest zbyt niskie), „card_account_closed" (konto karty posiadacza jest zamknięte). Ponowienie nie pomoże w tych przypadkach; patrz artykuł 8.10 w celu poznania ścieżek odtworzenia per typ błędu.
Kliknij
Ponów zwrot Stripe.Serwer ponownie uruchamia
_trigger_stripe_refund.Poczekaj ~2 sekundy.
Baner się aktualizuje: sukces → „Zwrot w toku, spodziewany w 3–5 dniach roboczych"; błąd → zaktualizowany powód błędu (często nowy kod błędu jeśli podstawowy problem jest inny).
Jeśli nadal błąd, przejdź do ręcznego.
Kliknij
Oznacz jako zwrócono(artykuł 8.9) po wystawieniu zwrotu poza pasmem.
Why this works this way
Implementacja (CreditNoteRetryStripeRefundView w amendment_views.py:775):
1. Odmów ponowienia jeśli stan to succeeded / manual / requested. Zwraca 409 z details.status, żeby frontend mógł pokazać właściwy błąd. Ponowienie ma sens tylko dla pending lub failed.
2. Wyczyść nieaktualne metadane błędu. refund_failure_reason = "", zapisz. Ponowienie startuje czysto.
3. Ponownie wywołaj `_trigger_stripe_refund(cn, cn.amount_gross)`. Funkcja nigdy nie zgłasza wyjątku (przechwytuje wszystkie wyjątki i zapisuje je w wierszu noty kredytowej), więc endpoint ponowienia zawsze zwraca 200 z wynikającym stanem.
4. Zwróć rozwiązany stan noty kredytowej. Frontend aktualizuje baner/wiersz w miejscu.
Czego ponowienie nie robi: nie zmienia konta Stripe, posiadacza konta ani kwoty. Te dane są pochodną noty kredytowej + oferty + aneksu + konfiguracji Connect — ponowienie po prostu próbuje tej samej akcji ponownie z wyczyszczonym stanem błędu.
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.