Migrare da PayPal NVP/SOAP a REST API
Le vecchie API NVP/SOAP di PayPal (Express Checkout API, MassPay, RecurringPayments) sono ancora supportate ma in maintenance: nessuna nuova funzionalità, comunicazioni di phase-out periodiche e crescente complessità di integrazione con strumenti moderni. La migrazione alle REST API è oggi consigliata a tutti i merchant che hanno integrazioni legacy attive. In questa guida vediamo come pianificarla.
Perché migrare
Quattro motivi pratici: SDK moderni (PHP, Node.js, Python, .NET) attivamente mantenuti solo per REST; JSON al posto di Name-Value-Pair (form-urlencoded) o XML SOAP; OAuth2 al posto di credenziali API "signature"; webhook firmati che sostituiscono il vecchio IPN. Le funzionalità nuove (Pay in 3, Apple Pay, Venmo) sono disponibili solo via REST. NVP/SOAP non sparirà a breve ma è già "in lettura": tutto il roadmap PayPal punta su REST.
Mapping delle operazioni principali
Tre conversioni fondamentali. SetExpressCheckout (NVP) → POST /v2/checkout/orders (REST): crea l'ordine con intent CAPTURE e purchase_units. DoExpressCheckoutPayment (NVP) → POST /v2/checkout/orders/{id}/capture (REST): cattura il pagamento approvato. RefundTransaction (NVP) → POST /v2/payments/captures/{id}/refund (REST). I parametri cambiano nome (PAYMENTREQUEST_0_AMT → amount.value) e il payload diventa JSON strutturato invece di flat key=value.
Autenticazione: da signature a OAuth2
NVP usa credenziali fisse: API Username, Password, Signature (o Certificate). Sono passate in ogni chiamata e non scadono. REST API usa OAuth2: il merchant ottiene un'access_token con client_credentials e lo include come Bearer token in ogni richiesta. Il token scade in ~9 ore. Implementa caching e refresh proattivo. Le credenziali OAuth2 (client_id, secret) sono generate creando un'app nel Developer Dashboard.
Procedura passo-passo
- Inventario delle integrazioni NVP/SOAP esistenti: quali endpoint, quali parametri.
- Crea app REST nel Developer Dashboard Sandbox e Live.
- Installa l'SDK REST per il tuo linguaggio (PayPal Server SDK).
- Implementa modulo OAuth2 con caching token (durata 8 ore).
- Mappa ogni operazione NVP alla corrispondente REST.
- Adatta i payload: da NVP flat a JSON strutturato.
- Sostituisci IPN con webhook REST firmati.
- Testa ogni flusso in Sandbox: ordine, cattura, refund, dispute.
- Esegui parallel running per 2-4 settimane: alcuni ordini con NVP, alcuni con REST.
- Migra il 100% del traffico a REST e monitora.
- Mantieni NVP attivo solo come fallback in lettura per consultare ordini storici.
Gestione dati storici
I transaction_id NVP e gli order_id REST sono formati diversi. Mantieni una tabella di mapping per gli ordini in essere (es. abbonamenti ricorrenti) prima della migrazione. Per refund di ordini NVP storici puoi continuare a usare l'endpoint legacy RefundTransaction anche dopo migrazione. Per nuovi pagamenti usa REST. Documenta chiaramente il cutoff date nel database (es. campo "payment_provider_version").
Differenze nei webhook
IPN invia form-encoded POST e richiede callback di verifica. Webhook REST invia JSON firmato con header HMAC e API di verifica firma. Cambia anche la struttura del payload: IPN ha campi flat (txn_id, payment_status, mc_gross), webhook REST ha JSON strutturato (resource.id, resource.amount.value, resource.status). I tipi di evento sono più granulari nei webhook (PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.REFUNDED separati).
Errori comuni e come risolverli
- Migrazione "big bang": rischio enorme. Fai parallel running graduale.
- Token OAuth2 ottenuto per ogni chiamata: latency moltiplicata. Usa caching.
- Mantenere webhook IPN + REST contemporaneamente: rischio di doppia elaborazione. Disabilita IPN dopo migrazione completa.
- Ignorare i webhook firmati: anche senza verifica funziona, ma sei vulnerabile a chiamate false.
Domande frequenti
D: Quanto tempo dura una migrazione tipica?
R: Per un'e-commerce medio, 2-6 settimane comprensive di test e parallel running.
D: PayPal cancellerà definitivamente NVP/SOAP?
R: Non c'è ancora una data, ma le funzionalità nuove sono già solo su REST.
D: Posso usare NVP per Refund di ordini vecchi e REST per i nuovi?
R: Sì, le due API coesistono e leggono dallo stesso account.
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.