Refunds & Notifications · Article 6.2

Remboursement automatique Stripe (Direct Charges via Connect)

Lorsque l'acompte original a été payé via Stripe, le remboursement est automatique. Clozo émet un Remboursement sur le compte connecté du freelancer, surveille le webhook `refund.updated` et fait passer la note de crédit à `succeeded` dès que Stripe confirme — généralement 3 à 5 jours ouvrés pour que les fonds atteignent le client.

Stripe Connect Direct Charges signifie que l'argent de l'acompte original a été débité sur le compte connecté du freelancer (acct_xxx), et non sur la plateforme Clozo. Les remboursements doivent donc être émis sur ce même compte — Clozo passe stripe_account=connected_account_id dans l'appel Refund.create pour que Stripe l'achemine correctement. Le remboursement est ensuite suivi par stripe_refund_id sur la ligne de note de crédit, et un écouteur webhook sur le compte connecté fait passer le statut à son état terminal quand Stripe termine le traitement.

Step by step

Le client signe l'avenant Δ_REFUND.
Le pipeline post-signature s'exécute ; _trigger_stripe_refund est appelé.
La note de crédit passe à requested en ~2 secondes.
La bannière du devis indique « Remboursement en cours » avec le numéro de note de crédit et « Prévu dans 3 à 5 jours ouvrés. »
Stripe traite le remboursement.
Les remboursements par carte sont généralement réglés en 3 à 5 jours ouvrés pour le titulaire de la carte ; les remboursements sur compte bancaire (Prélèvement SEPA) peuvent prendre 5 à 7 jours ouvrés. Le tableau de bord du compte connecté sur Stripe affiche le remboursement en temps réel.
Le webhook arrive.
L'événement refund.updated se déclenche quand Stripe finalise. Le statut passe à succeeded ; l'e-mail « remboursement effectué » est envoyé au client ; le devis se ferme à Payé s'il n'y a pas d'autres obligations.
(Si le devis était le seul en cours) le statut revient à Payé.
Sinon, reste dans son état actuel avec le remboursement enregistré.

Une bannière en direct « Remboursement en cours » avec le numéro de note de crédit + la fenêtre estimée. Un bouton Actualiser le statut (article 8.7) est visible si vous souhaitez extraire l'état actuel depuis Stripe plutôt que d'attendre le webhook. Une fois le remboursement réglé (webhook ou extraction), la bannière bascule vers un « Remboursement effectué le [date] » en vert avec un lien vers le PDF de la note de crédit. La ligne Note de crédit dans le menu déroulant Documents affiche le statut succeeded et un lien téléchargeable.

Why this works this way

Pourquoi une synchronisation par extraction comme filet de sécurité ? Les webhooks sont de type best-effort. Stripe relance un webhook défaillant avec un backoff exponentiel sur 3 jours, mais si votre point de terminaison est indisponible pendant toute cette fenêtre, l'événement est supprimé. Pire, la livraison des webhooks est parfois silencieusement retardée de quelques minutes — le freelancer voit une bannière « Remboursement en cours » qui ne se met pas à jour, panique et contacte le support. Le bouton Actualiser le statut (article 8.7) permet au freelancer d'extraire l'état du remboursement directement depuis l'API Stripe à la demande, en appliquant la même logique de transition apply_refund_state_from_stripe. Cela a été ajouté conformément à BUG-PROD-009 [D-115] — les chemins push et pull partagent désormais une seule machine à états, éliminant la classe de bugs où l'interface et la réalité divergeaient.

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.