For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /es/docs/web/stripe-payments.md (or send Accept: text/markdown).
Añadir los pagos con Stripe
Crea una cuenta de Stripe gratuita, un producto con un precio recurrente, una clave secreta y el webhook firmado que concede entitlements tras el checkout.
Guía paso a paso para principiantes
Prerrequisitos: la app corriendo en local (Lanza en 5 minutos) y una base de datos migrada para cuentas reales (Configurar la base de datos). Necesitas una dirección de email para la cuenta de Stripe — sin tarjeta y sin cargos. Todo en esta guía ocurre en modo de prueba: dinero ficticio, números de tarjeta de prueba y reintentos ilimitados antes de salir en vivo.
Términos rápidos: el modo de prueba es el sandbox de Stripe — el interruptor Test mode del panel mantiene cada clave, producto y pago como ficticio hasta que lo apagas. Una secret key (sk_test_…) es la contraseña de tu servidor ante Stripe. Un producto con un precio es lo que compran los clientes; un price id (price_…) lo nombra en el código. Un webhook es Stripe llamando a tu servidor cuando un pago tiene éxito o una suscripción cambia, y el signing secret (whsec_…) demuestra que la llamada viene realmente de Stripe.
Lo que creas: una cuenta de Stripe, un producto con un precio recurrente, una clave de API secreta y un endpoint de webhook — unos veinte minutos. Stripe aloja la propia página de checkout; el kit crea la sesión en el servidor y redirige, así que no hace falta ninguna clave publishable de navegador.
Ten en cuenta el alcance: esta guía vende solo suscripciones web. Las compras dentro de la app iOS/Android deben pasar por la facturación de Apple y Google — nunca por Stripe Checkout — por eso el móvil usa RevenueCat en su lugar.
Crear la cuenta de Stripe
1. Abre stripe.com → Start now y regístrate con tu email.
2. La incorporación pregunta por tu negocio — en modo de prueba puedes saltarte cada pregunta y aun así usar el sandbox completo; completa la activación solo antes de aceptar pagos reales.
Esperado: llegas al panel con el interruptor Test mode visible en la cabecera. Déjalo activado para todo lo siguiente — las claves live van después en tu almacén de secretos de producción, nunca en un archivo env del portátil.
Copiar las claves de API
1. En el panel abre Developers → API keys.
2. Ves dos claves de prueba: una Publishable key pk_test_… y una Secret key enmascarada. Haz clic en Reveal test key junto al secreto y copia el valor sk_test_….
El kit solo necesita la secret key: las sesiones de checkout se crean en el servidor y el usuario es redirigido a la página alojada de Stripe, así que ninguna publishable key llega a las variables env. Si un producto que construyas más adelante añade Stripe.js usarías la publishable key en el cliente; el flujo de facturación del kit no lo hace.
La clave sk_test_… es una credencial completa para la cuenta sandbox: vive en apps/web/.env.local o en un almacén de secretos, nunca en variables NEXT_PUBLIC_/EXPO_PUBLIC_ y nunca en Git.
Crear el producto y el precio
1. Abre Product catalog → Add product.
2. Ponle el nombre de tu plan — Pro coincide con el plan incluido del kit — dale un precio y elige Recurring (mensual, por ejemplo): el checkout del kit crea sesiones en modo suscripción, que requieren un precio recurrente, no uno de pago único.
3. Guarda, abre el producto y copia el price id — empieza por price_… (no prod_…, que es el id de producto).
El plan pro incluido ya muestra un conmutador Monthly/Yearly: el mensual paga con STRIPE_PRICE_ID, y la opción anual necesita un segundo precio recurrente en STRIPE_PRICE_ID_PRO_YEARLY — sin él, un checkout anual falla con price-unconfigured. Cambia los nombres de plan, los importes y lo que concede una compra en apps/web/src/product-plans.ts — Stripe guarda la parte del dinero, el archivo de planes guarda la parte del entitlement.
Añadir el endpoint de webhook
El webhook es lo que realmente concede el acceso: el kit activa el entitlement solo después de que llegue un evento firmado de Stripe, así que una redirección de checkout por sí sola no prueba nada.
1. Abre Developers → Webhooks → Add endpoint.
2. Endpoint URL: tu URL pública más /api/billing/webhook — por ejemplo https://yourdomain.com/api/billing/webhook. Los demás proveedores de facturación tienen su propia ruta bajo ese directorio; el receptor de Stripe vive en la raíz.
3. En Select events elige los eventos que maneja el kit: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated y customer.subscription.deleted.
4. Crea el endpoint, abre su página, haz clic en Reveal bajo Signing secret y copia el valor whsec_… — cada endpoint tiene su propio secreto.
El desarrollo local no puede recibir los servidores de Stripe, así que usa la Stripe CLI en su lugar: stripe login una vez, luego stripe listen --forward-to localhost:3000/api/billing/webhook en un segundo terminal. Imprime un whsec_… temporal — ese valor, no el del panel, va en .env.local mientras stripe listen se ejecuta.
Añadir los valores a la app
Escribe las líneas de abajo en apps/web/.env.local. BILLING_PROVIDER=stripe selecciona el adaptador; las otras tres son la clave, el precio y el signing secret. Activar el proveedor con alguna de ellas ausente hace fallar el arranque y nombra la variable.
Los tres valores STRIPE_* son solo de servidor — nunca NEXT_PUBLIC_/EXPO_PUBLIC_, nunca commiteados; producción los recibe a través del gestor de secretos del hosting (la guía de despliegue cubre Secret Manager). Reinicia el servidor de desarrollo después de editar.
# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_… # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_… # required for the shipped Yearly toggleVerificar y solucionar problemas
Arranca stripe listen --forward-to localhost:3000/api/billing/webhook y déjalo corriendo, reinicia el servidor de desarrollo, luego abre /billing, elige el plan Pro y termina el checkout alojado de Stripe con la tarjeta de prueba 4242 4242 4242 4242, cualquier caducidad futura y cualquier CVC.
Esperado: la app vuelve a /billing?checkout=success y el entitlement del workspace pasa a activo — el terminal de listen registra los eventos entregados, y Developers → Webhooks → tu endpoint en el panel muestra entregas en verde.
Para ejercitar el receptor sin hacer clic en el checkout, stripe trigger checkout.session.completed envía un evento sintético a través del reenviador de listen.
Fallos comunes: un 400 en cada entrega significa que el signing secret no coincide con ese endpoint — vuelve a copiar whsec_… del endpoint correcto y actualiza el env; efectos nulos silenciosos significan que BILLING_PROVIDER sigue en local; y claves sk_live_ mezcladas en un montaje de prueba significan que copiaste las claves del modo equivocado — mantén test y live estrictamente separados.
El kit incluye el mismo adaptador de un solo contrato para Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo y PayPal — mismo flujo, consola y nombres de env distintos — y las compras móviles se quedan en RevenueCat, no en Stripe.
Si quieres continuar la configuración, lee Añadir el email con Resend.