Refunds & Notifications · Article 6.10

Remboursements échoués et récupération — causes d'échec Stripe courantes

Une note de crédit avec le statut `failed` possède une chaîne `refund_failure_reason` provenant de Stripe. La plupart des raisons appartiennent à un petit ensemble ; voici ce que chacune signifie et la récupération recommandée.

Les remboursements échoués sont rares mais très stressants — le client attend son argent, vous avez signé un avenant le promettant, et l'API Stripe vient de répondre non. La plupart des échecs entrent dans un petit catalogue avec des récupérations connues. Cet article les passe en revue, par ordre de fréquence, avec l'étape pratique à suivre pour résoudre.

Step by step

Lisez la raison de l'échec dans la bannière Remboursement.
Elle est stockée telle quelle depuis Stripe ; le catalogue ci-dessus couvre ~90% de ce que vous verrez.
Associez-la à la récupération.
Transitoire → Nouvelle tentative. Contesté → attendez. Autre → passez au SEPA manuel.
Émettez le remboursement hors plateforme si nécessaire.
Envoyez un e-mail au client pour confirmer l'IBAN, transférez les fonds, cliquez sur Marquer comme remboursé avec la référence bancaire.
Confirmez que la note de crédit est en statut manual (ou succeeded si la Nouvelle tentative a réussi).
Les deux sont terminaux ; les deux clôturent la note de crédit à des fins comptables.
Confirmez que le devis est clôturé si applicable.
Lorsque la note de crédit est réglée ET qu'aucune autre facture n'a de amount_due en attente, close_proposal_if_settled fait passer le devis à Paid. Si le devis est le seul avec la note de crédit, cela se déclenche automatiquement.

Une bannière rouge Refund failed avec la raison de l'échec citée, plus les boutons Nouvelle tentative et Marquer comme remboursé. Après récupération, la bannière passe au vert (« Remboursement effectué via Stripe » ou « Remboursement effectué via virement manuel »).

Why this works this way

Stripe expose les raisons d'échec via le champ failure_reason de l'objet Refund. Nous le capturons dans CreditNote.refund_failure_reason (tronqué à 500 caractères) lorsque _trigger_stripe_refund lève une exception ou lorsque le webhook signale status: "failed". La chaîne de raison est affichée telle quelle dans la bannière Remboursement afin que vous puissiez agir sans fouiller dans les journaux Stripe.

### Catalogue des échecs

#### charge_disputed

Ce que cela signifie : l'encaissement de l'acompte original fait l'objet d'un litige en cours (la banque du titulaire de la carte a demandé un remboursement). Stripe bloque les remboursements sur les encaissements contestés pour éviter un double paiement.

Récupération : attendez que le litige soit résolu (généralement 30 à 90 jours). Si vous gagnez le litige, l'encaissement reste réglé et vous pouvez réessayer le remboursement. Si vous perdez, le titulaire de la carte a déjà reçu l'argent via la contestation — le remboursement Stripe n'est plus nécessaire ; marquez la note de crédit comme remboursée manuellement avec la raison « Contestation gagnée par le titulaire de la carte — fonds restitués via litige » pour garder une piste d'audit propre.

#### balance_insufficient

Ce que cela signifie : le solde de votre compte Stripe (ou du compte connecté, pour les Direct Charges) est inférieur au montant du remboursement. Cela arrive souvent lorsque vous avez retiré la plupart des fonds de la plateforme vers votre banque.

Récupération : alimentez le compte connecté en réduisant les virements en attente dans le tableau de bord Stripe, OU effectuez le remboursement hors plateforme via SEPA (plus rapide) et marquez-le comme remboursé manuellement. Stripe ne réessaiera pas automatiquement lorsque votre solde sera rétabli ; le remboursement est définitivement échoué jusqu'à ce que vous fassiez une Nouvelle tentative depuis Clozo.

#### card_account_closed / expired_or_invalid_card

Ce que cela signifie : la carte du titulaire n'est plus valide (compte clôturé, carte expirée, carte remplacée avec le même numéro mais un CVV différent). Stripe peut mettre le remboursement en file d'attente et finir par réussir si la banque du titulaire dispose de services de mise à jour de carte, mais le délai est imprévisible (de quelques jours à jamais).

Récupération : n'attendez pas. Envoyez un e-mail au client, demandez un compte bancaire vers lequel un virement SEPA peut être effectué, émettez le remboursement via SEPA, marquez-le comme remboursé manuellement avec la raison « Carte originale clôturée — remboursé via SEPA sur IBAN XXXX. » C'est de loin l'échec non transitoire le plus courant et le parcours manuel est la récupération la plus propre.

#### lost_or_stolen_card

Ce que cela signifie : le titulaire a signalé la carte perdue ou volée après vous avoir payé. Stripe bloque les remboursements pour éviter d'envoyer de l'argent sur un compte compromis.

Récupération : idem que pour la carte clôturée — passez au SEPA, demandez au client un IBAN de destination. Documentez explicitement dans la raison de la note de crédit (« Carte originale signalée perdue/volée — remboursé via SEPA sur IBAN vérifié »).

#### failed générique sans raison spécifique / panne API Stripe

Ce que cela signifie : transitoire ou non documenté. Peut être un problème temporaire chez Stripe, un incident réseau de notre côté, ou un problème subtil de configuration de compte.

Récupération : réessayez une fois après 30 secondes (article 8.8). Si la nouvelle tentative échoue de la même façon, passez au SEPA manuel + Marquer comme remboursé. Signalez-le au support si cela vous bloque — nous analyserons les journaux Stripe pour identifier la cause sous-jacente.

Troubleshooting

Keep reading

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

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.

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

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

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.