PayPal Recurring Payments: configurazione
Il termine Recurring Payments su PayPal copre due tecnologie diverse: la vecchia "Express Checkout Recurring Payments" (NVP/SOAP, deprecata) e la moderna "Subscriptions API" (REST). Per i nuovi merchant la scelta è netta: usare Subscriptions. Per chi ha integrazioni legacy vediamo come funzionano i Recurring Payments classici, quando ha senso mantenerli e quando migrare.
Recurring Payments legacy
Il flusso legacy si basa su tre chiamate NVP. SetExpressCheckout con campi BILLINGPERIOD, BILLINGFREQUENCY, AMT crea il profilo. Dopo l'approvazione del cliente, CreateRecurringPaymentsProfile genera il profile_id e schedula gli addebiti. ManageRecurringPaymentsProfileStatus permette di sospendere, riattivare o cancellare il profilo. Le notifiche di esito dei rinnovi arrivano via IPN con txn_type=recurring_payment.
Quando usare Recurring legacy vs Subscriptions
Usa Recurring legacy SOLO se hai un'integrazione esistente che funziona bene e che migrare avrebbe costo eccessivo. Per tutto il resto Subscriptions è migliore: payload JSON, webhook firmati, gestione trial più flessibile, supporto per upgrade/downgrade, SDK moderni. Recurring legacy continua a funzionare ma non riceve nuove feature.
Procedura passo-passo (legacy)
- Ottieni credenziali API NVP (Username, Password, Signature) dal pannello Business.
- Chiama SetExpressCheckout con i campi BILLINGPERIOD (Day/Week/Month/Year), BILLINGFREQUENCY (es. 1 = ogni mese), AMT (importo per ciclo), TOTALBILLINGCYCLES (0 = infinito).
- Ricevi token e reindirizza il cliente al checkout PayPal.
- Cliente approva.
- Chiama CreateRecurringPaymentsProfile con il token.
- Ricevi PROFILEID (es. I-XXXXX) e salvalo.
- Configura il listener IPN per ricevere notifiche txn_type=recurring_payment.
- Aggiorna database a ogni rinnovo riuscito.
- Gestisci cancellazione con ManageRecurringPaymentsProfileStatus action=Cancel.
Vault e Reference Transactions
Per chi vuole controllo totale sul timing degli addebiti (es. SaaS con consumi variabili) c'è il programma "Reference Transactions": il cliente autorizza una volta, e il merchant può eseguire addebiti arbitrari quando vuole tramite API DoReferenceTransaction. Richiede l'attivazione del programma da parte di PayPal (contatti commerciali). È utile per pay-per-use, billing on-demand, abbonamenti con add-on. La versione REST equivalente è "Vault" + "Payment Tokens".
Migrazione a Subscriptions
Non esiste una migrazione automatica: i profile_id legacy non sono interscambiabili con subscription_id REST. La strategia tipica è: nuovi abbonati su Subscriptions, vecchi abbonati restano su Recurring legacy finché cancellano. Quando un cliente legacy vuole modificare il piano, cancella il profilo legacy e ne crea uno nuovo via Subscriptions. Pianifica una migrazione progressiva su 12-24 mesi a seconda del churn naturale.
Errori comuni e come risolverli
- BILLINGFREQUENCY=0: invalido. Deve essere almeno 1.
- Mancata gestione "skipped" payments: se PayPal salta un'addebito (es. carta scaduta), il txn arriva con status Failed. Notifica il cliente.
- Cancellazione lato cliente non rilevata: il cliente può cancellare da paypal.com. Sottoscrivi IPN per recurring_payment_profile_cancel.
- Mancata sincronizzazione status: usa GetRecurringPaymentsProfileDetails per verificare status reale periodicamente.
Domande frequenti
D: PayPal disabiliterà i Recurring Payments legacy?
R: Non c'è data ufficiale. Resta supportato ma in maintenance.
D: Posso avere clienti su entrambe le tecnologie?
R: Sì, coesistono nello stesso account.
D: I rinnovi legacy emettono fattura automatica?
R: No, PayPal non emette fatture fiscali. Devi farlo tu lato gestionale.
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.
Vale la pena ricordare che ogni implementazione PayPal va testata in ambiente Sandbox prima del passaggio in produzione: simulare ogni scenario (successo, errore, timeout, refund parziale, dispute) permette di intercettare i bug più subdoli senza rischio reale di addebiti errati a clienti veri. Investi almeno una giornata di test prima del go-live, soprattutto se la tua integrazione coinvolge più sistemi come gestionale, CRM, magazzino, sistema di spedizioni o cassa fisica.
Mantieni inoltre un canale di comunicazione diretto con il supporto merchant PayPal: per gli account Business con volumi rilevanti è possibile avere un'account manager dedicato che risponde via email o telefono per problematiche complesse. Per i merchant più piccoli c'è il supporto via chat e centro assistenza online, con tempi di risposta tra le 2 e le 24 ore. Documenta sempre il ticket number nelle comunicazioni interne per agevolare follow-up successivi.
Hai bisogno di aiuto?
Se vuoi integrare PayPal nel tuo sito con il team di G Tech Group, scrivici tramite il modulo di contatto.