Skip to main content
Empezar gratis

Refunds & Notifications · Article 6.10

Reembolsos fallidos y recuperación — razones de fallo habituales en Stripe

Una nota de crédito con estado `fallido` tiene una cadena `refund_failure_reason` de Stripe. La mayoría de las razones pertenecen a un conjunto pequeño; aquí se explica qué significa cada una y la recuperación recomendada.

Los reembolsos fallidos son poco frecuentes pero muy estresantes cuando ocurren — el cliente espera su dinero, usted ha firmado una enmienda prometiéndoselo, y la API de Stripe acaba de decir que no. La mayoría de los fallos encajan en un pequeño catálogo con recuperaciones conocidas. Este artículo recorre cada uno, en orden de frecuencia, con el paso práctico que debe dar para resolverlo.

Step by step

  1. Lea la razón del fallo en el banner de Reembolso.

    Se almacena literalmente desde Stripe; el catálogo anterior cubre ~90% de lo que verá.

  2. Asóciela a la recuperación.

    Transitorio → Reintentar. Disputado → esperar. Cualquier otra cosa → cambiar a SEPA manual.

  3. Emita el reembolso fuera de la plataforma si es necesario.

    Envíe un correo al cliente para confirmar el IBAN, transfiera los fondos, haga clic en Marcar como reembolsado con la referencia bancaria.

  4. Confirme que la nota de crédito está en manual (o succeeded si el reintento funcionó).

    Ambas son terminales; ambas cierran la nota de crédito a efectos contables.

  5. Confirme que la propuesta se cerró si corresponde.

    Cuando la nota de crédito se liquida Y no hay otras facturas con amount_due pendiente, close_proposal_if_settled cambia la propuesta a Pagada. Si la propuesta es la única con la nota de crédito, esto se activa automáticamente.

Un banner rojo «Reembolso fallido» con la razón del fallo citada, más los botones Reintentar y Marcar como reembolsado. Tras la recuperación, el banner cambia a verde («Reembolso completado mediante Stripe» o «Reembolso completado mediante transferencia manual»).

Why this works this way

Stripe expone las razones de fallo a través del campo failure_reason del objeto Refund. Lo capturamos en CreditNote.refund_failure_reason (truncado a 500 caracteres) cuando _trigger_stripe_refund lanza una excepción o cuando el webhook reporta status: "failed". La cadena de razón se muestra literalmente en el banner de Reembolso para que pueda actuar sin necesidad de revisar los registros de Stripe.

### Catálogo de fallos

#### charge_disputed

Qué significa: el cargo de anticipo original tiene una disputa abierta (el banco del titular de la tarjeta solicitó un contracargo). Stripe bloquea los reembolsos en los cargos disputados para evitar el doble pago.

Recuperación: espere a que se resuelva la disputa (normalmente 30-90 días). Si gana la disputa, el cargo queda liquidado y puede reintentar el reembolso. Si la pierde, el titular de la tarjeta ya recibió el dinero a través del contracargo — el reembolso de Stripe ya no es necesario; marque la nota de crédito como reembolsada manualmente con la razón «Contracargo ganado por el titular de la tarjeta — fondos devueltos mediante disputa» para que su registro de auditoría sea limpio.

#### balance_insufficient

Qué significa: el saldo de su cuenta de Stripe (o el saldo de la cuenta conectada, en Cobros directos) está por debajo del importe del reembolso. Es habitual cuando ha retirado la mayor parte de los fondos de la plataforma a su banco.

Recuperación: recargar la cuenta conectada reduciendo los pagos pendientes en el panel de Stripe, O emitir el reembolso fuera de la plataforma mediante SEPA (más rápido) y marcarlo como reembolsado manualmente. Stripe no reintentará automáticamente cuando se recupere su saldo; el reembolso queda permanentemente como fallido hasta que usted lo reintente desde Clozo.

#### card_account_closed / expired_or_invalid_card

Qué significa: la tarjeta del titular ya no es válida (cuenta cerrada, tarjeta caducada, tarjeta reemplazada con el mismo número pero diferente CVV). Stripe pondrá el reembolso en cola y puede que eventualmente tenga éxito si el banco del titular dispone de servicios de actualización de tarjeta, pero el plazo es impredecible (de días a nunca).

Recuperación: no espere. Envíe un correo al cliente, pídales una cuenta bancaria con IBAN para SEPA, emita el reembolso mediante SEPA, marque como reembolsado manualmente con la razón «Tarjeta original cerrada — reembolsado mediante SEPA al IBAN XXXX.» Este es con diferencia el fallo no transitorio más habitual y la vía manual es la recuperación más limpia.

#### lost_or_stolen_card

Qué significa: el titular reportó la tarjeta como perdida o robada después de pagarle. Stripe bloquea los reembolsos para evitar enviar dinero a una cuenta comprometida.

Recuperación: igual que con la tarjeta cerrada — cambie a SEPA, pídales al cliente un IBAN de destino. Documente explícitamente en la razón de la nota de crédito («Tarjeta original reportada como perdida/robada — reembolsado mediante SEPA al IBAN verificado»).

#### failed genérico sin razón específica / interrupción de la API de Stripe

Qué significa: transitorio o sin documentar. Podría ser un problema temporal de Stripe, un fallo de red en nuestro lado, o un problema sutil de configuración de la cuenta.

Recuperación: reintentar una vez después de 30 segundos (artículo 8.8). Si el reintento falla de la misma manera, cambie a SEPA manual + marcar como reembolsado. Contacte con el soporte si le está bloqueando — revisaremos los registros de Stripe para identificar la causa subyacente.

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.