Configurare IPN (Instant Payment Notification) PayPal
L'Instant Payment Notification (IPN) è il sistema legacy di PayPal per notificare in tempo reale ai server merchant l'esito di una transazione: pagamento completato, rimborso, chargeback, autorizzazione. È stato lo standard per oltre 15 anni e milioni di e-commerce ne dipendono ancora. PayPal lo affianca oggi ai webhook REST più moderni, ma IPN resta supportato e ampiamente usato. In questo articolo vediamo come configurarlo correttamente.
Come funziona IPN
Il flusso è semplice: ogni volta che un'evento (pagamento, rimborso, status update) avviene nell'account PayPal del merchant, PayPal invia una POST HTTP a un'URL configurato sul tuo server con una stringa form-encoded di variabili. Il tuo script deve rispedire il messaggio identico all'endpoint di verifica PayPal (https://ipnpb.paypal.com/cgi-bin/webscr) aggiungendo "cmd=_notify-validate". PayPal risponde "VERIFIED" o "INVALID". Solo i messaggi VERIFIED vanno processati.
Configurazione del listener
Per attivare IPN: accedi a Profilo, Strumenti del Venditore, Notifiche Pagamento Istantaneo. Inserisci l'URL HTTPS del tuo listener (no HTTP) e abilita IPN. L'URL deve essere accessibile da internet, rispondere in meno di 30 secondi e tornare HTTP 200 anche se la logica fallisce. PayPal riprova fino a 15 volte in 4 giorni con backoff esponenziale se non riceve risposta 200.
Procedura passo-passo
- Crea uno script HTTPS pubblico (es. https://miosito.it/paypal/ipn.php).
- Configura il file php.ini per accettare POST raw.
- Nel listener: leggi $_POST e costruisci la query string identica.
- Aggiungi cmd=_notify-validate e POST a https://ipnpb.paypal.com/cgi-bin/webscr.
- Verifica la risposta: solo "VERIFIED" autorizza il processing.
- Controlla che receiver_email coincida con la tua email PayPal.
- Controlla che payment_status sia "Completed".
- Verifica che txn_id non sia già stato processato (deduplicazione).
- Aggiorna l'ordine nel database e invia conferma al cliente.
- Rispondi HTTP 200 anche in caso di errore interno per evitare retry inutili.
Esempio di listener PHP minimale
Il listener deve fare quattro cose: ricostruire il payload originale (PayPal richiede l'ordine delle variabili identico), inviarlo a IPN con cURL e POSTFIELDS, leggere la risposta come stringa pura, processare solo se "VERIFIED". L'errore tipico è usare http_build_query che riordina alfabeticamente: bisogna invece iterare $_POST mantenendo l'ordine di arrivo. Usa header "Connection: Close" per evitare timeout.
Sicurezza e idempotenza
IPN non firma i messaggi: la sicurezza è basata sul callback di verifica. Tre controlli minimi: receiver_email = tua email (impedisce attaccanti che inviano IPN falsi), txn_id univoco (deduplicazione contro retry e replay), importo coincide con l'ordine atteso (impedisce manipolazione del prezzo). Salva l'IPN completo in tabella audit per debug e per dispute future.
Transizione verso webhook REST
PayPal raccomanda i webhook REST per le nuove integrazioni: payload JSON, firma HMAC-SHA256, eventi più granulari. IPN continuerà a essere supportato per chi lo ha già attivo, ma non avrà nuove funzionalità. Se stai partendo da zero scegli direttamente i webhook (vedi articolo dedicato). Se hai IPN attivo, valuta la migrazione progressiva mantenendo entrambi attivi nei primi mesi.
Errori comuni e come risolverli
- Endpoint HTTP invece di HTTPS: dal 2018 PayPal richiede TLS 1.2+. Configura un certificato valido.
- Ordine delle variabili modificato: usa file_get_contents("php://input") per ricostruire il payload originale.
- Mancato controllo receiver_email: attacchi di IPN injection diventano possibili.
- Risposta oltre 30 secondi: PayPal disabilita progressivamente l'IPN. Scarica processing pesante in coda.
- Nessuna idempotenza: i retry generano addebiti multipli al cliente. Salva txn_id già processati.
Domande frequenti
D: IPN funziona con la Sandbox?
R: Sì, l'endpoint sandbox è https://ipnpb.sandbox.paypal.com/cgi-bin/webscr.
D: IPN sostituisce la pagina di ritorno?
R: No, IPN è server-to-server. La pagina di ritorno (return URL) serve all'utente nel browser.
D: Quanti IPN ricevo per una transazione?
R: Almeno uno al completamento, ma possono arrivarne altri per refund, chargeback, reversal: ognuno ha txn_type diverso.
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.