Integrazione PagoPA nel Tuo Software: Guida Tecnica, Costi e Tempi (2026)

Integrare PagoPA in un software custom costa €8.000-25.000 di sviluppo, piu canone mensile di intermediario tecnologico (€500-2.500/mese) e commissioni PSP per transazione (€0,50-2,00 a carico cittadino o ente). Il tempo medio per andare in produzione e 6-14 settimane includendo la certificazione tecnica. Le tre strade possibili sono: adesione diretta come ente creditore, integrazione tramite intermediario tecnologico (PA Digitale, Maggioli, Engineering, Almaviva), oppure adozione di una piattaforma PagoPA-as-a-service (MyPay regionale, HelpDeskPA). Il custom ha senso quando il flusso pagamenti deve essere profondamente integrato con un gestionale gia esistente o quando si gestiscono piu enti con un'unica esperienza.

A cura di Pedro Corgnati - sviluppatore full-stack, fondatore di SystemForge. Nel 2025 ho integrato PagoPA via intermediario tecnologico per una casa di riposo accreditata in regione Emilia-Romagna; conosco i pain point della certificazione e della riconciliazione automatica.

Questo articolo ti spiega l'architettura PagoPA in 4 minuti, le tre strade possibili per integrare, lo stack tecnico raccomandato, i costi reali nel 2026 e gli errori che bloccano la certificazione. Per il quadro fiscale parallelo, vedi software contabilita e fatturazione elettronica SDI/IVA e quanto costa un software gestionale su misura.

Architettura PagoPA in 4 minuti

PagoPA non e un PSP. E un nodo dei pagamenti gestito da PagoPA SpA che orchestra il flusso fra Ente Creditore (chi deve incassare), cittadino (chi paga) e PSP (chi processa il pagamento - banca, Postepay, Satispay, MyBank).

I ruoli rilevanti sono tre.

Ente Creditore. L'ente pubblico, partecipata, concessionario di pubblico servizio o associazione accreditata che ha il diritto di incassare via PagoPA. Esempi tipici: comune, ASL, scuola convenzionata, casa di riposo accreditata, federazione sportiva, ordine professionale, multiutility regolata.

Intermediario Tecnologico. Il soggetto che gestisce tecnicamente la connessione al Nodo PagoPA. Puo essere lo stesso ente (adesione diretta) oppure un fornitore terzo accreditato (PA Digitale, Maggioli Tributi, Engineering Sardegna IT, Almaviva, Datagraph, Areagest). L'intermediario e responsabile dei messaggi al Nodo.

PSP (Prestatore di Servizi di Pagamento). Banca o operatore (Intesa, Unicredit, Postepay, Satispay, BPER, MyBank) che processa effettivamente il pagamento. PagoPA orchestra ma non incassa direttamente.

Il flusso end-to-end:

