# Integrazione con Intermediari di pagamento PagoPA ## Cosa permette di fare la piattaforma con l’integrazione in questione La piattaforma consente la creazione di servizi digitali che prevedono l'associazione di uno o più pagamenti, gestiti in modo integrato con il sistema pagoPA o tramite registrazione manuale di marche da bollo. I pagamenti possono avvenire in due modalità: ### **Pagamento tramite marche da bollo** In questo caso non è prevista alcuna integrazione con sistemi esterni.\ Il cittadino registra i dati delle marche da bollo acquistate autonomamente (numero identificativo e data), a corredo della pratica che sta presentando. ### **Pagamento tramite circuito pagoPA** La piattaforma gestisce in modo integrato i pagamenti elettronici tramite l’infrastruttura pagoPA, attraverso l’interazione con uno degli intermediari accreditati. La creazione del pagamento avviene automaticamente durante l’invio della pratica o a seguito di un'azione dell’operatore, che può: * generare posizioni debitorie direttamente tramite configurazione della pratica; * **importare manualmente** pagamenti pendenti da sistemi esterni tramite file CSV, rendendoli disponibili al cittadino nell’Area Personale. L’integrazione consente quindi: * la creazione, la gestione e l’aggiornamento dei pagamenti; * la ricezione automatica delle notifiche di esito da parte del nodo pagoPA; * l’allineamento in tempo reale dello stato della pratica all'interno dell’Area Personale. > **Nota**: È attualmente in fase di sperimentazione l’introduzione della **Marca da Bollo Digitale**, che permetterà il pagamento del bollo direttamente tramite pagoPA, superando la modalità manuale tradizionale. ## **Benefici dell’integrazione** L’integrazione dei pagamenti nella piattaforma porta numerosi vantaggi operativi e strategici per gli enti: * **Automazione dei processi di incasso**:\ La generazione automatica delle posizioni debitorie e la ricezione dell’esito del pagamento riducono il carico di lavoro manuale per gli operatori. * **Migliore esperienza per il cittadino**:\ Il cittadino può completare i pagamenti online in autonomia, in un contesto centralizzato (Area Personale), senza dover interagire con sistemi esterni o recarsi fisicamente presso l’ente. * **Tracciabilità e trasparenza amministrativa**:\ Tutti i pagamenti vengono registrati con ID univoci, ricevute elettroniche e cronologia completa, garantendo sicurezza, conformità normativa e facilità di riconciliazione. ## Esempi di utilizzo dell’integrazione per i pagamenti Di seguito alcuni casi d’uso reali in cui l’integrazione dei pagamenti viene utilizzata all’interno della piattaforma: ### **Pagamenti pagoPA generati automaticamente dalla piattaforma** In questi scenari, la piattaforma crea autonomamente una posizione debitoria pagoPA in seguito a un’azione del cittadino o alla configurazione di un servizio digitale: #### **Domanda di occupazione suolo pubblico** Al termine della compilazione dell’istanza, un pagamento di €20 per i diritti di segreteria. Il cittadino può pagare direttamente dall’Area Personale.
### **Pagamenti pagoPA importati da file CSV** In alcuni casi, l’ente può caricare manualmente un file contenente posizioni debitorie provenienti da altri sistemi (es. tributi, multe, TARI): #### **Pagamenti Canone CUP** Il comune importa le posizioni già determinate nel gestionale tributi. Il cittadino visualizza e paga queste richieste direttamente dalla propria Area Personale.
### **Pagamento tramite marche da bollo cartacee** Alcuni servizi non richiedono l’integrazione con pagoPA, ma prevedono il pagamento tramite marche da bollo acquistate dal cittadino: #### **Istanza di residenza** Il modulo richiede l’inserimento del numero identificativo e della data di una marca da bollo da €16 acquistata autonomamente. Il cittadino la registra all’interno della pratica.
### **Visualizzazione di tutti i pagamenti in area personale** Per alcuni intermediari (in fase di sperimentazione) è possibile attivare la possibilità di scaricare tutti i dovuti di un cittadino quando questo fa login (anche quelli non creati dalla piattaforma). In questo modo troverà tutti i pagamenti che ha nei confronti dell'ente direttamente nella propria area personale, e potrà pagarli comodamente tramite il checkout pagoPA
## Processo di integrazione L’integrazione con il sistema di pagamento si sviluppa in diverse fasi operative. Di seguito una descrizione dettagliata del processo. ### **Fasi Principali** #### **Raccolta e validazione della documentazione e dell’ambiente di test** In questa fase iniziale viene contattato il fornitore dell’intermediario di pagamento per ottenere: * La **documentazione tecnica delle API**, contenente le specifiche delle operazioni fondamentali: * creazione del pagamento; * generazione dell’avviso cartaceo; * ottenimento del link per il pagamento online (checkout); * recupero dello stato del pagamento; * download della ricevuta telematica (RT). * Le informazioni sull’**ambiente di test**, in particolare: * l’URL del web service (WSDL per chiamate SOAP o documentazione Postman/Swagger per REST); * le **credenziali di accesso** e i **dati fittizi** da usare per i test (codici tipo dovuto, codice esercente, identificativi utente, ecc.). #### **Sviluppo dell’integrazione** Questa fase prevede lo sviluppo vero e proprio dell’integrazione, seguendo: * la documentazione fornita dall’intermediario; * la documentazione tecnica della piattaforma Opencity; * gli standard architetturali e funzionali adottati internamente. L’integrazione viene generalmente realizzata tramite un **proxy** che standardizza la comunicazione tra la piattaforma e l’intermediario. #### **Test dell’integrazione in ambiente di collaudo** Completato lo sviluppo, si procede alla validazione funzionale nell’ambiente di collaudo. I test previsti includono: * Test automatici delle API di configurazione del pagamento; * Test manuale della configurazione del pagamento tramite form (interfaccia admin); * Test di creazione del pagamento a partire da una pratica compilata da un cittadino; * Test del completamento del pagamento attraverso il checkout pagoPA; * Test di scaricamento della ricevuta telematica a pagamento avvenuto. * Test di importazione mediante file csv di un pagamento pendente creato esternamente alla piattaforma #### **Test dell’integrazione in ambiente di produzione** Una volta superata la fase di collaudo, si procede con il test in ambiente di produzione, **in collaborazione con un cliente pilota**. Questa fase è fondamentale perché: * emergono spesso **comportamenti specifici o difformità** rispetto all’ambiente di test; * si rilevano **dettagli contestuali** noti solo al cliente, che può accedere al **backoffice dell’intermediario** e fornire informazioni utili; * si verificano **disallineamenti tra test e produzione** dovuti a configurazioni, dati o logiche specifiche dell’ente. Prima di procedere, è necessario **concordare la tempistica e la modalità di test** con il cliente coinvolto. ### Criticità comuni nelle integrazioni di pagamento Durante lo sviluppo e la messa in produzione dell’integrazione con i sistemi di pagamento, possono emergere alcune criticità ricorrenti. Di seguito le principali: #### **Connettività in ambienti segregati (firewall, VPN, ecc.)** In alcuni casi, le API degli intermediari sono accessibili solo tramite VPN o da indirizzi IP autorizzati, sia in ambiente di test che in ambiente di produzione. Per usufruire delle API, è necessario comunicare al fornitore gli indirizzi IP fissi da autorizzare. Questo vincolo può essere particolarmente rilevante quando lo sviluppo dell’integrazione è affidato a un’azienda esterna. In questi casi si possono adottare due strategie: * **Configurare l’accesso alla VPN di Opencity Labs** per consentire lo sviluppo in modo controllato e sicuro. * **Richiedere lo sblocco dell’IP dell’azienda esterna** (se disponibile) da parte del fornitore dell’integrazione, insieme a quelli di Opencity Labs. #### **Documentazione tecnica errata o incompleta** La documentazione fornita dai fornitori del sistema di pagamento può presentare, in alcuni casi, ambiguità, imprecisioni o mancanze. Questo può ostacolare: * la corretta progettazione dell’integrazione; * lo sviluppo in ambiente di test; * la validazione finale in produzione. In presenza di dubbi o problemi tecnici, è fondamentale contattare tempestivamente il supporto tecnico del fornitore e fornire esempi concreti del comportamento anomalo riscontrato. #### **Ambiente di test instabile o non funzionante** Gli ambienti di test – sia del fornitore intermediario, sia di pagoPA – possono presentare frequenti disservizi. Le criticità più comuni si verificano nei seguenti punti del flusso: **1. Ambiente di test dell’intermediario di pagamento**\ I problemi più frequenti includono: * errori nella creazione del pagamento; * mancato download dell’avviso o della ricevuta telematica; * errori di aggiornamento dello stato del pagamento; * malfunzionamenti nel redirect verso il portale di pagamento. In questi casi è necessario contattare il supporto tecnico dell’intermediario, fornendo tutti i dettagli tecnici (endpoint, parametri inviati, timestamp, codice esercente, ecc.). **2. Ambiente di test di pagoPA**\ I problemi si manifestano generalmente **dopo il redirect** al portale pagoPA, in particolare: * nella schermata di inserimento dei dati della carta; * nel flusso di conferma o ricezione dell’esito. Per queste problematiche è necessario contattare **il supporto tecnico di pagoPA** via email all’indirizzo: [**pagamenti@assistenza.pagopa.it**](mailto:pagamenti@assistenza.pagopa.it) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazione-con-intermediari-di-pagamento-pagopa.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.