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.

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: [email protected]