Webhooks y suscripciones de Stripe: lo que hacen mal las apps creadas con IA

Los pagos son el punto donde el código generado por IA parece terminado antes de estarlo. La página de pago se abre, la tarjeta de prueba funciona, aparece una pantalla de «Gracias» y todo parece listo. Pero cobrar el primer pago es la parte fácil de la facturación. El verdadero trabajo es todo lo que ocurre después: renovaciones, tarjetas rechazadas, cancelaciones, mejoras de plan, reembolsos, reintentos y mensajes duplicados.

Esta guía recoge los errores de Stripe que buscaríamos primero en una aplicación creada con IA, por qué cada uno cuesta dinero o confianza y cómo corregirlo. Si quiere una visión más amplia antes del lanzamiento, comience con nuestra lista de verificación de preparación para producción.

El modelo mental: Stripe es la fuente de verdad

El estado de facturación de su cliente reside en Stripe. Su propia base de datos guarda una copia, y los webhooks son la forma en que Stripe avisa a su aplicación de que algo ha cambiado. Un webhook es simplemente una solicitud HTTP que Stripe envía a una URL de su servidor: «este pago se realizó con éxito», «esta suscripción se canceló», «esta factura falló».

La mayoría de los errores de facturación provienen de romper ese modelo: confiar en el navegador en lugar de en Stripe, confiar en los mensajes sin comprobar quién los envió, o asumir que cada mensaje llega exactamente una vez y en orden. Ninguna de estas suposiciones es válida.

Error 1: conceder acceso desde la página de éxito

Un flujo habitual generado por IA redirige a /success tras el pago y desbloquea el producto en esa página. Pero la redirección es solo una navegación del navegador. Un cliente puede cerrar la pestaña antes de que cargue y no obtener nunca el acceso, y cualquiera puede escribir a mano la URL de éxito y obtener acceso sin pagar.

Solución: desbloquee el acceso únicamente cuando su servidor haya recibido y verificado el evento de Stripe correspondiente, y luego lea el acceso del usuario desde su base de datos. La página de éxito puede mostrar un mensaje amable del tipo «estamos confirmando su pago» mientras llega el webhook.

Error 2: no verificar la firma del webhook

La URL de su webhook es simplemente una dirección pública. Si el manejador acepta cualquier solicitud, cualquiera puede enviar un falso evento de «pago realizado» para su propia cuenta. Stripe firma cada evento, y su servidor debe comprobar esa firma con el secreto de firma del endpoint.

La comprobación necesita el cuerpo sin procesar de la solicitud. Si un framework convierte primero el cuerpo a JSON y usted verifica la versión reserializada, la verificación falla, y las herramientas de IA a veces lo «arreglan» desactivando la verificación. Así es como se ve un manejador correcto en una ruta de Next.js:

export async function POST(req) {
  const body = await req.text();            // raw body, not req.json()
  const sig = req.headers.get("stripe-signature");

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return new Response("Invalid signature", { status: 400 });
  }

  // ...handle the event, then acknowledge it quickly
  return new Response("ok", { status: 200 });
}

En Express, utilice el analizador de cuerpo sin procesar para esta ruta concreta. Un error de firma que aparece solo en producción suele indicar que se está usando un secreto de firma equivocado: los endpoints de prueba y de producción tienen cada uno el suyo.

Error 3: asumir una única entrega y en orden

Stripe entrega los eventos al menos una vez, por lo que el mismo evento puede llegar dos veces y los eventos pueden llegar desordenados. Si su manejador suma créditos o crea un pedido cada vez que ve un evento, un reintento lo hará dos veces.

Solución: guarde el ID de cada evento que procese y omita los duplicados. Haga que los manejadores establezcan un estado (por ejemplo, «el estado es activo hasta esta fecha») en lugar de incrementar contadores, de modo que repetirlos sea inofensivo. Cuando el orden importe, consulte el objeto actual en Stripe en lugar de fiarse del orden en que llegan los mensajes.

