PayPal Subscriptions: setup abbonamenti
L'API PayPal Subscriptions permette di creare piani di abbonamento ricorrente con addebito automatico al cliente. È la soluzione moderna per SaaS, membership, riviste online, palestre digitali e qualsiasi servizio con fatturazione periodica. Sostituisce le vecchie Reference Transactions e offre flussi standardizzati, trial gratuiti, prezzi variabili e gestione completa del ciclo di vita.
Architettura: Product, Plan, Subscription
Tre entità gerarchiche. Il Product rappresenta cosa vendi (es. "Abbonamento Rivista Online", id PROD-123). Un Plan è una configurazione di prezzo per quel prodotto: durata, frequenza, importo (es. "Piano Mensile a 9,99 euro/mese", id P-456). Una Subscription è l'attivazione del piano per un cliente specifico (es. sub_id I-789). Il cliente attiva la subscription, PayPal addebita automaticamente alla scadenza di ogni ciclo.
Trial e billing cycles
Un Plan può avere più billing_cycles. Esempio tipico: primo ciclo TRIAL gratuito (durata 14 giorni, importo 0), secondo ciclo REGULAR (ricorrenza mensile, importo 9,99 euro). Puoi anche definire un "intro pricing" (es. primi 3 mesi a 4,99 poi a 9,99). Il numero massimo di total_cycles può essere finito (es. 12 = abbonamento annuale) o infinito (rinnovo automatico finché non cancellato).
Procedura passo-passo
- Crea un Product con POST /v1/catalogs/products specificando name, description, type=SERVICE.
- Crea un Plan con POST /v1/billing/plans collegato al product_id, con billing_cycles dettagliati.
- Attiva il Plan con POST /v1/billing/plans/{id}/activate.
- Genera link di sottoscrizione con POST /v1/billing/subscriptions specificando plan_id e subscriber.
- Reindirizza il cliente al link "approve" del response.
- Il cliente accede a PayPal, conferma l'abbonamento e autorizza i rinnovi.
- Ricevi webhook BILLING.SUBSCRIPTION.ACTIVATED.
- Aggiorna il database: il cliente è ora abbonato.
- Sottoscrivi altri webhook: BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.SUSPENDED, PAYMENT.SALE.COMPLETED (per ogni rinnovo).
- Gestisci il ciclo di vita: rinnovi, sospensioni per fallimento pagamento, riattivazioni.
Gestione fallimenti di pagamento
Se il rinnovo fallisce (carta scaduta, fondi insufficienti) PayPal mette la subscription in stato SUSPENDED e tenta di nuovo automaticamente fino a 3 volte. Configura il piano con auto_renewal_failure_max_attempts e payment_failure_threshold per personalizzare il comportamento. Sottoscrivi il webhook BILLING.SUBSCRIPTION.PAYMENT.FAILED per avvisare il cliente via email e invitarlo ad aggiornare il metodo di pagamento.
Modifica del piano
Puoi proporre upgrade/downgrade a un cliente esistente con POST /v1/billing/subscriptions/{id}/revise specificando il nuovo plan_id. Il cliente riceve un link da confermare; al consenso il piano cambia al ciclo successivo (prorata opzionale). Non puoi modificare un Plan attivo; devi crearne uno nuovo e spostare gli abbonati.
Cancellazione e sospensione
L'abbonamento può essere cancellato dal merchant via POST /v1/billing/subscriptions/{id}/cancel con motivo nel body. Può essere sospeso temporaneamente (utile per "freeze" durante le ferie del cliente) con /suspend e poi riattivato con /activate. Quando viene cancellato l'accesso al servizio va terminato al fine del ciclo corrente, non immediatamente: il cliente ha pagato fino a quella data.
Errori comuni e come risolverli
- Plan non attivato: dopo creazione devi chiamare /activate, altrimenti gli utenti non possono sottoscriverlo.
- Webhook BILLING.* non sottoscritti: senza webhook non sai quando un cliente rinnova o annulla.
- Auto-renewal failure thresholds troppo bassi: 1 retry e poi cancel = perdita di clienti. Usa 3+ retry.
- Mancata gestione del trial period: il cliente aspetta il primo addebito, devi tracciarlo correttamente.
Domande frequenti
D: Posso modificare il prezzo a un cliente esistente?
R: Solo via /revise con nuovo plan_id; il cliente deve approvare il cambio.
D: PayPal trattiene commissione anche sui rinnovi?
R: Sì, la commissione standard si applica a ogni transazione ricorrente.
D: Cosa succede se il cliente cambia carta?
R: PayPal aggiorna automaticamente il funding instrument; di norma non c'è interruzione.
Consigli operativi e best practice
Per consolidare quanto visto nei paragrafi precedenti tieni a mente alcuni accorgimenti pratici che fanno la differenza nel quotidiano. Documenta sempre ogni passaggio della configurazione in un registro interno aziendale: serve sia per il team sia in caso di audit fiscale o di richiesta di chiarimenti da parte di PayPal. Conserva una copia delle ricevute, delle email transazionali e degli screenshot dei pannelli di amministrazione per almeno dieci anni, come richiesto dalla normativa civilistica italiana.
Pianifica una revisione trimestrale della tua integrazione PayPal: verifica le commissioni applicate, controlla i tassi di contestazione, leggi gli avvisi nel Centro Risoluzioni e aggiorna eventuali plugin o SDK obsoleti. Le aziende che fanno questo controllo regolare riducono del 40-60% gli incidenti operativi rispetto a chi gestisce PayPal in modo reattivo. Coinvolgi anche il team di customer service: spesso sono loro i primi a notare pattern di richieste che possono indicare problemi nascosti nel flusso di pagamento.
Infine, abituati a monitorare i tempi di risposta nelle dispute e nei reclami: PayPal premia i merchant che rispondono entro 24-48 ore con score reputazionali migliori, che si traducono in minori riserve, commissioni più favorevoli al raggiungimento dei volumi e un'esperienza più fluida in caso di controlli antifrode. La gestione proattiva è sempre meno costosa di quella reattiva, in PayPal come nel resto del business online.
Hai bisogno di aiuto?
Se vuoi integrare PayPal nel tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.