> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores de pago

> Códigos de error de pago de Fire spark, cuáles se reintentan y cómo mostrarlos.

Cada intent fallido guarda un error con un **código de Fire spark** y, cuando el proveedor mandó uno, el **código del proveedor**. Los códigos son los mismos para todos los proveedores, así tu canal maneja los errores una sola vez.

```json theme={null}
{
  "code": "CARD_DECLINED",
  "reason": "declined",
  "retryable": false,
  "message": "Card declined",
  "provider_code": "05",
  "provider_message": "Rechazada",
  "attempt": 1,
  "elapsed_ms": 8421
}
```

Muestra los dos códigos para que soporte encuentre el intento, por ejemplo `Card declined (Transbank 05)`. `formatPaymentError(error, providerName)` de `@fire-spark/payments` arma ese texto.

## Cómo funcionan los reintentos

* Los errores **reintentables** se reintentan solos con la misma referencia de intento, hasta `runtime.max_attempts`. El proveedor ve un solo pago, no varios.
* Si el proveedor no responde a tiempo, el resultado es **desconocido**. Fire spark le pregunta al proveedor el estado del intento hasta tres veces y después intenta anularlo. Si aun así no puede saberlo, el intent falla con `AMBIGUOUS` y queda marcado para revisión.
* Un terminal que pide cierre de lote recibe uno automáticamente y el cobro se reintenta una vez.
* Los pagos con QR y billetera se revisan hasta que pasa `runtime.qr_ttl_ms`. Después se cancelan con `WALLET_EXPIRED`.

## Códigos

### Rechazados por el proveedor o el banco del cliente

| Código | Significado |
| - | - |
| `CARD_DECLINED` | Tarjeta rechazada |
| `INSUFFICIENT_FUNDS` | Fondos insuficientes |
| `EXPIRED_CARD` | Tarjeta vencida |
| `INVALID_CARD` | Tarjeta inválida |
| `INVALID_PIN` | PIN inválido |
| `LIMIT_EXCEEDED` | Límite excedido |
| `FRAUD_SUSPECTED` | Rechazado por seguridad |
| `WALLET_REJECTED` | Pago con billetera rechazado |
| `WALLET_EXPIRED` | La solicitud de pago venció |
| `INSUFFICIENT_BALANCE` | Saldo insuficiente (vales, billeteras) |
| `TRANSFER_NOT_FOUND` | No se encontró la transferencia |
| `TRANSFER_ALREADY_USED` | La transferencia ya se usó en otro pago |
| `TRANSFER_AMOUNT_MISMATCH` | El monto de la transferencia no coincide |
| `FINANCING_REJECTED` | Financiamiento rechazado |
| `FINANCING_EXPIRED` | La solicitud de financiamiento venció |

Ninguno se reintenta. Pide al cliente otro método.

### Cliente

| Código | Significado |
| - | - |
| `CANCELLED_BY_USER` | El cliente canceló |
| `USER_TIMEOUT` | El cliente no respondió a tiempo una pregunta del terminal |

### Terminal, proveedor y red

| Código | Significado | Se reintenta |
| - | - | - |
| `TERMINAL_UNAVAILABLE` | Terminal no disponible | Sí |
| `TERMINAL_BUSY` | Terminal ocupado | Sí |
| `TERMINAL_NOT_CONFIGURED` | Faltan datos del dispositivo o están mal | No |
| `TERMINAL_NEEDS_INIT` | El terminal necesita inicialización | No |
| `BATCH_CLOSE_REQUIRED` | Se requiere cierre de lote (se maneja solo una vez) | No |
| `INVALID_CREDENTIALS` | Las credenciales del pago están mal | No |
| `INVALID_REQUEST` | El proveedor rechazó la solicitud | No |
| `PROVIDER_UNAVAILABLE` | Proveedor no disponible | Sí |
| `NETWORK_ERROR` | Error de red | Sí |
| `TIMEOUT` | El proveedor tardó demasiado | Sí |
| `AMBIGUOUS` | El resultado sigue desconocido después de consultar; revisa el pago | No |
| `REVERSAL_NOT_ALLOWED` | El proveedor no permite anular ni devolver este pago | No |
| `MANUAL_REVERSAL_REQUIRED` | Reversa el pago a mano en el portal del proveedor | No |
| `UNKNOWN` | Cualquier otro error del proveedor | No |

La página de cada método lista los códigos del proveedor que corresponden a estos códigos.

## Alertas

Las fallas de pago y de terminal pueden disparar [alertas de monitoreo](https://firespark.cloud/docs/es/guides/monitoring-alerts.md). Los intents que terminan en `AMBIGUOUS` o `MANUAL_REVERSAL_REQUIRED` necesitan que alguien revise el portal del proveedor.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.