Error 4: gestionar solo el primer pago

Una suscripción tiene un ciclo de vida, y cada etapa requiere una decisión en su aplicación. Estos son los eventos que la mayoría de los productos deben gestionar:

Su lista exacta depende de su modelo de precios, pero «solo gestionamos el pago» casi nunca es suficiente.

Error 5: tratar la cancelación como instantánea

Cuando un cliente cancela, la mayoría de las empresas le permiten conservar el acceso hasta el final del periodo que ya pagó. Stripe representa esto con una marca en la suscripción que indica que se cancelará al final del periodo. Las aplicaciones que retiran el acceso de inmediato provocan solicitudes de reembolso y quejas, y las que ignoran la marca siguen atendiendo a clientes que ya se han ido.

Muestre al cliente el estado real en su interfaz («Su plan finaliza el 14 de marzo») y considere el portal de clientes alojado de Stripe para los cambios de plan y las cancelaciones, de modo que no tenga que construir esas pantallas.

Error 6: no tener un plan para los pagos fallidos

Las tarjetas caducan, los bancos rechazan operaciones y se alcanzan límites. Una renovación fallida es algo normal, y una suscripción en estado de pago vencido todavía no es un cliente perdido. Defina su política de antemano: cuánto dura el periodo de gracia, qué ve el cliente y qué correos se envían. Stripe puede reintentar los cargos fallidos y enviar correos de recordatorio automáticamente, pero su aplicación aún debe responder con criterio a los cambios de estado.

Error 7: mezclar el modo de prueba y el modo en vivo

El modo de prueba y el modo en vivo son mundos separados, con sus propias claves, productos, precios, clientes y endpoints de webhook. Los errores típicos incluyen un sitio en producción que usa una clave secreta de prueba, un endpoint de webhook en vivo que nunca se creó o un ID de precio copiado del modo equivocado. Mantenga las claves de cada modo en variables de entorno separadas para cada entorno y no deje que unas se mezclen con otras.

Para probar correctamente, use la CLI de Stripe para reenviar eventos a su máquina local y activar eventos de ejemplo, y use los relojes de prueba (test clocks) de Stripe para simular en minutos meses de renovaciones, fallos y cancelaciones.

Error 8: hacer el trabajo pesado dentro del webhook

Stripe espera una respuesta rápida. Si su manejador envía correos, llama a otros servicios y actualiza muchas tablas antes de responder, puede agotar el tiempo de espera y Stripe considerará fallida la entrega. En modo en vivo, Stripe reintenta las entregas fallidas con retrasos crecientes durante hasta tres días, lo que multiplica el procesamiento duplicado si el manejador no es idempotente. Confirme la recepción rápidamente y delegue el trabajo lento a una tarea en segundo plano.

Una breve revisión de facturación que puede hacer hoy

1. ¿Se verifica la firma del webhook usando el cuerpo sin procesar?
2. ¿Se almacenan los ID de los eventos procesados para ignorar los duplicados?
3. ¿El acceso depende del estado de la suscripción en su base de datos y no de la página de éxito?
4. ¿Ha probado en modo de prueba un pago fallido, una cancelación, una mejora de plan y un reembolso?
5. ¿Usan el modo de prueba y el modo en vivo claves, secretos y endpoints distintos?
6. ¿Puede averiguar en un minuto por qué un cliente determinado tiene o no tiene acceso?

Si varias respuestas son «no lo sé», probablemente la facturación sea la parte de su aplicación que debe revisar primero. Nuestra auditoría técnica de aplicaciones de IA incluye en su alcance los flujos de pago y la gestión de webhooks, y la reparación y lanzamiento a producción de aplicaciones de IA abarca completar o corregir el pago con Stripe, las actualizaciones de suscripción, las cancelaciones y los webhooks, con pruebas para cada flujo.