Faro Payments

FLUSSO DECISIONALE

Pagamento una tantum → Checkout Session mode='payment'
Abbonamento         → Checkout Session mode='subscription' + trial_period_days
Upgrade/downgrade   → Customer Portal (Stripe gestisce tutto)
Verifica piano      → getSubscriptionPlan(userId) in ogni Server Action protetta

Webhook obbligatori da implementare:
checkout.session.completed → attiva abbonamento
customer.subscription.updated → aggiorna piano
customer.subscription.deleted → cancella abbonamento
invoice.payment_failed → stato PAST_DUE + email utente
invoice.paid → aggiorna periodo_fine

REGOLE CHIAVE

1. Chiavi test vs produzione separate in env — mai chiavi prod in sviluppo
2. Webhook endpoint configurato su Stripe Dashboard prima del deploy
3. STRIPE_WEBHOOK_SECRET obbligatorio per validare firma webhook
4. Idempotenza webhook — tabella webhook_events per evitare doppio processing
5. utente_id nei metadata del checkout — necessario per associare il pagamento
6. Implementa tutti e 5 gli eventi webhook — non solo checkout.session.completed
7. Customer Portal per gestione self-service — non costruirlo da zero
8. automatic_tax: true per IVA automatica per paese utente
9. Test con Stripe CLI prima del deploy in produzione
10. stato: PAST_DUE su invoice.payment_failed + email immediata all'utente

FLUSSO OPERATIVO

1. Stripe setup: crea prodotti + prezzi nel Dashboard
2. Schema DB: tabella abbonamenti + webhook_events per idempotenza
3. Checkout Session: endpoint /api/checkout con userId nei metadata
4. Webhook handler: /api/stripe/webhook con signature verify + idempotency
5. Customer Portal: link in settings account
6. Feature gate: getSubscriptionPlan() prima di operazioni PRO
7. Test: Stripe CLI stripe listen + card test 4242 4242 4242 4242
8. Deploy: cambia chiavi + endpoint webhook produzione

CHECKLIST

• Chiavi test vs produzione separate in env
• Webhook endpoint configurato su Stripe Dashboard
• STRIPE_WEBHOOK_SECRET aggiunto all'env
• Idempotenza webhook (tabella webhook_events)
• Gestione invoice.payment_failed con email all'utente
• Customer Portal configurato
• Schema DB abbonamenti con stato e periodo_fine
• Protezione route per piano (FREE non vede funzionalità PRO)
• Test con Stripe CLI prima del deploy
• Transizione da test a produzione: aggiorna chiavi env in produzione
• Automatic tax abilitato (IVA automatica per paese utente)

TABELLA — Eventi webhook critici

Web vs Mobile: Stripe, IAP, e policy degli store

Stripe funziona su web senza restrizioni. Su mobile (iOS/Android) digital goods richiedono Apple IAP o Google Play Billing (Stripe VIETATO); physical goods e servizi fuori-app possono usare Stripe. Per un SaaS web + mobile valuta RevenueCat (unifica Stripe e IAP con un'unica API).

Dettagli, workaround legittimi (reader app, DMA UE, ruling Epic 2024), strategia per SaaS multi-target e anti-pattern in references/stripe-patterns.md → sezione "Web vs Mobile".

REFERENCES

Per dettagli tecnici completi, leggi:

• [references/stripe-patterns.md] — checkout session, subscription lifecycle, webhook handler idempotente, customer portal, fatturazione IVA, test con Stripe CLI, Web vs Mobile (IAP)