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 /it/docs/modules/billing-configuration.md (or send Accept: text/markdown).
Configurazione Stripe e webhook
Collega gli abbonamenti web ai permessi lato server.
Installazione e configurazione
Prima di qualsiasi passaggio, leggere Prima di iniziare e Nozioni di base sui terminali. Queste istruzioni presuppongono che tu abbia aperto l'intero supastack monorepo in VS Code; la sua radice package.json contrassegna la radice del repository. Nei comandi pnpm, un pacchetto dell'area di lavoro è un'app o una cartella di codice condiviso; nel prodotto, uno spazio di lavoro è il contenitore dei dati di un team e il limite di sicurezza. corepack pnpm --filter ... seleziona un pacchetto dal monorepo mentre i comandi vengono eseguiti dalla sua radice. Se hai aperto solo una cartella mobile o desktop sincronizzata, non contiene il backend Web, la configurazione di Docker o gli script root: esegui il backend da questo monorepo o da un server ospitato raggiungibile e utilizza gli script della cartella della piattaforma. Una variabile di ambiente è un'impostazione denominata memorizzata in un file .env locale o nel dashboard dell'hosting; riavvia l'app pertinente dopo averla modificata e mantieni i segreti del server fuori dai valori NEXT_PUBLIC_ e EXPO_PUBLIC_.
1. Apri apps/web/.env.local e mantieni BILLING_PROVIDER=local mentre visualizzi la schermata di pagamento.
2. Per un'integrazione reale, creare prodotti in modalità test in un provider, quindi aggiungere le chiavi del server e il segreto del webhook alle impostazioni dell'ambiente privato dell'host Web. Un webhook è un messaggio firmato che il servizio di fatturazione invia alla tua app dopo il checkout, il rinnovo o l'annullamento; il percorso dell'endpoint è elencato nell'esempio di codice di questa guida.
3. Avviare Web con corepack pnpm --filter @supastack/web dev e testare solo il sandbox. Previsto: un webhook verificato aggiorna i diritti dell'area di lavoro su cui è stato eseguito l'accesso; la sola apertura di una pagina di pagamento non garantisce l'accesso.
Utilizza credenziali sandbox/test durante l'integrazione. Configura BILLING_PROVIDER più i segreti solo server del provider: stripe → STRIPE_SECRET_KEY, STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET; spremuta di limone → 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 per la sandbox); polare → 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). Il prezzo/prodotto deve rappresentare l'abbonamento ricorrente previsto.
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/portalComandi da copiare
Segui i commenti per vedere in quale cartella viene eseguito un comando. Se due terminali sono etichettati, apri due finestre di terminale e mantieni il primo comando in esecuzione mentre usi il secondo.
corepack pnpm --filter @supastack/web devFlusso di implementazione
Segui la lista degli eventi del ciclo di vita in docs/real-provider-smoke.md per configurare l'endpoint webhook. La verifica della firma richiede il segreto webhook corrispondente all'endpoint. Un redirect di checkout da solo non deve mai concedere accesso.
Il permesso alla frontiera dell'azione server decide se il lavoro a pagamento è consentito. Tratta gli eventi ripetuti in sicurezza e delimita i record cliente/abbonamento al workspace giusto. Il checkout web resta separato dagli acquisti nativi.
La chiave garantita da un piano è il vocabolario del prodotto condiviso su tutte le superfici: ProductPlan.entitlement in src/product-plans.ts dichiara la chiave macchina in minuscolo scritta nel registro mentre un piano viene pagato (il kit viene spedito "ai.reference-task" su pro e life; src/billing-runtime.ts lo passa a BFF). La stessa chiave è ciò con cui si confronta il campo require_entitlement di una voce CMS e il prop equality-compare entitlementGate del componente EntitlementGate: una voce controllata su "ai.reference-task" si sblocca per qualsiasi area di lavoro che detiene tale concessione, mentre una chiave che nessun piano concede rimane bloccata per tutti.
Verifica e risoluzione dei problemi
Se un webhook viene rifiutato, confronta l'esatto sandbox URL e il segreto di firma nel dashboard del provider con le impostazioni del server e controlla se il provider richiede l'inoltro delle richieste a localhost. Se il checkout funziona ma l'accesso rimane bloccato, controlla il risultato del webhook e la chiave di autorizzazione sul piano. Non eseguire mai test con credenziali di pagamento in tempo reale mentre segui questa guida locale.
Testa attivazione, aggiornamenti, cancellazione, firme non valide ed eventi ripetuti nella sandbox. Ispeziona lo stato di accesso persistito dopo l'elaborazione. Creare una sessione di checkout non consumata dimostra solo connettività, non il fulfillment del ciclo di vita.