Refunds & Notifications · Article 6.8
Reintentar reembolso de Stripe — cuando los fallos transitorios se resuelven
Un reembolso de Stripe fallido normalmente se puede reintentar — la mayoría de los fallos son transitorios (límites de velocidad, breves interrupciones de Stripe, o el webhook de anticipo pagado que llegó después de que el proceso post-firma se ejecutara). El botón Reintentar llama a `_trigger_stripe_refund` de nuevo en la nota de crédito.
La API de reembolso de Stripe es fiable, pero el camino desde «la enmienda se firma» hasta «Stripe acepta la solicitud de reembolso» tiene múltiples partes móviles. Tres formas comunes en que el _trigger_stripe_refund original puede fallar:
1. Carrera de webhook — el webhook payment_intent.succeeded del anticipo original no había llegado aún cuando se firmó la enmienda; según [D-113], el disparador se niega a reembolsar hasta que el webhook confirme el cargo. Cuando el autónomo lo nota, el webhook ya ha llegado; un reintento pasa la comprobación de cargo confirmado y procede.
2. Transitorio de Stripe — límite de velocidad alcanzado, breve interrupción, fallo de red. El reintento normalmente lo resuelve.
3. Despliegues anteriores a [D-113] — una ruta de código más antigua que no reconocía ciertas configuraciones de cargo de Stripe. El reintento en el nuevo código encuentra correctamente el PaymentIntent.
Step by step
Observe una nota de crédito en
failed.El banner de reembolso muestra «Reembolso fallido: [motivo].» con las opciones Reintentar y Marcar como reembolsado.
Lea primero el motivo del fallo.
Algunos motivos no se pueden corregir con un reintento: «charge_disputed» (el cargo original tiene una disputa abierta — los reembolsos están bloqueados), «balance_insufficient» (su saldo de Stripe es demasiado bajo), «card_account_closed» (la cuenta de la tarjeta del titular está cerrada). Reintentar no ayudará en estos casos; véase el artículo 8.10 para las rutas de recuperación por tipo de fallo.
Haga clic en
Reintentar reembolso de Stripe.El servidor ejecuta
_trigger_stripe_refundde nuevo.Espere ~2 segundos.
El banner se actualiza: éxito → «Reembolso en curso, esperado en 3–5 días hábiles»; fallo → motivo de fallo actualizado (a menudo un nuevo código de error si el problema subyacente es diferente).
Si sigue fallando, cambie al método manual.
Haga clic en
Marcar como reembolsado(artículo 8.9) después de emitir el reembolso fuera de la plataforma.
Why this works this way
Implementación (CreditNoteRetryStripeRefundView en amendment_views.py:775):
1. Rechazar el reintento si el estado es succeeded / manual / requested. Devuelve 409 con details.status para que el frontend pueda mostrar el error correcto. El reintento solo tiene sentido en pending o failed.
2. Borrar los metadatos de fallo obsoletos. refund_failure_reason = "", guardar. El reintento comienza limpio.
3. Volver a llamar a `_trigger_stripe_refund(cn, cn.amount_gross)`. La función nunca genera una excepción (captura todas las excepciones y las registra en la fila de la nota de crédito), por lo que el endpoint de reintento siempre devuelve 200 con el estado resultante.
4. Devolver el estado resuelto de la nota de crédito. El frontend actualiza el banner / fila en su lugar.
Lo que el reintento no hace: cambiar la cuenta de Stripe, el titular de la cuenta o el importe. Estos se derivan de la nota de crédito + propuesta + enmienda + configuración de Connect — el reintento simplemente vuelve a intentar la misma acción con el estado de error borrado.
Troubleshooting
Keep reading
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
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
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.
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.