# 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)
