> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # 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. [Configurar la base de datos](https://supastack.dev/es/docs/web/setup-database.md) [Configurar RevenueCat para las compras móviles](https://supastack.dev/es/docs/mobile/revenuecat.md) ## Crear la cuenta de Stripe 1. Abre [stripe.com](https://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 toggle ``` ## Verificar 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. [Comparar los proveedores de facturación](https://supastack.dev/es/docs/web/setup-payments.md) [Añadir a continuación el email con Resend](https://supastack.dev/es/docs/web/resend-email.md) [Las compras móviles usan RevenueCat](https://supastack.dev/es/docs/mobile/revenuecat.md) Si quieres continuar la configuración, lee [Añadir el email con Resend](https://supastack.dev/es/docs/web/resend-email.md). ## Siguiente [Añadir el email con Resend](https://supastack.dev/es/docs/web/resend-email.md)