Refunds & Notifications · Article 6.4
Etapas del reembolso: emitida → solicitada → completada (o manual)
La nota de crédito pasa por hasta cuatro estados desde su creación hasta su liquidación. Cada estado corresponde a un punto específico del ciclo de vida del reembolso, con indicadores de interfaz predecibles y activadores de correo.
La máquina de cinco estados en CreditNote.refund_status es la única fuente de verdad para el progreso del reembolso. Tanto la interfaz del autónomo como los correos del cliente se leen de ella. Comprender el significado de cada estado — y qué transiciones son posibles desde cuál — es el camino más rápido para diagnosticar las preguntas de «¿por qué mi reembolso está bloqueado?».
Step by step
Observe el banner de Reembolso de la propuesta.
Refleja el estado de la nota de crédito con texto legible: -
pending(flujo Stripe) → «Reembolso en curso — verificando Stripe» -pending(flujo SEPA) → «Reembolso manual — confirme la transferencia bancaria» -requested→ «Reembolso en curso — esperado en 3–5 días hábiles. Comprobar estado.» -failed→ «Reembolso fallido: [motivo]. Reintentar o marcar manualmente.» -succeeded→ «Reembolso completado el [fecha] a través de Stripe.» -manual→ «Reembolso completado el [fecha] mediante transferencia manual.»Use la acción correcta según el estado.
pendingflujo Stripe: espere o reintente.pendingflujo SEPA: emita la transferencia + marque como reembolsado.requested: Actualizar estado (artículo 8.7) si el banner permanece estático durante más de 5 minutos.failed: Reintentar (artículo 8.8) o marcar manualmente (artículo 8.9).Audite a través de la Línea de tiempo.
Cada transición de estado emite un evento en la Línea de tiempo (
refund_initiated,refund_completed, etc.) con metadatos (importe, método). Útil para los inspectores fiscales o si alguna vez necesita disputar una transacción.
Why this works this way
Transiciones de estado:
| De | A | Activador | Efectos secundarios |
|---|---|---|---|
| (ninguno) | pending | Nota de crédito creada en _build_credit_note post-firma | Documentos (Storno + Berichtigung + Gutschrift) creados; el cliente recibe el correo «Reembolso iniciado» |
pending | requested | _trigger_stripe_refund tuvo éxito (Refund.create aceptado) | stripe_refund_id y refund_initiated_at completados; el banner muestra «Reembolso en curso, esperado en 3–5 días hábiles» |
pending | failed | _trigger_stripe_refund generó una excepción o el cargo no estaba confirmado | refund_failure_reason completado; el banner ofrece Reintentar + Marcar como reembolsado manualmente |
pending | manual | El autónomo hizo clic en Marcar como reembolsado (flujo SEPA) | refund_completed_at y manual_refund_reason completados; el cliente recibe el correo «reembolso completado»; la propuesta se cierra si corresponde |
requested | succeeded | Webhook refund.updated con status=succeeded O sincronización por sondeo devolvió completado | refund_completed_at completado; correo «reembolso completado»; propuesta cerrada |
requested | failed | Webhook con status=failed/canceled | refund_failure_reason completado; el banner ofrece Reintentar + Marcar como reembolsado manualmente |
failed | requested | El autónomo hizo clic en Reintentar reembolso de Stripe (artículo 8.8) | Motivo de fallo borrado; de vuelta a Stripe |
failed | manual | El autónomo hizo clic en Marcar como reembolsado (después de emitir una transferencia SEPA fuera de la plataforma) | Igual que pending → manual |
succeeded y manual son terminales — ambos indican que el tramo de efectivo se ha liquidado, solo a través de canales diferentes. El registro de auditoría conserva qué canal se usó; el comportamiento visible para el usuario es idéntico (correo de cierre, propuesta Pagada si corresponde, PDF de nota de crédito accesible).
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
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
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
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.