Stripe per Developer: Integrazione Completa con Abbonamenti e One-Time Payment

Hai costruito il tuo Micro SaaS, l’MVP funziona, i primi utenti sono entusiasti. Ora arriva il momento della verità: come accetti i pagamenti? Stripe è lo standard de facto per i developer — ma la sua documentazione è vastissima. Questa guida ti porta dall’installazione alla gestione degli abbonamenti nel modo più diretto possibile.

Setup Iniziale e Credenziali

npm install stripe @stripe/stripe-js

// lib/stripe.js
import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: '2024-12-18.acacia',
});

// Usa sempre la chiave test (sk_test_...) in development
// e la chiave live (sk_live_...) in production

One-Time Payment con Checkout Session

Il modo più rapido per accettare un pagamento singolo. Stripe gestisce tutto — form di pagamento, validazione carta, 3D Secure — tu ricevi solo la conferma.

// api/checkout/route.js (Next.js App Router)
import { stripe } from '@/lib/stripe';
import { NextResponse } from 'next/server';

export async function POST(request) {
  const { priceId, userId } = await request.json();

  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    payment_method_types: ['card'],
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/cancel`,
    metadata: { userId }, // Passa dati custom per il webhook
  });

  return NextResponse.json({ url: session.url });
}

Abbonamenti Ricorrenti con Stripe Billing

Per un SaaS con piano mensile/annuale, usa mode: 'subscription'. Crea prima i Price objects nella Stripe Dashboard, poi usali nell’API.

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  payment_method_types: ['card'],
  line_items: [{
    price: 'price_1234...', // ID dal Stripe Dashboard
    quantity: 1,
  }],
  subscription_data: {
    trial_period_days: 14, // Trial gratuito
    metadata: { userId },
  },
  success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
  customer_email: user.email, // Pre-compila l'email
});

Webhooks: Il Pezzo Più Importante

I webhooks sono fondamentali: Stripe ti notifica quando un pagamento va a buon fine, quando una subscription si rinnova, quando una carta viene rifiutata. Senza webhooks, non puoi aggiornare il database in modo affidabile.

// api/webhooks/stripe/route.js
import { stripe } from '@/lib/stripe';
import { headers } from 'next/headers';

export async function POST(request) {
  const body = await request.text();
  const signature = headers().get('stripe-signature');

  let event;
  try {
    // FONDAMENTALE: verifica la firma per sicurezza
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }

  switch (event.type) {
    case 'checkout.session.completed':
      const session = event.data.object;
      await activateSubscription(session.metadata.userId);
      break;
    case 'invoice.payment_failed':
      const invoice = event.data.object;
      await suspendAccount(invoice.customer);
      break;
    case 'customer.subscription.deleted':
      await cancelSubscription(event.data.object.metadata.userId);
      break;
  }

  return new Response(null, { status: 200 });
}

💡 Pro tip: Per testare i webhooks in locale usa stripe listen --forward-to localhost:3000/api/webhooks/stripe dalla Stripe CLI. Non devi deployare ogni volta per testare il webhook handler.

Per il progetto completo ti servirà uno stack zero-cost per il tuo SaaS. Puoi partire da zero seguendo la guida su come lanciare un Micro SaaS.

FAQ e Domande Frequenti

Stripe è disponibile per partite IVA italiane?

Sì, Stripe è pienamente operativo in Italia. Puoi registrarti con partita IVA, ricevere pagamenti in euro, e i fondi vengono trasferiti sul tuo conto corrente italiano entro 2-7 giorni lavorativi.

Quanto trattiene Stripe su ogni transazione?

Il piano standard è 1.5% + 0.25€ per le carte europee, 2.5% + 0.25€ per le carte non europee. Nessun canone mensile fisso. Per volumi elevati puoi negoziare tariffe custom.

Come gestisco i rimborsi?

Via API: stripe.refunds.create({ payment_intent: 'pi_...' }) oppure dalla Dashboard Stripe. Stripe restituisce il costo della transazione solo per rimborsi totali entro 90 giorni.

Devo implementare il Customer Portal per le cancellazioni?

Stripe offre un Billing Portal pre-costruito che gestisce upgrade, downgrade e cancellazioni. Basta creare una sessione con stripe.billingPortal.sessions.create() — nessun frontend da scrivere.

🔧 Strumenti: stripe.com/docs · Stripe CLI · stripe-node SDK | 🎯 Takeaway: Inizia con Checkout Session per ridurre al minimo il codice frontend. Implementa i webhook da subito — sono essenziali per la consistenza del database.