Refunds & Notifications · Article 6.2
Reembolso automático de Stripe (Cargos Directos a través de Connect)
Cuando el anticipo original se pagó a través de Stripe, el reembolso es automático. Clozo emite un reembolso en la cuenta conectada del autónomo, observa el webhook `refund.updated` y cambia la nota de crédito a `succeeded` una vez que Stripe lo confirma — normalmente en 3–5 días hábiles para que el efectivo llegue al cliente.
Los Cargos Directos de Stripe Connect significan que el dinero del anticipo original fue cobrado en la cuenta conectada del autónomo (acct_xxx), no en la plataforma de Clozo. Por tanto, los reembolsos deben emitirse en esa misma cuenta — Clozo pasa stripe_account=connected_account_id en la llamada Refund.create para que Stripe lo enrute correctamente. El reembolso se sigue entonces por stripe_refund_id en la fila de la nota de crédito, y un listener de webhook en la cuenta conectada cambia el estado a su estado terminal cuando Stripe finaliza el procesamiento.
Step by step
El cliente firma la enmienda Δ_REEMBOLSO.
Se ejecuta el pipeline post-firma; se llama a
_trigger_stripe_refund.La nota de crédito pasa a
requesteden ~2 segundos.El banner de la propuesta muestra «Reembolso en progreso» con el número de la nota de crédito y «Se espera en 3–5 días hábiles».
Stripe procesa el reembolso.
Los reembolsos con tarjeta suelen liquidarse en 3–5 días hábiles para el titular; los reembolsos en cuenta bancaria (Débito Directo SEPA) pueden tardar 5–7 días hábiles. El panel de la cuenta conectada en Stripe muestra el reembolso en tiempo real.
Llega el webhook.
El evento
refund.updatedse activa cuando Stripe finaliza. El estado cambia asucceeded; el correo «reembolso completado» se envía al cliente; la propuesta se cierra aPagadasi no hay otras obligaciones.(Si la propuesta era la única pendiente) el estado vuelve a
Pagada.De lo contrario, permanece en su estado actual con el reembolso registrado.
Un banner en vivo «Reembolso en progreso» con el número de la nota de crédito y la ventana esperada. El botón Actualizar estado (artículo 8.7) es visible si desea consultar el estado actual de Stripe en lugar de esperar el webhook. Una vez que el reembolso se liquida (webhook o consulta), el banner cambia a un «Reembolso completado el [fecha]» en verde con un enlace al PDF de la nota de crédito. La fila de la Nota de Crédito en el menú desplegable de Documentos muestra el estado succeeded y un enlace de descarga.
Why this works this way
¿Por qué la sincronización de respaldo basada en consulta? Los webhooks son de mejor esfuerzo. Stripe reintenta un webhook fallido con retroceso exponencial durante 3 días, pero si su endpoint está caído durante toda esa ventana, el evento se pierde. Peor aún, a veces la entrega de webhooks se retrasa silenciosamente durante minutos — el autónomo ve un banner «Reembolso en progreso» que no se actualiza, entra en pánico y contacta con el soporte. El botón Actualizar estado (artículo 8.7) permite al autónomo consultar el estado del reembolso directamente desde la API de Stripe a petición, aplicando la misma lógica de transición de apply_refund_state_from_stripe. Esto se añadió según BUG-PROD-009 [D-115] — tanto el envío como la consulta ahora comparten una única máquina de estados, eliminando la clase de errores en los que la interfaz de usuario y la realidad divergían.
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.