Pasar Stripe de modo prueba a producción: checklist

Pasar Stripe del modo de prueba a producción significa volver a crear casi todo en un segundo entorno, separado del primero: claves de API live, productos y precios live, un endpoint de webhook live con su propio secreto de firma y la configuración live del portal de clientes y de los correos. Nada de lo que hiciste en un sandbox se copia solo. Los fallos del día del lanzamiento casi siempre vienen de un valor de prueba que quedó olvidado: un secreto de webhook viejo, un ID de precio de prueba o un ID de cliente de prueba guardado en tu base de datos.

Esta lista recorre cada punto en el orden que evita sorpresas y termina con cómo confirmar el cambio con un pago real.

¿Qué cambia de verdad entre un sandbox y el modo live?

Stripe diseñó los dos entornos para que se comporten lo más parecido posible; en sus palabras, cambiar es "sobre todo cuestión de cambiar las claves de API". El problema está en ese "sobre todo". Los objetos creados en un sandbox (productos, precios, cupones, clientes) no se pueden usar en live. Los endpoints de webhook, las configuraciones del portal y las claves también son independientes. Hoy Stripe llama sandbox a los entornos de prueba; las guías viejas y algunos menús todavía dicen "test mode", y es la misma idea.

Paso 1: ¿Tu cuenta de Stripe está lista para cobrar dinero real?

Antes de tocar código, entra al Dashboard en modo live y completa lo que Stripe te pida: datos del negocio, cuenta bancaria para los pagos y verificación de identidad. Después revisa dos cosas que verán tus clientes:

• Nombre público del negocio y datos de soporte, que aparecen en Checkout, en los recibos y en el portal de clientes.
• Descriptor del estado de cuenta, el texto que sale en el resumen de la tarjeta. Que sea algo reconocible: un nombre extraño es una causa frecuente de disputas por cobros que la persona sí hizo.

Paso 2: ¿Cómo manejas las claves live?

Las claves live empiezan con pk_live_, sk_live_ y, en las restringidas, rk_live_. Algunas reglas:

1. En el servidor, usa una clave restringida siempre que puedas. Stripe las recomienda para la mayoría de los casos porque tú eliges sus permisos.
2. Copia la clave al crearla. En modo live, Stripe muestra una sola vez las claves secretas que creas tú. Si la pierdes, rótala y crea otra.
3. En el navegador solo va la clave publicable. La secreta o la restringida vive en las variables de tu servidor (secrets de Supabase, variables de entorno de Vercel o el panel de tu hosting), nunca en el código del frontend.
4. Vuelve a desplegar después de cambiar variables. Muchos hostings solo leen las variables al compilar o desplegar.

Si en algún momento una clave secreta terminó en tu repositorio durante el desarrollo, rótala antes del lanzamiento, no después.

Paso 3: ¿Cómo vuelves a crear productos y precios?

Los IDs de precio del sandbox no existen en live, y los precios live tienen IDs nuevos. Dos formas de evitar desajustes escritos a mano en el código:

• En la página de cada producto dentro del sandbox, el botón Copy to live mode crea el producto y sus precios en live.
• Ponle a cada precio un lookup_key, por ejemplo pro_mensual, y busca los precios por esa clave en tu código. Así el mismo código funciona en los dos entornos y puedes cambiar un precio sin desplegar.

Revisa que montos, moneda, intervalo de cobro y días de prueba coincidan con lo que promete tu página de precios.

Paso 4: ¿Creaste un endpoint de webhook live?

Es el punto que más se olvida. Un endpoint live es un objeto distinto, con un secreto de firma distinto.

1. En modo live, abre Workbench, ve a Webhooks y agrega la URL de producción. Los endpoints live deben usar HTTPS.
2. Selecciona los mismos eventos que atiendes en el sandbox, por ejemplo checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.paid e invoice.payment_failed.
3. Revela el nuevo secreto whsec_ y ponlo en la variable de entorno de producción.
4. Despliega de nuevo.

Si te saltas el paso 3, todos los eventos live fallan con error de firma mientras los del sandbox siguen funcionando, y el problema parece aleatorio. Lo explicamos en error de firma del webhook de Stripe.

Paso 5: ¿Qué más existe por separado en cada entorno?

• La configuración del portal de clientes. Stripe guarda un juego de configuraciones para live y otro por cada sandbox, así que vuelve a activar cancelación, cambio de plan e historial de facturas en live. En la guía del portal de clientes de Stripe están todas las opciones.
• Los IDs de cliente guardados en tu base de datos. Si tus usuarios de prueba tienen un stripe_customer_id del sandbox, las llamadas live con ese ID fallan porque ese cliente no existe allí. Limpia los datos de prueba o usa bases de datos distintas para pruebas y producción.
• Los correos a clientes. En un sandbox, Stripe solo envía correos a direcciones de tu dominio verificado o a miembros del equipo. En live, los recibos, avisos de pago fallido y recordatorios de tarjeta por vencer llegan a clientes reales: revisa esa configuración antes de lanzar.
• La versión de la API. Fíjala en la librería de tu servidor para que una actualización desde el Dashboard no cambie la forma de los objetos que lee tu código.

Paso 6: ¿Cómo confirmas que todo funciona?

Haz un pago real de punta a punta con tu propia tarjeta, con el plan más barato que vendas.

1. Regístrate como usuario nuevo en el sitio de producción y compra el plan.
2. En el Dashboard live, confirma que existen el pago y la suscripción.
3. En Workbench, abre la pestaña Event deliveries del endpoint live y verifica que cada evento figure como entregado, con respuesta 2xx.
4. Comprueba que tu app muestra el plan pagado y que el portal de clientes abre.
5. Cancela y reembolsa la compra. Ten en cuenta que Stripe no devuelve su comisión de procesamiento al reembolsar, así que esta prueba tiene un costo pequeño.

Respuestas rápidas

¿Puedo seguir usando claves de prueba en un sitio de staging después del lanzamiento? Sí, y es lo recomendable. Staging apunta a un sandbox y producción a live, cada uno con sus claves y su secreto de webhook.

¿Mis clientes y suscripciones del sandbox pasan a live? No. Nada del sandbox pasa a live; los clientes reales empiezan de cero.

¿Por qué los webhooks del sandbox funcionan y los live no? Casi siempre porque producción todavía tiene el secreto de firma del sandbox, o porque nunca se creó el endpoint live.

¿Necesito otro código de Checkout para live? No. El mismo código sirve si las claves, la búsqueda de precios y los secretos salen de variables de entorno.

¿Lanzas pronto y quieres una segunda mirada?

El paso a live toca claves, webhooks y tu base de datos al mismo tiempo, por eso vale la pena revisarlo una vez antes de que lleguen clientes reales. Mira nuestro servicio de pagos con Stripe, pasa la revisión gratuita de tu app, ten a mano la checklist oficial de Stripe para salir a producción o escríbenos con tu fecha de lanzamiento.