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/modules/billing-configuration.md (or send Accept: text/markdown).
Configuración de Stripe y webhooks
Conecta las suscripciones web con derechos controlados por el servidor.
Configuración y ajustes
Antes de cualquier paso, lea Antes de comenzar y Conceptos básicos del terminal. Estas instrucciones suponen que abrió el monorepo supastack completo en VS Code; su paquete raíz.json marca la raíz del repositorio. En los comandos pnpm, un paquete de espacio de trabajo es una aplicación o una carpeta de código compartido; En el producto, un espacio de trabajo es el contenedor de datos y el límite de seguridad de un equipo. corepack pnpm --filter ... selecciona un paquete del monorepo mientras los comandos se ejecutan desde su raíz. Si abrió solo una carpeta sincronizada para dispositivos móviles o de escritorio, no contiene el backend web, la configuración de Docker ni los scripts raíz: ejecute el backend desde este monorepo o un servidor alojado accesible y use los propios scripts de la carpeta de la plataforma. Una variable de entorno es una configuración con nombre almacenada en un archivo .env local o en su panel de hosting; reinicie la aplicación correspondiente después de cambiarla y mantenga los secretos del servidor fuera de los valores NEXT_PUBLIC_ y EXPO_PUBLIC_.
1. Abra apps/web/.env.local y mantenga BILLING_PROVIDER=local mientras aprende la pantalla de pago.
2. Para una integración real, cree productos en modo de prueba en un proveedor, luego agregue sus claves de servidor y su secreto de webhook a la configuración del entorno privado del servidor web. Un webhook es un mensaje firmado que el servicio de facturación envía a su aplicación después del pago, la renovación o la cancelación; la ruta del punto final aparece en el ejemplo de código de esta guía.
3. Inicie Web con corepack pnpm --filter @supastack/web dev y pruebe solo el sandbox. Se espera: un webhook verificado actualiza los derechos del espacio de trabajo en el que se ha iniciado sesión; Abrir una página de pago por sí sola no otorga acceso.
Usa credenciales de sandbox/prueba durante la integración. Configura BILLING_PROVIDER junto con los secretos del proveedor, solo en el servidor: stripe → STRIPE_SECRET_KEY, STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET; lemonsqueezy → LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_VARIANT_ID, LEMONSQUEEZY_WEBHOOK_SECRET; creem → CREEM_API_KEY, CREEM_PRODUCT_ID, CREEM_WEBHOOK_SECRET (CREEM_TEST_MODE=true para el sandbox); polar → POLAR_ACCESS_TOKEN, POLAR_PRODUCT_ID, POLAR_WEBHOOK_SECRET (POLAR_SERVER); whop → WHOP_API_KEY, WHOP_PLAN_ID, WHOP_WEBHOOK_SECRET; paddle → PADDLE_API_KEY, PADDLE_PRICE_ID, PADDLE_WEBHOOK_SECRET (PADDLE_ENVIRONMENT); dodo → DODO_PAYMENTS_API_KEY, DODO_PRODUCT_ID, DODO_PAYMENTS_WEBHOOK_KEY (DODO_PAYMENTS_ENVIRONMENT); paypal → PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_PLAN_ID, PAYPAL_WEBHOOK_ID (PAYPAL_ENVIRONMENT). El precio/producto debe representar la suscripción recurrente prevista.
Webhook endpoint: /api/billing/webhook (stripe), /api/billing/webhook/lemonsqueezy, /api/billing/webhook/creem, /api/billing/webhook/polar, /api/billing/webhook/whop, /api/billing/webhook/paddle, /api/billing/webhook/dodo, /api/billing/webhook/paypal
Checkout endpoint: /api/billing/checkout
Portal endpoint: /api/billing/portalComandos para copiar
Siga los comentarios para ver en qué carpeta se ejecuta un comando. Si dos terminales están etiquetados, abra dos ventanas de terminal y mantenga el primer comando ejecutándose mientras usa el segundo.
corepack pnpm --filter @supastack/web devFlujo de implementación
Al configurar el endpoint del webhook, sigue la lista de eventos del ciclo de vida en docs/real-provider-smoke.md. La verificación de la firma necesita el secreto correspondiente al endpoint. Una redirección al checkout nunca debe conceder acceso por sí sola.
El derecho en el límite de la acción del servidor decide si se permite el trabajo de pago. Procesa los eventos repetidos con seguridad y vincula los registros del cliente y la suscripción al espacio de trabajo correcto. El checkout web sigue separado de las compras nativas.
La clave que concede un plan es vocabulario del producto compartido entre superficies: ProductPlan.entitlement en src/product-plans.ts declara la clave de máquina en minúsculas que se escribe en el registro mientras el plan está pagado (el kit incluye 'ai.reference-task' en pro y lifetime; src/billing-runtime.ts se la pasa al BFF). La misma clave se compara por igualdad con el campo required_entitlement de una entrada del CMS y con la propiedad entitlementKey del componente EntitlementGate: una entrada protegida con 'ai.reference-task' se desbloquea para cualquier espacio de trabajo que tenga ese permiso, mientras que una clave que ningún plan concede permanece bloqueada para todos.
Verificación y solución de problemas
Si se rechaza un webhook, compare la zona de pruebas exacta URL y el secreto de firma en el panel del proveedor con la configuración del servidor, y verifique si ese proveedor requiere reenviar solicitudes a localhost. Si el pago funciona pero el acceso permanece bloqueado, inspeccione el resultado del webhook y la clave de derecho en el plan. Nunca realice pruebas con credenciales de pago en vivo mientras sigue esta guía local.
Prueba la activación, las actualizaciones, la cancelación, las firmas no válidas y los eventos repetidos en el sandbox. Inspecciona el estado de acceso persistido después del procesamiento. Crear una sesión de checkout sin consumirla solo demuestra conectividad, no el cumplimiento del ciclo de vida.