Refunds & Notifications Β· Article 6.2
Automatische Stripe-terugbetaling (Direct Charges via Connect)
Wanneer de oorspronkelijke aanbetaling via Stripe is betaald, verloopt de terugbetaling automatisch. Clozo geeft een terugbetaling uit op de verbonden rekening van de freelancer, wacht op de webhook `refund.updated` en zet de creditnota naar `geslaagd` zodra Stripe bevestigt β het duurt doorgaans 3β5 werkdagen voordat het geld de klant bereikt.
Stripe Connect Direct Charges betekent dat het oorspronkelijke aanbetalingsgeld is gefactureerd op de verbonden rekening van de freelancer (acct_xxx), niet op het Clozo-platform. Terugbetalingen moeten daarom worden uitgegeven op diezelfde rekening β Clozo geeft stripe_account=connected_account_id door bij de Refund.create-aanroep zodat Stripe het correct routeert. De terugbetaling wordt dan bijgehouden via stripe_refund_id op de creditnotarij, en een webhookluisteraar op de verbonden rekening zet de status naar de eindstaat wanneer Stripe de verwerking afrondt.
Step by step
Klant ondertekent het Ξ_REFUND-addendum.
Post-ondertekeningspipeline wordt uitgevoerd;
_trigger_stripe_refundwordt aangeroepen.Creditnota gaat binnen ~2 seconden naar
aangevraagd.De offertebanner toont "Terugbetaling in behandeling" met het creditnotanummer en "Verwacht binnen 3β5 werkdagen."
Stripe verwerkt de terugbetaling.
Kaartterugbetalingen verrekenen doorgaans in 3β5 werkdagen voor de kaarthouder; bankrekening-terugbetalingen (SEPA Incasso) kunnen 5β7 werkdagen duren. Het verbonden-rekening-dashboard op Stripe toont de terugbetaling in realtime.
Webhook arriveert.
Gebeurtenis
refund.updatedwordt geactiveerd wanneer Stripe afrondt. Status wisselt naargeslaagd; e-mail "terugbetaling voltooid" gaat uit naar klant; offerte sluit naarBetaaldals er geen andere verplichtingen zijn.(Als de offerte de enige uitstaande was) status keert terug naar
Betaald.Anders blijft de offerte in de huidige staat met de terugbetaling geregistreerd.
Een live banner "Terugbetaling in behandeling" met creditnotanummer + verwacht venster. Een knop Status vernieuwen (artikel 8.7) is zichtbaar als u de huidige staat van Stripe wilt opvragen in plaats van op de webhook te wachten. Zodra de terugbetaling is verrekend (via webhook of pull), wisselt de banner naar een groene "Terugbetaling voltooid op [datum]" met een koppeling naar de creditnota-PDF. De creditnotarij in het dropdown-menu Documenten toont status geslaagd en een downloadkoppeling.
Why this works this way
Waarom pull-gebaseerde synchronisatie als vangnet? Webhooks zijn best-effort. Stripe herprobeert een mislukte webhook met exponentiΓ«le vertraging gedurende 3 dagen, maar als uw eindpunt gedurende dat hele venster offline is, wordt de gebeurtenis weggegooid. Erger nog, soms is de bezorging van webhooks stil vertraagd met minuten β de freelancer ziet een banner "Terugbetaling in behandeling" die niet bijwerkt, raakt in paniek en neemt contact op met ondersteuning. De knop Status vernieuwen (artikel 8.7) laat de freelancer de terugbetalingsstatus rechtstreeks van de Stripe API opvragen op aanvraag, waarbij dezelfde apply_refund_state_from_stripe-overganglogica wordt toegepast. Dit is toegevoegd per BUG-PROD-009 [D-115] β zowel push als pull delen nu een enkele toestandsmachine, waarmee de klasse van bugs waarbij de UI en de werkelijkheid uiteen liepen, is geΓ«limineerd.
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.