LISTENER-CHECKOUT — Mensajes y recuperación para checkout pendiente o en conflicto

[nicoechaniz]

Problema observado

En producción, al seleccionar Continue with Mercado Pago la interfaz mostró:

Membership is not available for purchase right now.

La evidencia operativa indicó un conflicto de checkout pendiente, no indisponibilidad general de Mercado Pago. El mensaje actual colapsa estados distintos —sesión vencida, checkout existente, membresía vigente, idempotencia, proveedor caído o configuración deshabilitada— en un mismo error genérico y no ofrece una acción para continuar.

Esto impide que la persona sepa si puede:

• retomar el checkout ya creado;
• cambiar de PayPal a Mercado Pago o viceversa;
• descartar un intento pendiente;
• volver a autenticarse;
• esperar y reintentar por una falla real del proveedor.

Objetivo

Presentar el estado correcto y acciones server-authoritative sin generar checkouts duplicados, suscripciones huérfanas ni cobros inesperados.

Estados y UX requeridos

Checkout pendiente del mismo proveedor

Mostrar que ya existe un proceso pendiente y ofrecer:

• Continuar con el checkout existente.
• Cancelar por ahora.

Reutilizar la approval URL persistida sólo después de validarla y nunca crear otra operación.

Checkout pendiente de otro proveedor

Mostrar qué medio está pendiente y ofrecer:

• Continuar con el medio existente.
• Cambiar a PayPal/Mercado Pago.
• Cancelar por ahora.

Cambiar de medio debe retirar/cancelar de forma segura el intento anterior tanto en la autoridad como en el proveedor cuando corresponda, antes de habilitar uno nuevo.

Membresía vigente o paid-through

No mostrar compra indisponible. Explicar que la cuenta ya tiene acceso y enlazar a Account para ver o administrar la membresía.

Sesión vencida

Pedir autenticación y volver una sola vez al estado de membresía, sin loop ni perder la intención.

Proveedor realmente indisponible

Sólo en este caso usar un mensaje de indisponibilidad temporal, identificando PayPal o Mercado Pago y permitiendo reintento acotado.

Configuración comercial deshabilitada

No renderizar un botón que el servidor sabe que no puede funcionar.

Contrato backend

• Respuestas tipadas y estables, por ejemplo: pending_checkout_same_provider, pending_checkout_other_provider, membership_already_active, sign_in_required, provider_unavailable, checkout_disabled e idempotency_conflict.
• No exponer payer email, account ID, external subscription ID, approval URL en errores ni detalles del proveedor.
• Una sola autoridad decide si el checkout se puede continuar, retirar o reemplazar.
• Continuar y cambiar son idempotentes ante doble clic, refresh y reconexión.
• Registrar métricas por provider/outcome sin PII y con correlación operativa acotada.

Criterios de aceptación

• El caso observado muestra checkout pendiente y las opciones correspondientes, nunca la falsa indisponibilidad general.
• PayPal pendiente → Mercado Pago y Mercado Pago pendiente → PayPal funcionan sin bindings o preapprovals huérfanos.
• Múltiples clics, Back, refresh, dos pestañas y timeout no crean operaciones duplicadas.
• Una approval URL vencida no se reutiliza; la autoridad ofrece recuperación o reemplazo seguro.
• Membresía activa/cancelled-pending-end/expired presenta acciones coherentes con su estado.
• Errores 401, 409, 422, 503 y timeout tienen copy ES/EN específico y accesible.
• Pruebas unitarias, PostgreSQL, contrato, integración y navegador cubren ambos proveedores y staging/live.
• No se modifica el precio Founder, pagos reales existentes, paid-through, cuotas ni acceso durante la corrección.
• El deploy conserva rollback verificable y smoke de ambos proveedores sin completar un cobro real.

[nicoechaniz]

Evidencia productiva — 2026-08-29

Reproducción humana exacta:

1. Se presionó Continue with PayPal.
2. PayPal abrió su flujo.
3. La persona volvió con Back sin aprobar.
4. Luego Mercado Pago mostró el error genérico.
5. Telegram disparó EarlyBirds FIRING / ListenerPaidJobFailed / listener-paid-queue.

Estado comprobado, sin exponer identificadores:

• PayPal creó el checkout Live a las 03:03:32 UTC.
• Estado remoto actual: APPROVAL_PENDING.
• El plan coincide con el plan Founder configurado.
• No hay pago, activación ni transacción confirmada.
• El job early_birds.paypal.reconcile agotó 5/5 intentos con PayPal returned unexpected HTTP 404.
• El TTL productivo de aprobación es 24 horas y la reconciliación corre cada 900 segundos.

Causa raíz

Para una suscripción todavía APPROVAL_PENDING, show_subscription responde correctamente pero la consulta posterior al endpoint de transacciones devuelve HTTP 404 porque aún no existen transacciones. El adaptador/reconciliador actual clasifica ese 404 como ProviderUnavailableError, agota el job y dispara una alerta de lifecycle, aunque el estado pendiente sea coherente.

El binding pendiente también impide iniciar otro proveedor; esa parte es el comportamiento fail-closed actual, pero la UI lo traduce falsamente como indisponibilidad de Mercado Pago.

Criterios adicionales

