TechReview 2025 - Evoluzione tecnica dei prodotti PagoPA
Un appuntamento speciale del ciclo DevTalks dedicato al racconto tecnico del 2025. L'evento si rivolge principalmente a sviluppatori, system integrator e figure tecniche coinvolte nell’integrazione dei prodotti di PagoPA.
Durante questa puntata raccoglieremo in un’unica sessione più team prodotto con l’obiettivo di condividere aggiornamenti rilevanti per chi integra e utilizza quotidianamente i servizi.
In particolare, mostreremo:

Ogni team proporrà un approfondimento tecnico seguito da Q&A, per favorire il confronto diretto con la community.
Ruggero Castagnola
Resp. SL PDND Interoperabilità Estensioni
Stefano Perazzolo
Resp. SL PDND Interoperabilità Core
Danilo Ciano
pagoPA - Software Engineer
Gianluca Ciuffa
pagoPA - Software Engineer
Pietro Tota
pagoPA - Software Engineer
Mario Gammaldi
SEND - Staff Engineer
Matteo Turra
SEND - Senior Technical Project Manager
[pagoPA] Come mai non è stata pensata in principio la waitingUrl?
Nella prima modellazione del servizio non era emersa questa esigenza, emersa successivamente
[pagoPA] Come mai avete gestito un versioning dell'API?
In ottica di avere una strict validation a livello di api: la nuova URL è un campo obbligatorio se usata la versione 2, al pari delle altre URL, considerando non valida una richiesta senza questo campo.
[pagoPA] Quando sarà disponibile la nuova versione della API?
Entro fine Maggio
[pagoPA] Si può continuare ad usare la V1 dell'API?
si, le due versioni coesisteranno con le transazioni innescate dalla versione 1 che continueranno a funzionare as-is, senza gestire ovviamente una waiting url
[pagoPA] E' necessario per l'ente implementare la pagina di waiting?
Non è obbligatorio ma fortemente suggerito: in questo modo l’esperienza utente sarà coerente fra quanto detto da Checkout e quanto detto sul portale dell’EC, per evitare fraintendimenti ed aiutare l’utente in queste casistiche
[pagoPA] Lato checkout è stato necessario implementare un breaking change per la nuova versione di questa API ?
No, Checkout non è cambiato. La stessa versione di Checkout supporta sia la versione 1 che la versione 2 delle api
[pagoPA] Avete in mente di predisporre un servizio per richiedere/scaricare una ricevuta formale del pagamento?
Attualmente viene generata una ricevuta nel momento in cui l’utente effettua il login su Checkout, ricevuta che viene inviata al cittadino su app IO.
Questa ricevuta, come riportato anche all’interno della stessa, attesta il pagamento effettuato su piattaforma pagoPA. NON si tratta di una quietanza liberatoria, la stessa rimane sotto responsabilità dell’Ente creditore nella parte di generazione e comunicazione al cittadino
[pagoPA] L'uso delle API di Checkout è libero (no adesioni, no autenticazione, no requisiti) e resterà tale?
Si, rimarrà tale anche per la versione 2 delle api
[pagoPA] c'è un tempo massimo per lo stato pending?
Dipende dal punto di “rottura” della transazione. Se non viene ricevuto outcome dell’autorizzazione il timeout è quello della durata del payment token, ovvero 15 minuti.
In caso di mancata chiusura del flusso lato Nodo/PSP il tempo massimo si potrebbe protrarre
[pagoPA] il carrello con alcune PA non funziona perché non consente il pagamento contemporaneo di più tributi, nonostante diretti allo stesso beneficiario. Questo comporta pagamenti di più transazioni a carico dell'utente
Il pagamento innescato da POST /carts gestisce fino a 5 avvisi per singola transazione, permettendo all’utente di pagare gli avvisi in un’unica transazione.
Non è supportato il pagamento parziale: se uno degli avvisi nel carrello non è pagabile (ad es. avviso non esistente o già pagato) allora l’intero carrello non sarà pagabile
[pagoPA] Nell'array di riepilogo dei dati del pagamento non è possibile fare in modo che compaiano i dati (causale, importo, ec) ricavati tramite la ""RPT response"" e non i dati passati dal payload di post/carta? (per motivi di sicurezza)
In fase di pagamento dell’avviso viene effettuata l’activatePaymentNotice verso il Nodo che causa, oltre l’attivazione della transazione, l’attualizzazione dell’importo dell’avviso di pagamento, che sarà oggetto del pagamento da parte del cittadino.
Per la parte di descrizione e companyName si potrebbe adottare lo stesso approccio, ovvero “attualizzare” descrizione e company name con quanto ricevuto in risposta sull’activate, sovrascrivendo i dati forniti in input.
Sarebbe utile, comunque, condividere, tramite gli appositi canali, i concern di sicurezza inerenti il fatto di usare i dati in input alla POST carts per indirizzare meglio le analisi
[pagoPA] Abbiamo notato che a seguito della singola creazione di posizione debitoria, chiamata messa a disposizione da un intermediario, il salto al checkout con i parametri corretti alcune volte genera errori, è possibile che vi sia una latenza?
In fase di atterraggio su Checkout viene effettuata una chiamata interna di check dei dati inseriti sul Nodo, pertanto se la posizione è stata creata pochi istanti prima di effettuare la chiamata verso Checkout potrebbe darsi che la stessa non risulti essere ancora “visibile”
[pagoPA] verranno condivisi i numeri di carta da utilizzare su uat per simulare tutti i vari casi ?
Si
[pagoPA] Anche la nuova url potrà contenere parametri in coda, come le precedenti?
Si, valgono le stesse considerazioni effettuate per le altre urls
[pagoPA] E' previsto un url per il donwload della ricevuta a seguito della conferma avvenuto pagamento, prova per l'integratore non per il cittadino?
No, non è previsto un URL per il download di ricevute per l’integratore.
Seguendo le SANP il flusso di pagamento si conclude con la paSendRT scatenata dal Nodo verso l’EC a valle della chiusura con successo del flusso di pagamento: con questa chiamata l’EC riceve ricevuta di avvenuto pagamento dell’avviso
[pagoPA] l'api per lo scarico dell'elenco delle ricevute sulla GPD https://api.platform.pagopa.it/gpd/payments-receipts-service/v1/payments fino al 26/03 accettava yyyy-MM-ddTHH:mm:ss mentre ora accetta solamente yyyy-MM-dd, sarà ripristinato?
Confermiamo che l'API 'GPD - Recupero receipt' supporta attualmente entrambi i formati. È possibile valorizzare i parametri from e to per la ricerca delle paSendRT sia utilizzando il formato yyyy-MM-dd sia quello esteso yyyy-MM-ddTHH:mm:ss.
Qualora si dovessero riscontrare errori di validazione utilizzando il formato con orario, invitiamo a fornire un esempio della request per permettere di effettuare ulteriori verifiche.
Cogliamo l’occasione per segnalare che le specifiche SANP-3.12.0 forniranno una documentazione più dettagliata di questi parametri.
[pagoPA] perché non predisporre un servizio rest apposito per il download della ricevuta (per esempio dal sito web dell'EC)?
ogni EC può generare quietanza di pagamento verso il cittadino alla ricezione della paSendRT da parte del Nodo
[pagoPA] Da Responsabile IT e formatore, chiedo un punto sullo stato dell'arte di pagoPA fra SANP tradizionali e GPD, fra modalità sincrona e asincrona: prospettive lato PagoPA spa e cosa conviene fare agli enti
Entrambe le modalità di integrazione pagoPA risultano pienamente supportate e attivamente mantenute; pertanto, non si configura una scelta obbligata in termini assoluti.
La valutazione comparativa tra le due modalità deve essere effettuata tenendo conto delle specifiche esigenze dell’Ente Creditore, con particolare riferimento al livello di controllo richiesto sulle posizioni debitorie, alla complessità dei processi amministrativi e allo stato evolutivo dei sistemi informativi interni.
In tale contesto, la modalità asincrona (GPD) presenta un evidente vantaggio operativo, in quanto la gestione delle posizioni debitorie, nell’ambito del flusso di pagamento, è demandata alla piattaforma pagoPA, con conseguente semplificazione degli adempimenti lato Ente e riduzione delle necessità di sviluppo e manutenzione di logiche applicative proprietarie.
Per contro, la modalità di integrazione sincrona risulta maggiormente adeguata nei casi in cui sia richiesto un più elevato livello di controllo diretto, ovvero nei contesti caratterizzati dalla presenza di sistemi legacy già strutturati e consolidati.
Non si rileva, pertanto, una soluzione univocamente preferibile, dovendosi piuttosto procedere a una valutazione caso per caso, in funzione del contesto organizzativo dell’Ente e degli obiettivi di evoluzione del relativo ecosistema informativo.
C'è un tempo massimo per lo stato pending?
Dipende dal punto di “rottura” della transazione. Se non viene ricevuto outcome dell’autorizzazione il timeout è quello della durata del payment token, ovvero 15 minuti.
In caso di mancata chiusura del flusso lato Nodo/PSP il tempo massimo si potrebbe protrarre
Flussi json pagoPA: anche l'API ""GPD - Recupero flussi di rendicontazione"" sarà deprecata (in quanto prevede lo scarico di flussi XML) ?
Alla data odierna, l’API “GPD - Recupero flussi di rendicontazione” risulta ancora disponibile e utilizzabile; tuttavia, ne è prevista la progressiva dismissione nell’ambito delle prossime evoluzioni delle SANP (3.12.0) di pagoPA.
Si raccomanda, pertanto, l’adozione del nuovo servizio “FdR - Flussi di Rendicontazione (ORGs)”, al fine di beneficiare dell’utilizzo di standard JSON e di una gestione più efficiente e scalabile dei flussi di rendicontazione, in particolare per volumi di grandi dimensioni.