PayPal Mass Payment: API per pagamenti multipli
PayPal Mass Payment è il termine storico (legacy) per indicare l'invio massivo di pagamenti da un'account business a destinatari multipli. Oggi è stato sostituito dall'API REST "Payouts", ma molte integrazioni esistenti usano ancora la chiamata NVP MassPay. Vediamo le differenze, quando ha senso mantenere il flusso legacy e come strutturare correttamente le chiamate.
Mass Payment legacy: la chiamata NVP
L'endpoint legacy è https://api-3t.paypal.com/nvp con METHOD=MassPay. La richiesta usa form-urlencoded con parametri numerati: L_EMAIL0, L_AMT0, L_CURRENCYCODE0, L_NOTE0 per il primo destinatario, L_EMAIL1, L_AMT1 ecc per gli altri. Si possono inviare fino a 250 destinatari per chiamata. Le credenziali sono Username/Password/Signature dell'account business. La risposta torna ACK=Success con TRANSACTIONID per il batch.
Quando ha senso MassPay legacy
Solo per chi ha integrazioni esistenti funzionanti che non vuole rifattorizzare a breve. Per qualsiasi nuovo progetto usa Payouts REST: payload JSON, OAuth2, webhook, gestione UNCLAIMED migliorata, SDK moderni. MassPay non sparirà a breve ma è in maintenance. PayPal sconsiglia attivamente nuove integrazioni MassPay legacy dal 2020.
Differenze con Payouts REST
Tre differenze pratiche. Autenticazione: MassPay usa credenziali signature, Payouts usa OAuth2 access_token. Payload: MassPay flat key=value, Payouts JSON strutturato. Notifiche: MassPay solo IPN form-encoded, Payouts webhook REST firmati con eventi granulari (PAYMENT.PAYOUTS-ITEM.SUCCEEDED, PAYMENT.PAYOUTS-ITEM.FAILED). Stati: MassPay non distingue UNCLAIMED da FAILED; Payouts sì.
Procedura passo-passo (MassPay legacy)
- Configura le credenziali API NVP nel pannello business.
- Costruisci la stringa POST con USER, PWD, SIGNATURE, METHOD=MassPay, EMAILSUBJECT.
- Aggiungi i destinatari con indice progressivo: L_EMAIL0=user@example.com, L_AMT0=10.00, L_CURRENCYCODE0=EUR.
- POST a https://api-3t.paypal.com/nvp con header Content-Type form-urlencoded.
- Verifica ACK nella risposta: Success o Failure.
- Salva CORRELATIONID per log e debug.
- Configura listener IPN per ricevere notifiche di accettazione/rifiuto.
- Gestisci i pagamenti UNCLAIMED dopo 30 giorni.
Limiti e quote
Limiti operativi MassPay: max 250 destinatari per chiamata, max 100.000 USD per chiamata, max 1.000 chiamate al giorno per account. Per volumi superiori chiama PayPal per accordo custom. Le quote sono identiche su Payouts REST: il vincolo non è tecnologico ma legato alla compliance antiriciclaggio.
Errori più comuni in MassPay
Errore 11607: importo sotto il minimo (0,01). Errore 10001: insufficient funds. Errore 11609: troppi destinatari per batch (over 250). Errore 11610: limit reached per giorno. Errore 11611: receiver account closed. Gestisci ognuno con retry o segnalazione all'utente. Mantieni una tabella di errori-azione per automatizzare i retry sulle condizioni transitorie e fermare sui blocchi definitivi.
Migrazione MassPay → Payouts REST
Per migrare: implementa cliente OAuth2, prepara mapping campi (L_EMAIL → item.receiver, L_AMT → item.amount.value, L_CURRENCYCODE → item.amount.currency, L_NOTE → item.note), riscrivi listener IPN come webhook REST, testa in Sandbox con batch di 5-10 destinatari, poi aumenta. Tempo medio 2-3 settimane di lavoro per migrazione completa. Vantaggio principale: visibilità degli stati UNCLAIMED e gestione errori granulare.
Errori comuni e come risolverli
- Importo con virgola come decimale: PayPal accetta solo punto (es. 10.50, non 10,50).
- EMAILSUBJECT troppo lungo: massimo 255 caratteri.
- Mancata gestione idempotenza: senza identificatore univoco rischi doppio invio. Salva CORRELATIONID.
- IPN non configurato: non scopri mai gli UNCLAIMED. Configura URL listener.
Domande frequenti
D: MassPay e Payouts hanno la stessa commissione?
R: Sì, struttura tariffaria identica.
D: Posso usare entrambi sullo stesso account?
R: Sì, sono completamente compatibili.
D: Come migro senza interruzioni?
R: Parallel running per 30 giorni, poi switch finale a Payouts REST.
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.