1. Il software dell'ente genera una posizione debitoria (esempio: rata casa di riposo, contributo iscrizione, multa).
2. L'intermediario tecnologico genera un avviso di pagamento con un IUV (Identificativo Univoco di Versamento) e codice avviso (numero di 18 cifre).
3. Il cittadino paga (online via app IO o portale dell'ente, oppure offline via Sisal/Lottomatica/banca).
4. Il PSP comunica al Nodo l'avvenuto pagamento.
5. Il Nodo invia una RT (Ricevuta Telematica) all'intermediario.
6. L'intermediario propaga la RT al software dell'ente che riconcilia con la posizione debitoria.

Esistono due modelli principali. Il modello 1 prevede avviso pre-generato (stampato o inviato via email/PEC al cittadino), il modello 3 prevede pagamento attivato dal cittadino su portale dell'ente con calcolo dell'importo in tempo reale. Molti enti usano entrambi.

Le tre strade per integrare

Strada 1 - Adesione diretta come ente. L'ente diventa direttamente intermediario tecnologico. Richiede certificazione tecnica con AgID/PagoPA SpA, ambiente di test, audit, mantenimento di SDK e firma elettronica. Costo iniziale alto (€18.000-25.000 di sviluppo + canone certificazione), ma azzera il fee dell'intermediario nel tempo. Conviene a enti grandi (sopra i 50.000 transazioni/anno) o gruppi di enti.

Strada 2 - Tramite intermediario tecnologico. L'ente sceglie un intermediario accreditato, firma il contratto, e il software custom dialoga con le API dell'intermediario. Setup molto piu rapido (6-10 settimane), nessuna certificazione AgID a carico dell'ente. Costo: €8.000-15.000 sviluppo + canone intermediario (€500-2.500/mese tipicamente). E la scelta corretta per il 90% dei progetti reali.

Strada 3 - Piattaforma PagoPA-as-a-service. MyPay regionale (Veneto, Trentino, Marche, Emilia-Romagna...), HelpDeskPA, Studio K. L'ente non sviluppa nulla, usa un portale gia pronto. Costo bassissimo (a volte gratuito per ente pubblico), ma zero personalizzazione UX e zero integrazione profonda con il gestionale esistente. Adatto solo per casi semplici.

Stack tecnico raccomandato per il custom (Strada 2)

Per scegliere l'intermediario in funzione del gestionale esistente, vedi integrare ERP SAP, TeamSystem, Zucchetti via API.

Backend. Java Spring Boot e l'opzione "ufficiale" (gli SDK PagoPA sono nati Java) ma non e obbligatorio. Node.js/Next.js o Python FastAPI funzionano benissimo se mappi correttamente i contratti REST/SOAP dell'intermediario. La scelta dipende dal team esistente.

Generazione IUV. Algoritmo specifico definito nelle Specifiche Attuative del Nodo. Lo IUV e composto da 17 cifre + carattere di controllo CCITT-4. Non e banale da implementare correttamente; conviene usare libreria standard dell'intermediario o ben validata.

Codice avviso. 18 cifre composto da: AUX (1 cifra) + applicationCode (2) + IUV (17). Il calcolo del check digit deve essere identico a quello atteso dal Nodo, altrimenti l'avviso non viene riconosciuto.

Gestione asincrona delle RT. Le RT possono arrivare istantaneamente o con ritardo (fino a giorni per pagamenti offline). Il sistema deve essere asincrono: webhook ricevuti dall'intermediario + polling fallback notturno per recuperare RT mancate.

Persistenza idempotente. Per dettagli sulla validazione delle firme webhook, vedi webhook sicuri - validazione firma e idempotenza. Database append-only per audit trail AgID. Mai aggiornare in-place una RT ricevuta - sempre nuova riga + flag "current". Fondamentale per ispezioni e per gestire il caso (raro ma reale) di RT duplicata o annullata.

Frontend. Next.js con due opzioni: redirect al checkout PagoPA (semplice, standard) o embed con WISP 2.0 (esperienza piu integrata, richiede certificazione UI). Il redirect copre il 90% dei casi.

Riconciliazione automatica

E qui che il custom paga davvero rispetto al "MyPay regionale".

Quando arriva una RT, il sistema deve:

1. Verificare la firma digitale (XML signed).
2. Estrarre IUV, importo, data pagamento, PSP, riferimento operazione.
3. Cercare la posizione debitoria corrispondente nel gestionale (matching per IUV).
4. Aggiornare lo stato della posizione (PAGATA, PAGATA PARZIALE, STORNATA).
5. Esportare il movimento contabile verso il gestionale (TeamSystem, Zucchetti, Adhoc PA, Sicraweb).
6. Notificare l'ufficio competente.
7. Salvare la RT in conservazione sostitutiva (10 anni).

Casi limite da gestire: pagamento parziale (raro ma possibile), storno (rimborso), pagamento doppio dello stesso IUV (l'utente ha pagato due volte per errore - RT duplicata, gestire rimborso), IUV scaduto pagato comunque.

Una pipeline di riconciliazione robusta richiede 3-5 settimane di sviluppo dedicate, oltre alla parte avvisi.

Costi reali 2026

Voce	Range
Sviluppo integrazione tramite intermediario	€8.000-15.000
Sviluppo adesione diretta + certificazione	€18.000-25.000
Canone intermediario tecnologico	€500-2.500/mese
Commissioni PSP per transazione	€0,50-2,00 (a carico cittadino o ente, configurabile)
Mantenimento + monitoraggio	€300-800/mese
Conservazione sostitutiva 10 anni	€0,02-0,08 per documento

I canoni intermediario variano molto per ente: PA Digitale e Maggioli partono da €500-800/mese per piccoli enti, salendo a €2.000-2.500 per multiutility. Engineering e Almaviva sono spesso piu cari ma con SLA enterprise.

Le commissioni PSP sono normate da PagoPA SpA e visibili pubblicamente nella tabella commissioni. Tipicamente vanno da €0,50 (carta a basso costo, MyBank) a €2,00 (carte premium, alcuni circuiti). L'ente sceglie chi paga: tutto a carico cittadino, tutto a carico ente, o split.

Hai dubbi se ti conviene andare in adesione diretta o tramite intermediario? Mandami su WhatsApp il tipo di ente, il volume annuo stimato di transazioni e il gestionale che usi: ti rispondo entro 24h con stima e raccomandazione. Scrivimi su WhatsApp oppure scopri il servizio di sistemi personalizzati.

Compliance: AgID, conservazione, accessibilita

Linee guida AgID per Enti. Le Specifiche Attuative del Nodo sono il documento normativo principale. Aggiornate periodicamente. Aggiornare il software ad ogni nuova versione del protocollo e parte del costo di mantenimento.

Conservazione sostitutiva 10 anni. Le RT e gli avvisi sono documenti fiscali a tutti gli effetti. Conservazione obbligatoria 10 anni con conservatore accreditato (Aruba, InfoCert, Namirial, Doc-eA). Costo €0,02-0,08 per documento conservato.

Accessibilita Legge Stanca + WCAG 2.1 AA. Obbligatoria per portali della PA. Richiede audit periodico (annuale) e dichiarazione di accessibilita pubblica. Per il portale di pagamento PagoPA custom serve attenzione particolare a: contrasti, navigazione tastiera, screen reader, alternative testuali per icone PSP.

GDPR su dati di pagamento. I dati dell'avviso (causale, importo, dati cittadino) sono trattati come dati personali. Base giuridica: obbligo legale (interesse pubblico). Retention limitata alla finalita contabile + obbligo conservazione 10 anni. DPIA consigliata per portali con grandi volumi.

Errori comuni che bloccano la certificazione

Codice avviso non conforme all'algoritmo CCITT-4. L'errore piu comune. Il check digit calcolato male significa avvisi rifiutati dal Nodo. Test: validare 1.000 avvisi generati contro libreria di riferimento PagoPA.

Mancata gestione del codice esito 9 (in attesa). Quando il PSP risponde "in attesa", il sistema deve aspettare la RT definitiva senza considerare il pagamento gia chiuso. Errori in questo stato generano riconciliazioni sbagliate.

RT duplicate non idempotenti. Il sistema riceve la stessa RT due volte (succede). Se non gestisce idempotenza, registra il pagamento due volte. Sempre check su IUV + transactionId prima di registrare.

Scadenza IUV mal calcolata. L'IUV ha scadenza configurabile. Avvisi scaduti possono comunque essere pagati (in alcune configurazioni). Gestire correttamente lo stato "scaduto" senza chiudere prematuramente la posizione.

Quando ha senso fare custom invece di MyPay regionale

Tre scenari concreti.

Multi-ente / multi-comune con esperienza unificata. Una unione di comuni o un consorzio che vuole portale unico per i cittadini. MyPay regionale frammenta l'esperienza, custom unifica.

Customizzazione UX cittadino oltre i template MyPay. Quando il portale di pagamento e parte dell'identita digitale dell'ente (esempio: portale studenti universita privata), serve controllo completo su UX e branding.

Integrazione profonda con CRM/gestionale esistente. Quando l'ente gestisce posizioni debitorie complesse (es. casa di riposo con rate variabili per ospite, servizi extra, anticipi) il custom riconcilia direttamente nel gestionale evitando esportazioni manuali.

Caso italiano concreto

Casa di riposo accreditata Emilia-Romagna - 280 ospiti, ~1.400 pagamenti/mese. Integrazione PagoPA via intermediario PA Digitale, software custom Next.js + Postgres che genera avvisi mensili automatici (rata fissa + servizi extra), invia via email/PEC ai familiari, riceve RT, riconcilia con gestionale Adhoc PA. Investimento €14.500 sviluppo + €850/mese intermediario. ROI in 11 mesi calcolato sul tempo amministrativo liberato (40 ore/mese di personale).

FAQ

Posso integrare PagoPA senza essere PA? Si, se sei concessionario di pubblico servizio, partecipata pubblica, ente accreditato, o associazione che svolge funzione di pubblica utilita riconosciuta. Esempi: scuole paritarie, case di riposo accreditate, federazioni sportive CONI, ordini professionali. Verifica con PagoPA SpA il diritto all'accreditamento prima di iniziare lo sviluppo.

Quanto tempo serve per la certificazione tecnica? Per adesione diretta: 8-16 settimane di certificazione AgID dopo lo sviluppo. Tramite intermediario: zero certificazione a carico dell'ente, l'intermediario e gia certificato.

Differenza commissioni PSP fra Postepay, carte, MyBank, satispay? Postepay e Satispay tipicamente €1,00-1,50. Carte di debito €0,80-1,20. Carte di credito €1,50-2,00. MyBank (bonifico immediato) €0,80-1,20. Le commissioni esatte sono pubblicate nella tabella commissioni PagoPA SpA aggiornata trimestralmente.

Come gestisco i pagamenti rateali? Generi piu IUV legati alla stessa posizione padre. Ogni rata ha avviso indipendente con scadenza propria. Riconciliazione tracciata a livello di posizione padre.

Posso usare la stessa integrazione per piu enti? Si, e una pratica comune. Devi definire correttamente nei messaggi al Nodo l'identificativo dell'ente creditore (CodiceFiscalePA). Un'unica istanza software puo servire decine di enti con configurazioni separate.

Cosa succede se cambio PSP? Tipicamente il PSP non viene "scelto" dall'ente in modo esclusivo: e PagoPA che presenta tutti i PSP disponibili al cittadino. Quello che cambia e il conto su cui arriva il bonifico finale (IBAN dell'ente). La modifica IBAN richiede comunicazione all'intermediario.

---

Stai pianificando un'integrazione PagoPA per un ente, una partecipata o un'associazione accreditata e vuoi una valutazione tecnica indipendente prima di scegliere intermediario? Scrivimi su WhatsApp - ti aiuto a capire qual e la strada giusta. Oppure scopri il servizio di sistemi personalizzati.