• APPROVAL_PENDING más 404 del endpoint de transacciones se trata como cero transacciones pendientes, no como incidente financiero, después de confirmar que show_subscription existe, pertenece al plan esperado y sigue en un estado permitido.
• Back desde PayPal vuelve a una pantalla que permite reanudar, retirar o cambiar de proveedor.
• El reconciliador periódico no genera jobs FAILED ni alertas mientras la aprobación está dentro del TTL.
• Al vencer el TTL, el job específico de expiry cancela/retira con evidencia terminal e idempotencia.
• Una suscripción realmente inexistente, plan incorrecto, estado inesperado o 404 de show_subscription sigue fallando cerrado y alertando.
• Agregar prueba de regresión exacta: create checkout → APPROVAL_PENDING → transactions 404 → Back → switch provider.
• El alerta debe distinguir aprobación abandonada recuperable de lifecycle pago fallido.

[nicoechaniz]

Decisión de producto — abandono del proveedor es comportamiento normal

Abrir PayPal o Mercado Pago y no continuar es un recorrido habitual. No debe quedar representado ante producto u operaciones como una transacción, suscripción, membresía ni fallo de lifecycle.

Distinción obligatoria

• checkout_intent / provider approval object: artefacto técnico efímero necesario para obtener la URL del proveedor;
• approved subscription: autorización explícita del usuario confirmada por el proveedor;
• paid membership: estado canónico respaldado por webhook/reconciliación y evidencia comercial suficiente;
• transaction/payment: movimiento de dinero confirmado.

Un objeto PayPal APPROVAL_PENDING pertenece exclusivamente al primer estado. Nunca debe contarse como subscriber, compra, membresía, ingreso ni error financiero.

Comportamiento requerido

• Back, cierre de pestaña, timeout o abandono silencioso son resultados normales.
• No disparar ListenerPaidJobFailed por ausencia de transacciones en un checkout no aprobado.
• No bloquear otro proveedor indefinidamente.
• Si se inicia otro medio, ofrecer reemplazar el intento anterior y retirar/cancelar de forma idempotente el objeto remoto pendiente cuando el proveedor lo permita.
• Los intentos abandonados expiran automáticamente en una ventana corta y documentada; 24 horas debe reevaluarse desde UX y operación.
• La cancel URL del proveedor retira inmediatamente el intento cuando sea recibida.
• Como Back/cierre no siempre notifican al servidor, el vencimiento server-side es obligatorio y no puede depender del navegador.
• Sólo una aprobación/pago canónico puede ganar; una carrera tardía de un intento reemplazado debe reconciliarse sin doble acceso ni doble membresía.
• Alertar únicamente cuando falla una operación que amenaza consistencia o dinero, no porque un usuario decidió no comprar.

Pruebas de aceptación adicionales

• abrir PayPal → Back;
• abrir PayPal → cerrar pestaña;
• abrir PayPal → cambiar a Mercado Pago;
• abrir Mercado Pago → cambiar a PayPal;
• abandonar y regresar dentro/fuera del TTL;
• aprobación tardía de un intento reemplazado;
• dos pestañas y doble clic;
• proveedor devuelve approval pending sin transacciones.

En todos los casos sin aprobación: cero subscriber, cero payment, cero acceso Founder, cero alerta crítica y posibilidad inmediata de continuar usando Free o elegir otro medio.

[nicoechaniz]

Incidente operativo saneado — 2026-08-29 03:00 ART

La porción operativa que generaba alertas críticas fue corregida y desplegada sin implementar incidentalmente el flujo UX completo de esta card.

• Causa confirmada en producción: recurso PayPal existente en APPROVAL_PENDING y colección de transacciones HTTP 404.
• PR de autoridad: SairaAsua/proyecciones-mito#108, CI verde y suite completa verde.
• Imagen productiva mínima y reproducible: 4f50dd5dce88c216ebeab9e3a66e3e284ce10d2a, derivada exactamente de la imagen anterior 4c8a0c7e2acdbea3a68da9ae6d40a15fe6c3065a más el fix revisado.
• Backup cifrado previo creado y restore-list verificado; imagen anterior conservada para rollback.
• Smoke directo: estado remoto APPROVAL_PENDING, cero eventos y cero mutaciones.
• Ciclo automático real de las 06:00 UTC: suscripción activa COMPLETED; checkout abandonado con transactions 404 COMPLETED; cero retries y cero jobs FAILED nuevos.

La UI para reanudar, retirar o cambiar de proveedor, junto con el TTL de producto, permanece correctamente dentro de #483.

[nicoechaniz]

Incident evidence (2026-08-29): opening PayPal Live and returning without approval left checkout binding I-6GWRDDC4GX19 in APPROVAL_PENDING with zero subscriptions, zero processed provider events and no membership/payment. PayPal transaction-history returned HTTP 404 for that non-paid approval object; the durable reconciler misclassified the 404 as a job failure and Alertmanager repeated ListenerPaidJobFailed every ~16 minutes.

Operational hotfix merged/deployed in SairaAsua/proyecciones-mito#108: history 404 is treated as an empty history only for non-paid lifecycle states (APPROVAL_PENDING, APPROVED, CANCELLED, EXPIRED); every paid lifecycle remains fail-closed. 66 tests passed. Production reconciliations from 06:00 through 07:30 UTC completed, affected checkout now reconciles cleanly, failure gauges are zero and Alertmanager has no active alert.

This fixes alert noise without inventing a purchase or suppressing real payment failures. The user-facing abandoned/pending checkout recovery and message semantics remain the scope of this card and were not implemented by the hotfix.