GovPay

GovPay è una piattaforma open source (GPL v3), che implementa il protocollo di dialogo tra Enti, Intermediari o Partner Tecnologici con il Nodo dei Pagamementi del progetto pagoPA.

GovPay gestisce in autonomia la comunicazione con il Nodo dei Pagamenti, sollevando da questo compito gli applicativi verso i quali sono esposte apposite API di integrazione; nel contempo supporta la gestione dell’intero ciclo di vita della Posizione Debitoria e dell’Archivio dei Pagamenti in Attesa.

GovPay, in qualità di nodo accentratore dei flussi pagoPA dei domini gestiti, consente l’accesso agli operatori dell’ente per la configurazione e il monitoraggio tramite un cruscotto di gestione web-based.

GovPay supporta anche la fase di riconciliazione dei versamenti ricevuti dalla Banca Tesoriera con le pendenze che hanno originato i relativi pagamenti.

La documentazione di GovPay consente agli utenti di affrontare le diverse fasi del ciclo di vita del prodotto ed è suddivisa nelle seguenti sezioni:

• Un inquadramento generale del contesto di attuazione (Contesto)
• Il processo di installazione e dispiegamento del prodotto nell’ambiente dell’ente (Installazione)
• I passi per accedere al cruscotto grafico govpayConsole (Cruscotto)
• Le operazioni di configurazione del prodotto a carico degli amministratori del sistema (Configurazione)
• L’utilizzo del cruscotto di gestione per la gestione delle pendenze, monitoraggio e riconciliazione (Conduzione)
• La documentazione tecnica delle interfacce applicative (API) per l’integrazione dei sistemi verticali in adozione nell’ambiente tecnologico dell’ente (Integrazione)
• Una presentazione degli scenari tipici per l’utilizzo di GovPay (Scenari)
• Una raccolta di best practices per affrontare problematiche di utilizzo comuni (How-To)

Contesto

Il contesto in cui si colloca GovPay è quello della riscossione dei tributi da parte degli enti pubblici. Ciascun ente, che amministra nel proprio dominio applicativo le pendenze dei cittadini ed i relativi pagamenti, può avvalersi del servizio di mediazione offerto dal «Nodo SPC» per interagire con i PSP secondo una piattaforma paritetica e garantita da una governance pubblica.

In tale scenario ciascun ente deve predisporre l’ambiente tecnologico per far dialogare i propri sistemi, portale e sistema informativo per la gestione dei pagamenti, con il Nodo SPC.

GovPay: visione d’insieme

Come illustrato in VisioneInsieme_fig, lo scenario complessivo si compone dei seguenti attori/elementi:

• Soggetto Debitore (nel seguito “Cittadino”): L’utilizzatore finale della piattaforma di pagamenti
• Portale Pagamenti: applicazione web offerta al cittadino con le funzionalità necessarie alla consultazione o predisposizione della propria posizione debitoria.
• Gestionale Posizioni: applicazioni dell’ente che gestiscono le posizioni debitorie dei cittadini.
• Sistema Amministrativo Contabile: applicazioni dell’ente responsabili della riconciliazione delle riscossioni ricevute con i pagamenti di origine.
• GovPay: gestore del protocollo di colloquio con il Nodo dei Pagamenti.
• GovPay Console: applicazione web per la configurazione e il monitoraggio dell’operatività di GovPay.
• PSP: Prestatore di Servizi di Pagamento, soggetto abilitato alla riscossione dei pagamenti ed emissione di relativa ricevuta elettronica aderente alla piattaforma pagoPA.
• pagoPA - Nodo SPC: la piattaforma AgID che intermedia i PSP.
• pagoPA - WISP: il portale pagoPA che consente al debitore di selezionare il PSP per procedere con un pagamento.

Installazione

Questo manuale fornisce le informazioni generali e la procedura necessaria per l’installazione e il dispiegamento di GovPay. Tale procedura prevede una fase preliminare di verifica dei requisiti di installazione sull’ambiente di destinazione, seguita da una fase di configurazione dei moduli applicativi tramite un installer grafico, per poi concludere con la fase di deploy nell’ambiente di destinazione.

Terminata la procedura di installazione vengono descritti i passi da effettuare per verificarne la riuscita.

Ambiente e architettura di riferimento

L’ambiente di esecuzione di GovPay richiede la presenza di software di base, precedentemente installato i cui riferimenti sono:

• JVM Oracle Java 8
• Application Server WildFly 11

Relativamente alla versione di RDBMS, l’attuale versione di GovPay consente di selezionare tra i seguenti:

• PostgreSQL 8.x o superiore
• MySQL 5.6.4 o superiore
• Oracle 10g o superiore

Configurazione dei moduli applicativi

La fase di configurazione dei moduli applicativi consente di impostare i dati di riferimento del proprio ambiente di installazione, tramite una procedura basata sul modello wizard.

Download

Scaricare l’ultima versione (binary release) di GovPay dal sito GitHub https://github.com/link-it/GovPay.

Esecuzione dell’Installer

L’archivio di installazione può essere scompattato e il relativo installer eseguito su un ambiente che non deve essere necessariamente quello di destinazione. Infatti l’Installer non installa il prodotto ma produce tutti gli elementi necessari che dovranno essere dispiegati nell’ambiente di esercizio.

Per l’esecuzione dell’installer verificare ed eventualmente impostare la variabile d’ambiente JAVA_HOME in modo che riferisca la directory radice dell’installazione di Java. Eseguire quindi l’installer mandando in esecuzione il file install.sh su Unix/Linux, oppure install.cmd su Windows.

Avvio

L’Installer mostra all’avvio una pagina introduttiva.

Sono mostrate informazioni quali:

• Nome e versione del prodotto
• Informazioni sul copyright
• Informazioni sulla licenza d’uso

Selezionando il pulsante Next si procede con la configurazione del software.

Pagina introduttiva all’avvio dell’Installer

Informazioni Preliminari

La schermata «Informazioni Preliminari» consente di inserire i dati sul contesto di installazione nell’ambiente di esercizio.

Informazioni preliminari

Devono essere inserite le seguenti informazioni:

• Application Server: la scelta dell’application server è vincolata su «WildFly 11.0»**
• Work Folder: inserire il path assoluto della directory, presente nell’ambiente di destinazione, che sarà utilizzata da GovPay per accedere a dati accessori legati alle funzionalità opzionali, ad esempio: - file di configurazione personalizzati - loghi dei psp
• Log Folder: inserire il path assoluto della directory, presente nell’ambiente di destinazione, che sarà utilizzata da GovPay per inserire i diversi file di tracciamento prodotti.

Informazioni Applicative

• Username Amministratore: indicare l’identificativo dell’utenza di amministrazione per l’accesso alla console di gestione e monitoraggio. Tipicamente si fornisce il «principal» dell’utenza applicativa registrata sull’Application Server, ma è in alternativa possibile indicare altre tipologie di utenze, come ad esempio identificate dal Certificato Client Digitale.
• Nome Dominio: inserire l’hostname tramite il quale saranno raggiungibili i servizi di GovPay (ad esempio la console di monitoraggio).

Informazioni applicative

Il Database

Nella schermata «Il Database» si devono inserire i riferimenti per l’accesso al database di esercizio di GovPay.

Informazioni accesso al DB

• DB Platform: selezionare la piattaforma RDBMS utilizzata
• Hostname: indirizzo per raggiungere il database
• Porta: la porta da associare all’hostname per la connessione al database
• Nome Database: il nome dell’istanza del database a supporto di GovPay.
• Username: l’utente con diritti di lettura/scrittura sul database sopra indicato.
• Password: la password dell’utente del database.

Nota

Non è necessario che il database e l’utente indicato esistano in questa fase. Potranno essere creati nella successiva fase di dispiegamento purché i dati relativi coincidano con i valori inseriti in questi campi del wizard.

Installazione

Premendo il pulsante Install il processo di configurazione termina con la produzione dei files necessari per l’installazione di GovPay che verranno inseriti nella nuova directory dist creata al termine di questo processo.

Installazione terminata

I files presenti nella directory dist dovranno essere utilizzati nella fase successiva di dispiegamento di GovPay.

Fase di Dispiegamento

Al termine dell’esecuzione dell’utility di installazione vengono prodotti i files necessari per effettuare il dispiegamento nell’ambiente di esercizio. Tali files sono disponibili nella directory dist prodotta dall’utility.

Per il dispiegamento nell’ambiente di destinazione devono essere effettuati i seguenti passi:

1. Creare un utente sul RDBMS avente i medesimi valori di username e password indicati in fase di setup.
2. Creare un database, per ospitare le tabelle dell’applicazione, avente il nome indicato durante la fase di setup. Il charset da utilizzare è UTF-8.
3. Impostare i permessi di accesso in modo che l’utente creato al passo 1 abbia i diritti di lettura/scrittura sul database creato al passo 2.
4. Garantire la raggiungibilità dell’application server al RDBMS indicato in fase di setup.
5. Eseguire lo script sql/gov_pay.sql per la creazione dello schema del database. Ad esempio, nel caso di PostgreSQL, si potrà eseguire il comando:
   • psql -h <hostname> -d <database> -U <username> -f sql/gov_pay.sql
6. In riferimento al valore indicato come «Username Amministratore», creare l’utenza applicativa sull’application server che rappresenti l’amministratore di GovPay. Per farlo è possibile utilizzare lo script presente nella distribuzione di WildFly in ./bin/add-user.sh o ./bin/add-user.bat, fornendo i seguenti parametri:
   • Type of user: indicare b) Application User
   • Realm: lasciare il valore di default
   • Username: utenza amministratore di GovPay indicata durante l’esecuzione dell’Installer (es. Gpadmin)
   • Password: password associata all’utenza
   • Roles: lasciare il valore di default
   • Group: lasciare il valore di default
   • Is this new user going to be used for one AS process to connect to another AS process?: Indicare “no”.
7. Copiare il file datasource/govpay-ds.xml, contenente la definizione del datasource, nella directory <JBOSS_HOME>/standalone/deployments dell’application server.
8. Copiare le applicazioni presenti nella directory archivi nella directory <JBOSS_HOME>/standalone/deployments dell’application server.
9. Installare il DriverJDBC, relativo al tipo di RDBMS indicato in fase di setup, nella directory <JBOSS_HOME>/standalone/deployments dell’application server.
10. Editare i datasources installati al punto 7. sostituendo la keyword NOME_DRIVER_JDBC.jar con il nome del file corrispondente al driver jdbc.
11. Verificare che la directory di lavoro e quella di log di GovPay, inserite in fase di configurazione, esistano o altrimenti crearle con permessi tali da consentire la scrittura all’utente di esecuzione del processo java dell’application server.
12. Avviare l’application server (ad esempio su Linux con il comando <JBOSS_HOME>/bin/standalone.sh oppure utilizzando il relativo service).

Verifica dell’Installazione

Per la fase di verifica dell’installazione, effettuare i seguenti passi:

1. Avviare l’application server
2. Al termine della fase di avvio, sono riscontrabili i seguenti contesti dispiegati, suddivisi tra servizi di frontend (rivolti all’utente finale) e servizi di backend (rivolti all’utenza interna):

2.1 Frontend:

• /govpay/frontend/web/connector

  web application per la gestione delle redirezioni durante i flussi di pagamento

• /govpay/frontend/api/pagamento

  api per l’esecuzione dei pagamenti da parte del debitore

• /govpay/frontend/api/pagopa

  api per la gestione del colloquio con la piattaforma centrale pagoPA

2.2 Backend:

• /govpay/backend/api/pendenze

  api per la gestione dell’archivio dei pagamenti in attesa (pendenze, pagamenti, ecc.)

• /govpay/backend/api/ragioneria

  api relative ai servizi di riconciliazione degli incassi con le pendenze/pagamenti di origine

• /govpay/backend/api/backoffice

  api relative ai servizi di configurazione della piattaforma (domini, applicazioni, operatori, ecc.)

• /govpay/backend/gui/backoffice

  web application che corrisponde al cruscotto di gestione e monitoraggio di GovPay

3. Verificare che i servizi esposti da GovPay verso pagoPA siano raggiungibili verificando sul browser le seguenti URL:

• http://<hostname>:<port>/govpay/frontend/api/pagopa/PagamentiTelematiciCCPservice?wsdl
• http://<hostname>:<port>/govpay/frontend/api/pagopa/PagamentiTelematiciRTservice?wsdl

4. Verificare che la govpayConsole, l’applicazione web per la gestione della configurazione e monitoraggio di GovPay, sia accessibile tramite browser all’indirizzo:

   • http://<hostname>:<port>/govpay/backend/gui/backoffice

   In caso di corretto funzionamento verrà visualizzata la pagina di autenticazione per l’accesso alla console.

5. Accedere alla govpayConsole usando l’utenza di jboss configurata in fase di dispiegamento.

   L’utenza creata in precedenza ha accesso a tutte le funzionalità compresa la gestione degli utenti. Utilizzando questo accesso potranno quindi essere registrati dei nuovi utenti.

6. Completata l’installazione di GovPay, per proseguire con l’utilizzo del sistema si rimanda al “Manuale Utente”.

Configurazione in Load Balancing

Per realizzare un’installazione in load balancing è necessario predisporre più istanze dell’Application Server, ognuna con una propria installazione di GovPay. Sarà inoltre necessario:

1. Che tutte le istanze di GovPay siano configurate per condividere lo stesso DB.
2. Che esista un Load Balancer in grado di bilanciare il flusso di richieste in arrivo sulle varie istanze di application server ospitanti GovPay.
3. Che GovPay sia opportunamente configurato con un identificatore unico che contraddistingua lo specifico nodo.

Le proprietà per la configurazione del singolo nodo sono le seguenti:

• it.govpay.clusterId: identificativo dell’istanza di GovPay. Deve essere un numero univoco tra le istanze.
• it.govpay.timeoutBatch: timeout in secondi delle operazioni soggette alla gestione applicativa della concorrenza. Se non valorizzato viene usato il default di 5 minuti.

Queste proprietà possono essere specificate sia nelle Java Options, dei processi Java associati agli application server, oppure nel file govpay.properties nella directory di lavoro di ogni nodo.

Ad esempio è possibile ridefinire la directory di log impostando la seguente proprietà:

• it.govpay.resource.log.path

Servizi di Monitoraggio

Per consentire l’integrazione con i sistemi di monitoraggio, GovPay mette a disposizione servizi interrogabili per verificare il funzionamento del sistema.

I servizi di monitoraggio sono di due tipi:

• Monitoraggio Domini

  per verificare l’esito delle ultime comunicazioni con il Nodo dei Pagamenti, relativamente ad uno specifico dominio.

• Monitoraggio GovPay

  per verificare il funzionamento delle singole componenti del prodotto.

Monitoraggio domini

Viene esposto un servizio di monitoraggio per dominio che fornisce indicazioni di stato inerenti l’esito delle interazioni con il Nodo dei Pagamenti. Il servizio si interroga con la seguente chiamata HTTP:

GET /govpay/frontend/api/pagopa/rs/check/{id_dominio} HTTP/1.1

Accept: application/json

in ritorno si ha un messaggio con questo formato:

{

«ultimo_aggiornamento»:null,

«codice_stato»:1,

«operazione_eseguita»:null,

«errore_rilevato»:»STATO NON VERIFICATO»

}

con la seguente semantica:

ultimo_aggiornamento	Data dell’ultimo aggiornamento dello stato
codice_stato	0: ok 1: stato non verificato 2: fail
operazione_eseguita	Operazione richiesta al nodo che ha aggiornato lo stato
errore_rilevato	Dettaglio dell’errore riscontrato

Monitoraggio GovPay

Sono implementati dei check sui servizi gestiti da GovPay per verificarne il corretto funzionamento. Lo stato dei check è consultabile tramite servizi REST.

GET /govpay/frontend/api/pagopa/rs/check/sonda/

Il servizio restituisce una panoramica dei check attivi sul sistema e del loro stato attuale. Per ciascuno è possibile acquisirne il dettaglio:

GET /govpay/frontend/api/pagopa/rs/check/sonda/{nome}

dove nome può assumere i seguenti valori:

update-psp	Check del servizio di aggiornamento PSP
update-rnd	Check del servizio di acquisizione flussi rendicontazione
update-pnd	Check del servizio di risoluzione pagamenti pendenti
update-ntfy	Check del servizio di spedizione notifiche
update-conto	Check del servizio di generazione estratti conto
check-ntfy	Check della coda di notifiche da spedire

in ritorno si ha un messaggio con questo formato:

{

«nome»:»check-ntfy»,

«stato»:0,

«descrizioneStato»:null,

«durataStato»:null,

«sogliaWarn»:»Numero di elementi accodati: 10»,

«sogliaError»:»Numero di elementi accodati: 100»,

«sogliaWarnValue»:10,

«sogliaErrorValue»:100,

«dataUltimoCheck»:1489673880116,

«tipo»:»Coda»

}

con la seguente semantica:

Nome	Identificativo della check
stato	null: stato non verificato 0: ok 1: warning 2: error
descrizioneStato	Descrizione informativa sullo stato assunto dal check
durataStato	Tempo in millisecondi in cui il check e” nello stato attuale
sogliaWarn	Soglia di Warning in forma descrittiva
sogliaError	Soglia di Error in forma descrittiva
sogliaWarnValue	Valore di soglia per lo stato di warning. La semantica del valore dipende dal tipo di check:
sogliaError	Come sogliaWarnValue ma per lo stato di error
dataUltimoCheck	Data dell’ultima verifica del check
tipo	Tipologia di check:

Cruscotto

Una volta completata con successo la procedura di installazione sarà possibile procedere con la configurazione accedendo al Cruscotto di Gestione al seguente indirizzo:

http://<hostname>:<port>/backend/gui/backoffice

Dove al posto dei placeholder <hostname> e <port> dovranno essere inseriti i riferimenti al proprio ambiente di installazione (nome host o indirizzo IP e relativa porta).

Sono disponibili le seguenti funzionalità informative, liberamente consultabili prima dell’autenticazione:

• Manuale Utente, che permette di accedere alla versione più recente di questo manuale in formato liberamente
• Progetto GovPay, che illustra le caratteristiche salienti del prodotto e le sue novità

Per l’accesso al cruscotto viene presentata la maschera per l’immissione delle credenziali. Si noti come ad ogni utente sia associato un ruolo che rappresenta l’insieme delle funzionalità che sono destinate all’utente stesso. Questo meccanismo, che verrà maggiormente dettagliato in seguito, permette di ritagliare in modo assolutamente generico il giusto profilo funzionale per tutte le classi di utente abilitati all’uso della piattaforma.

Immissione delle credenziali [1]

[1]	Ovviamente le credenziali evidenziate in figura sono a puro scopo esemplificativo

I metodi di autenticazione al sistema sono:

• Username / password
• SPID

Si noti che il sistema abilita l’accesso tramite SPID se l’Ente ha effettuato tutti i necessari passi per accreditarsi all’uso di SPID stesso (certificazioni, test e via dicendo).

Dopo aver effettuato l’accesso con le credenziali in proprio possesso, si accede a tutte le funzionalità descritte nelle corrispondenti sezioni di questo documento. La schermata dovrebbe presentarsi in questo modo [2]

[2]	Si tenga sempre presente che la propria schermata dipende dai ruoli cui si è associati

Schermata iniziale

Menu di navigazione

La colonna posta sinistra nell’interfaccia rappresenta il menu di navigazione, con le relative voci che variano in funzione dei ruoli associati all’utenza autenticata.

Cruscotto iniziale [3]

[3]	Si noti come le funzionalità evidenziate corrispondono a un ruolo particolare: l’utente che si autentica, a seconda dei ruoli cui è associato, potrà vedere tutte o parte delle funzionalità in figura

L’area iniziale (primo box in alto a sinistra) mette a disposizione informazioni sul profilo e permette di effettuare il logut dalla piattaforma.

Funzionalità di profilo

Si faccia riferimento alle evidenziazioni in rosso: da sinistra verso destra abbiamo: * Identificativo dell’utente appena autenticatosi * Dettaglio profilo Utente * Logout per permettere l’uscita dal sistema

Si tenga presente che, come regola generale, se si è indecisi sulla funzionalità associata a un pulsante, basta stazionarci sopra con il puntatore del mouse per avere una descrizione sintetica della funzionalità cui esso è associato. Cliccando su profilo utente abbiamo, sul riquadro di destra, il dettaglio dell’utente con le autorizzazioni sulle funzionalità che gli sono state concesse. Ad esempio avremmo:

Dettaglio del profilo (esempio)

A seguire sono elencate le sezioni del menu di navigazione, che possono variare in base alle autorizzazioni possedute dall’utente che ha effettuato l’accesso. Le sezioni del menu sono:

• Cruscotto: sezione iniziale che evidenzia in modo immediato la situazione generale di pagamenti e pendenze.
• Pagamenti: sezione di consultazione delle operazioni di pagamento effettuate dai debitori.
• Pendenze: sezione di consultazione delle pendenze di pagamento in carico ai debitori.
• Giornale degli eventi: sezione di consultazione del Giornale Eventi previsto dalla specifica pagoPA.
• Configurazioni: raccoglie gli strumenti per la consultazione, censimento e modifica delle entità alla base della configurazione del prodotto (Psp, Domini, Tributi, Applicazioni, ecc.).
• Funzioni Avanzate: sezione dedicata alla consultazione di entità avanzate (rendicontazioni, riscossioni, ecc.).
• Manutenzione: Accesso a funzionalità di manutenzione straordinaria.

Ad esempio, per l’utente che si è autenticato nel nostro caso esemplificativo (gpadmin) avremo la seguente lista funzionalità:

Lista funzionalità (esempio)

A ciascuna di queste funzionalità verrà dedicata una sezione di dettaglio esplicativo.

Configurazione

La configurazione di Govpay è quella attività, visibile solo agli amministratori del sistema, che consente il censimento e la manutenzione delle entità logiche (operatori, ruoli, domini, abilitazioni e quant’altro) coinvolte nel processo di pagamento.

Le attività di configurazione vengono svolte tramite un’apposita sezione del cruscotto grafico Cruscotto e sono necessarie alla messa in funzione dell’applicativo. La lista degli oggetti che è possibile configurare comprende i seguenti elementi:

• Intermediari: rappresentano le entità “Intermediario” o “Partner Tecnologico” censiti presso il Nodo dei Pagamenti scelti in fase di adesione dagli Enti Creditore per l’accesso al sistema pagoPA.
• Enti Creditori: corrispondono agli enti creditori aderenti al sistema pagoPA.
• Tipi Pendenza: rappresentano le esigenze dell’ente creditore dalle quali scaturiscono le tipologie di pagamenti che possono essere gestiti dal sistema (ad esempiotassa rifiuti, licenza di caccia, bollo auto e via dicendo).
• Applicazioni: rappresentano i portali di pagamento e i gestionali delle posizioni debitorie degli enti Creditori integrati con GovPay tramite gli appositi servizi.
• Operatori: sono le utenze del cruscotto di gestione GovPay.
• Ruoli: rappresentano l’insieme delle autorizzazioni consentite sulle entità dati, da assegnarsi agli utenti del cruscotto.

Nota

Nell’analisi delle funzionalità di configurazione, le immagini esemplificative mostrate mancheranno della sezione di sinistra (Lista funzionalità) al fine di agevolare la focalizzazione sulla parte important della funzionalità, ovvero il suo dettaglio posto a destra.

Intermediari

Gli intermediari o partner tecnologici sono entità censite da AgID sul circuito pagoPA al momento dell’adesione di un Ente Creditore. Per il corretto funzionamento di GovPay, gli intermediari di interesse devono essere censiti con le informazioni di corredo necessarie.

Vista di dettaglio intermediari

Accedendo alla sezione corrispondente (Configurazioni > Intermediari), viene visualizzato l’elenco degli intermediari censiti sul sistema. È possibile filtrare gli intermediari in relazione al loro stato, impostandolo nella casella di selezione posta a sinistra, come di seguito mostrato:

Filtro su ricerca Intermediari

Nuovo Intermediario

Per inserire un nuovo intermediario è necessario premere l’apposito pulsante, presente nella pagina di elenco in basso a destra, e compilare il form che viene aperto:

Informazioni che definiscono un nuovo intermediario

Le informazioni contenute nel form sono le seguenti:

Dettagli di un nuovo intermediario

Campo	Significato	Note
Denominazione	Nome associato all’Intermediario o al Partner Tecnologico	Obbligatorio
Id Intermediario	Identificativo dell’intermediario o Partner Tecnologico, fornito da AgID, corrisponde alla Partita IVA del soggetto	Obbligatorio
Principal	identificativo (subject certificato o principal) corrispondente alle credenziali con cui Govpay riceve le chiamate in entrata da pagoPA
Abilitato/Non Abilitato	Stato del nuovo intermediario: indica se l’intermediario è usabile da GovPay per gestire nuovi pagamenti o se impedire nuove richieste.
Servizio RPT	Riferimenti utilizzati da Govpay per comunicare con il Nodo SPC: Endpoint per le chiamate in uscita verso il Nodo SPC
Tipo Autenticazione	Lista a discesa per selezionare il tipo di autenticazione adottata per le comunicazioni con il Nodo SPC. Si può scegliere, al momento, tra Nessuna e HTTP-Basic. Nel caso si scelga quest’ultima modalità di autenticazione, dovranno essere inserite i relativi dati di configurazione (userid/password)

Selezionando un intermediario dalla pagina che li elenca si accede alla pagina di dettaglio.

Dettaglio Intermediario

La pagina di dettaglio di un intermediario mostra i singoli campi che lo compongono unitamente all’elenco delle stazioni ad esso associate. Infatti, al censimento di un Intermediario o Partner Tecnologico, AgID assegna anche una o più Stazioni Tecnologiche che devono essere registrate su GovPay.

Pulsante di modifica

Il pulsante di modifica presente nella pagina consente di aprire il form per modificare le proprietà dell’intermediario.

Stazioni

Nella pagina di dettaglio dell’intermediario (quindi una volta che lo si è creato) esiste una sezione dedicata alle stazioni in cui è possibile aggiungerne di nuove:

Pulsante di aggiunta stazione (evidenziato in rosso)

Si ottiene così il seguente risultato:

Maschera di inserimento di una nuova stazione

Per definire una stazione connessa all’intermediario occorre immettere le seguenti informazioni:

Dettagli di una nuova stazione

Campo	Significato	Note
IdStazione	Identificativo della stazione, fornito da AgID	Obbligatorio
Password	Chiave segreta, fornita da AgID	Obbligatorio
Abilitato	indica se la stazione è usabile da GovPay per gestire nuovi pagamenti (abilitato) o se si vogliono impedire nuove richieste (disabilitato)

Nota

Si noti come le stazioni siano connesse univocamente a ciascun intermediario, non è quindi possibile avere una stessa stazione connessa a due intermediari

È possibile visualizzare il dettaglio di una stazione selezionandola dall’elenco, avendo il dettaglio dei campi appena visti.

In corrispondenza di ciascuna stazione in elenco si evidenzia il pulsante per la modifica delle informazioni:

Modifica di una stazione esistente

I dati modificabili della stazione saranno la sola password e lo stato; l’identificativo non sarà modificabile:

Maschera di modifica di una stazione

Una volta terminata la modifica è necessaria la pressione della voce Salva per renderla effettiva.

Enti Creditori

Ogni Ente Creditore su pagoPA va registrato nell’anagrafica di GovPay.

Accedendo alla sezione Configurazioni > Enti Creditori, viene visualizzato l’elenco degli enti già censiti. Sul lato sinistro è presente il form per filtrare i domini visualizzati in elenco, con i possibili parametri di ricerca, ovvero:

Parametri di filtro per la ricerca di un Ente Creditore

Ciascun Ente Creditore presente in elenco è identificato tramite denominazione e codice identificativo.

Nuovo Ente Creditore

Utilizzando il pulsante di creazione, presente in basso a destra nella pagina di elenco, è possibile procedere con la creazione di un nuovo Ente Creditore, compilando il seguente form di creazione:

Campi del form di inserimento Nuovo Ente Creditore

Dettagli di un Nuovo Ente Creditore

Campo	Significato	Note
Id Dominio	Identificativo del dominio, fornito da AgID, corrisponde alla Partita Iva dell’ente	Obbligatorio
Ragione Sociale	Ragione sociale del dominio	Obbligatorio
Area	Identificativo interno dell’Area
GLN (Global Location Number)	Identificativo del dominio nella codifica standard GS1. Obbligatorio, fornito da AgIDD
Intermediario	Intermediario selezionato	Obbligatorio
Stazione	Stazione tecnologica scelta in fase di adesione a pagoPA, deve ovviamente essere stata già censita sul sistema	Obbligatorio
Riferimenti anagrafici del Dominio	Riferimenti anagrafici del dominio forniti dal Referente dei Pagamenti: Indirizzo (Indirizzo completo di toponimo), Numero Civico, CAP, Località, Provincia, Nazione (condice di due lettere, IT per Itaia), eMail, PEC, Sito web, Telefono, Fax
CBILL	Codice CBILL per i domini che supportano questa modalità di pagamento, attribuito da PagoPA
Prefisso IUV	Prefisso da inserire negli IUV generati da GovPay per questo dominio. Il prefisso, numerico, può contenere dei placeholder racchiusi tra graffe
Aux	Valore numerico che definisce la struttura del codice IUV in funzione del numero di punti di generazione dello stesso (cfr. Specifiche Attuative dei codici identificativi di versamento, riversamento e rendicontazione)
Codice di segregazione	Se configurato come dominio pluri-intermediato, imposta il codice numerico di segregazione.	Fornito da AgID
Abilitato	Indica se il dominio è usabile da GovPay per gestire nuovi pagamenti (abilitato) o se si vogliono impedire nuove richieste (disabilitato)
Autorizzazione stampa PT	Numero di autorizzazione PT per la stampa in proprio del bollettino postale
Sfoglia.. (Logo)	Elemento per il caricamento del logo dell’ente creditore corrispondente al dominio

I placeholder contenuti nel prefisso IUV vengono sostituiti a runtime con i valori forniti dagli applicativi richiedenti o con i valori di sistema configurati. La lunghezza del prefisso riduce lo spazio di IUV generabili, quindi è necessario che sia il più breve possibile. I seguenti sono i placeholder di sistema, sovrascrivibili dall’applicazione chiamante:

• a: codice IUV assegnato all’applicazione che gestisce il debito
• t: codice IUV assegnato al tributo
• y: anno di emissione dello IUV, due cifre
• Y: anno di emissione dello IUV, quattro cifre

Dettaglio Ente Creditore

Selezionando uno degli enti creditori presenti nella pagina di elenco si accede alla pagina di dettaglio, che si compone a partire dalle seguenti aree:

Aree del dettaglio Ente Creditore

Area	Descrizione
Riepilogo Informazioni	Dati che caratterizzano l’ente creditore, appena visti nella sezione Nuovo Ente Creditore
Unità Operative	Uffici di gestione dei pagamenti in cui è suddiviso il dominio dell’ente creditore.
Iban	Codici IBAN dei conti correnti su cui l’ente creditore riceve gli accrediti in banca tesoriera. Tali IBAN sono quelli già comunicati ad AgID in fase di accreditamento.
Entrate	Sono le entrate attive nel dominio dell’ente creditore e quindi sulle quali è predisposto per ricevere dei pagamenti.
Pendenze	Sono le entrate attive nel dominio dell’ente creditore e quindi sulle quali è predisposto per ricevere dei pagamenti.

Tramite il pulsante di modifica presente nella pagina di dettaglio è possibile procedere con l’aggiornamento dei dati di base, visualizzati nell’area «Riepilogo Informazioni». Si tenga presente che il valore del campo “Codice Dominio” non è modificabile.

Campi del dettaglio dell’Ente Creditore

Le aree seguenti contengono i relativi pulsanti di creazione e modifica dei rispettivi elementi, con le solite, naturali, uniformi convenzioni grafiche.

Campi degli oggetti correlati all’Ente Creditore

Unità Operative

La specifica pagoPA consente di indicare l’anagrafica dell’Unità operativa titolare del credito, qualora sia diversa da quella dell’Ente Creditore. È quindi possibile censire le Unità operative del Dominio in GovPay al fine di utilizzarle in fase di pagamento.

Campi per creare una Nuova Unità Operativa

Dettagli di una nuova Unità Operativa

Campo	Significato	Note
Id unità	Codice identificativo, ad uso interno, dell’unità operativa	Obbligatorio
Ragione Sociale	Ragione sociale dell’Unità Operativa	Obbligatorio
Sezione Anagrafica	Riferimenti anagrafici dell’unità forniti dal Referente dei Pagamenti
Abilitato	Indica se l’unità operativa è abilitata o meno nel contesto del dominio su cui si opera

Ovviamente dall’elenco delle unità operative associate a un Ente Creditore, è possibile modificarne le informazioni associate.

Iban

Gli iban utilizzati per l’accredito degli importi versati vanno censiti su GovPay. Esiste quindi una maschera di definizione degli IBAN associati all’Ente Creditore.

Maschera di creazione IBAN associato all’Ente Creditore

Il form di creazione di un Iban deve essere compilato con i dati seguenti:

Dettagli di un nuovo IBAN

Campo	Significato	Note
IBAN Accredito	Codice IBAN del conto di accredito	Obbligatorio, fornito dal referente dei Pagamenti
BIC Accredito	BIC del conto di accredito	Obbligatorio
Postale	Indica se l’iban di accredito è riferito ad un conto corrente postale
My Bank	Indica se l’iban di accredito è è abilitato alle transazioni MyBank
Abilitato	Indica se l’IBAN è abilitato o meno nel contesto del dominio su cui si opera

Tornando all’elenco degli Iban, è possibile scegliere le operazioni di modifica degli elementi precedentemente creati. Il campo Iban Accredito non è, ovviamente, modificabile.

Entrate

Ogni importo che costituisce un versamento deve essere associato ad una entrata censita sul sistema. L’entrata associata al versamento ne determina l’iban di accredito dell’importo e le coordinate di rendicontazione.

Nota

Si noti come la gestione delle Entrate sia stata sostituita da quella delle Pendenze, assai più flessibile e con in più la possibilità di generazione automatica delle interfacce per la riscossione: ciò semplifica grandemente l’implementazione effettiva di queste modalità di pagamento verso l’Utente finale, fornendogli al contempo un’interfaccia omogenea e consistente. Si decide di lasciare questa tipologia di oggetti per meri scopi di ereditarietà. Le nuove configurazioni dovrebbero pertanto utilizzare la Gestione delle Pendenze.

Maschera di creazione nuova entrata associata all’Ente Creditore

Il form di creazione di un’entrata va compilato con le seguenti informazioni:

Dettagli di una nuova entrata

Campo	Significato	Note
Tipo entrata	Selezione tra le tipologie già censite	Se non risulta presente la voce desiderata, selezionare Nuova Entrata Id Entrata: identificativo dell’entrata. Descrizione: testo di descrizione dell’entrata per facilitarne il riconoscimento agli operatori. Obbligatorio, a discrezione dell’operatore. Tipo Contabilità: tipologia di codifica contabile assegnata all’entrata (SIOPE/SPECIALE/…). Obbligatorio, fornito dalla segreteria. Codice Contabilità: codice contabilità assegnato all’entrata secondo la codifica indicata precedentemente. Obbligatorio, fornito dalla segreteria. Codifica IUV: codifica dell’entrata nel contesto degli IUV generati da GovPay, se configurato in tal senso.
IBAN Accredito	IBAN di accredito del tributo a scelta tra quelli censiti per il dominio	Obbligatorio
IBAN Appoggio	utilizzato nelle situazioni in cui il PSP non è in condizioni di accreditare somme sul conto di accredito (si considerino le limitazioni in essere nel circuito postale)
Tipo contabilità	Se valorizzato sovrascive l’mpostazione prevista nel default per l’entrata cui si fa riferimento
Codice contabilità	Se valorizzato sovrascive l’mpostazione prevista nel default per l’entrata cui si fa riferimento
Abilitato	Indica se l’Entrata è abilitata o meno nel contesto del dominio su cui si opera

Nota

I campi Tipo Contabilità e Codice Contabilità rappresentano i valori di default per il tipo entrata e saranno attualizzabili nel contesto di ciascun Ente Creditore.

Dalla lista delle Entrate rimane sempre possibile modificare la singola Entrata, con il campo Codice Entrata non modificabile. Fa eccezione l’entrata preconfigurata “Marca da Bollo Telematica” per la quale si ha la sola possibilità di modificare i parametri di contabilizzazione.

Pendenze

Questa sezione permette la scelta e la personalizzazione delle pendenze (ovvero oggetti che vanno riconciliati con i pagamenti) ammissibili per l’Ente Creditore in essere. Si noti come le pendenze possano essere associate all’Ente selezionandole da quelle censite (l’aggiunta di un nuovo tipo di pendenza viene gestita nella funzionalità associata alla voce Tipi Pendenze del menu sulla sinistra). Il sistema, ovviamente, permette di aggiungere solo le pendenze che, per l’Ente, non siano state già scelte. Ad esempio, in un Ente Creditore abbiamo le seguenti tipologie di pendenza già selezionate:

Pendenze associate a un Ente Creditore

A questo punto, sull’Ente Creditore selezionato, si potrà aggiungere una sola pendenza (quella non ancora selezionata), come mostrato:

Pendenza selezionabile per aggiunta all’Ente Creditore

Il sistema dà la possibilità, una volta aggiunta una nuova pendenza, di personalizzarla per l’Ente Creditore, consentendo anche la generazione di maschere automatiche per l’immissione dei dati. Si tenga presente che si affronterà il dettaglio dei campi delle pendenze nella sezione apposita, cui si fa riferimento. Al momento si noti come una pendenza possa essere completamente personalizzata per un dominio a partire da una standard definita nella sezione `Tipi Pendenze`_. I meccanismi di selezione sono del tutto analoghi a quanto già visto in altri contesti del sistema: selezioniamo la Pendenza Sanzione Amministrativa

Selezione della Pendenza Sanzione Amministrativa

Il sistema mostra la seguente maschera

Modifica Sanzione Amministrativa

Da qui possiamo personalizzare senza modificare le informazioni standard del tipo Sanzione Amministrativa.

Tipi Pendenze

Ogni importo che costituisce un versamento deve essere associato ad una pendenza censita sul sistema. La configurazione di questo oggetto determina quindi le coordinate di pagamento e quelle di rendicontazione. Si noti come le pendenze siano associate a un dominio, determinando quindi il tipo di pagamenti che ad esso fanno riferimento. La gestione dei tipi di pendenza permette la generazione di maschere automatiche per l’immissione dei dati, semplificando in modo notevole lo sviluppo di interfacce e ottimizzando i tempi generali di progetto. Le modalità per la creazione di una nuova pendenza sono sempre le medesime (tasto più in basso a destra) e la maschera presentata è la seguente:

Maschera di creazione di una Nuova Pendenza

Vediamo come modificare una pendenza esistente; ciò ci permetterà di illustrare il dettaglio dei campi presenti. Selezioniamo, ad esempio, la Pendenza Sanzione Amministrativa.

Selezione della Pendenza Sanzione Amministrativa

Il sistema mostra la seguente maschera

Modifica del tipo pendenza Sanzione Amministrativa

Possiamo identificare i seguenti raggruppamenti di informazioni:

• Riepilogo Informazioni
• Layout form dati
• Elaborazione
• Promemoria avviso pagamento
• Promemoria ricevuta telematica

A ciascuno di essi è dedicata una sezione di dettaglio, come segue.

Riepilogo Informazioni

La sottosezione si presenta nel seguente modo:

Sezione Riepilogo Informazioni

Campi modificabili della prima sezione

Campo	Significato	Note
Descrizione	Descrizione sintetica del tipo di pendenza
Id Tipo Pendenza	Codice tecnico che indica in modo univoco la pendenza	Non modificabile
Tipologia	Tipo di pendenza: dovuta o spontanea
Codifica IUV	Identificatore della struttura del codice IUV
Abilitato	Indica se la Sanzione Amministrativa sia abilitata o meno, quindi sia o meno associabile a domini esistenti
Pagabile da terzi	Indica se la sanzione possa o meno essere pagata non dal debitore

Layout form dati

Sezione form della Sanzione Amministrativa

Campi modificabili della sezione Layout Form dati

Campo	Significato	Note
Tipo layout	Indica il motore di interpretazione della descrizione formale della maschera di immissione del pagamento da parte del debitore	Al momento solo Angular Json schema form
Definizione	Mostra il menu di caricamento e visualizzazione della descrizione formale dell’interfaccia di pagamento

Funzionalità selezionabili per la definizione form

Sono presenti le voci:

• Carica: carica un nuovo file di definizione del form
• Visualizza: visualizza la definizione del form
• Ripristina: ripristina la definizione originaria del form

Vediamo un esempio di un file di definizione dell’interfaccia:

Funzionalità selezionabili per la definizione form

Elaborazione

La sezione Elaborazione consente a GovPay di descrivere in modo formale come elaborare quanto immesso nella sezione Layout Form Dati al fine di trasformare e inoltrare le informazioni del pagamento alle applicazioni (anche esterne) che ne abbisognino. Si pensi a uno scenario in cui, ad esempio, sia necessario informare un sistema di recupero crediti del fatto che una pendenza abbia superato la data di scadenza.

Funzionalità della sezione Elaborazione

Dettagli della sezione Elaborazione

Campo	Significato	Note
Validazione	Selezione delle funzionalità sulla definizione della validazione in formato Json Schema	Carica Visualizza Ripristina
Trasformazione: tipo template	Motore di trasformazione delle informazioni immesse nel Form Dati	Freemarker
Trasformazione: Template	Template di defizione della trasformazione dati	Carica Visualizza Ripristina
Inoltro	Consente di selezionare l’applicazione cui verranno inoltrati i dati	L’applicazione deve essere censita nella sezione Applicazioni

Promemoria Avviso Pagamento

La sezione Avviso di pagamento permette l’inoltro automatico verso la mail del debitore dell’avviso di pagamento. La tipologia di definizione del subject e del corpo della mail è, al momento, basata su Freemarker

Informazioni della sezione Promemoria Avviso Pagamento

Dettagli della sezione Promemoria Avviso Pagamento

Campo	Significato	Note
Tipo template	Motore di trasformazione delle informazioni immesse nel template oggetto e messaggio della mail di Avviso Pagamento	Freemarker
Template Oggetto	Template di defizione dell’oggetto della mail di Avviso Pagamento	Carica Visualizza Ripristina
Template Messaggio	Template di defizione del messaggio della mail di Avviso Pagamento	Carica Visualizza Ripristina
Allega pdf avviso	Permette di allegare o meno il pdf dell’avviso di pagamento alla mail di promemoria

Promemoria Ricevuta Telematica

La sezione Promemoria Ricevuta Telematica è del tutto analoga a quella relativa all” Avviso di pagamento: essa permette l’inoltro automatico verso la mail del debitore della ricevuta telematica dell’avvenuto pagamento. Anche in questo caso la tipologia di definizione formale del oggetto e del corpo della mail è, al momento, basata su Freemarker

Informazioni della sezione Promemoria Ricevuta Telematica

Dettagli della sezione Promemoria Ricevuta Telematica

Campo	Significato	Note
Tipo template	Motore di trasformazione delle informazioni immesse nel template oggetto e messaggio della mail di Ricevuta Telematica	Freemarker
Template Oggetto	Template di defizione dell’oggetto della mail di Ricevuta Telematica	Carica Visualizza Ripristina
Template Messaggio	Template di defizione del messaggio della mail di Ricevuta Telematica	Carica Visualizza Ripristina
Allega pdf avviso	Permette di allegare o meno il pdf della Ricevuta Telematica

Esempio di scenario di utilizzo

Come esempio di scenario di utilizzo possiamo cercare di mappare, sui componenti presentati, un semplice processo reale: si supponga di gestire, infatti, il pagamento spontaneo di dieci buoni pasto elettronici con relativo inoltro della codifica elettronica univoca, previo pagamento andato a buon fine, al richiedente.

Gestione buoni pasto elettronici

#	Oggetto della pendenza	Passo di processo
1	Layout form dati	Definizione form in cui si chiede il numero di buoni pasto richiesti
2	Elaborazione.Validazione	Gestione delle soglie (es. massimo 20 buoni pasti a richiesta)
3	Elaborazione.Trasformazione	Creazione della pendenza correlata al numero di buoni mensa effettivamente richiesti (es. determinazione del costo finale, con le varie franchigie, aggravi amministrativi e via dicendo)
4	Elaborazione.Applicazione	Interfacciamento con l’applicazione verticale che crea i codici relativi ai buoni mensa richiesti

E” di tutta evidenza come questo non sia che uno dei molteplici processi che sono formalmente definibili, quindi implementabili direttamente, con i meccanismi appena visti, da GovPay.

Applicazioni

Le Applicazioni in GovPay rappresentano i portali di pagamento e i sistemi applicativi gestionali dei debiti che si interfacciano tramite le Web API di integrazione. Accedendo alla sezione Configurazioni > Applicazioni, viene visualizzato l’elenco delle applicazioni già censite. Sul lato sinistro della pagina è presente un form che consente di filtrare i dati visualizzati nella pagina, come di seguito mostrato:

Vista generale delle applicazioni censite e criterio di filtro

Nuova Applicazione

Per aggiungere una nuova applicazione, premere il pulsante posizionato, come sempre, in basso a destra. Analizzeremo questa funzionalità che è del tutto analoga, dal punto di vista delle informazioni richieste, a quella della modifica di un’applicazione già censita nel sistema.

Vista generale dei campi di una nuova applicazione

Analizziamo le sottosezioni in cui è strutturata l’applicazione, ovvero: * Informazioni di riepilogo * Codifica avvisi * API integrazione * Autorizzazioni API * Autorizzazioni Backoffice

Informazioni di riepilogo

In questa sottosezione sono contenute le informazioni che definiscono un’applicazione in tutti i suoi aspetti di interazione con il sistema dei pagamenti.

Informazioni di riepilogo di un’applicazione

Dettagli della sezione Informazioni di riepilogo di una nuova Applicazione

Campo	Significato	Note
Id A2A	identificativo dell’applicazione	Obbligatorio
Principal	Identificativo del principal autenticato nelle chiamate alle Web API di integrazione
Abilitato	se disabilitato, tutte le nuove richieste all’applicazione saranno negate

Codifica avvisi

In questa sottosezione sono contenute le informazioni che definiscono un’applicazione in tutti i suoi aspetti di interazione con il sistema dei pagamenti.

Sezione Codifica Avvisi di un’applicazione

Dettagli della sezione Codifica avvisi di una nuova Applicazione

Campo	Significato	Note
Codifica IUV	Numero identificativo dell’applicazione nel prefisso IUV, se configurato
RegEx IUV	Espressione regolare che consente di effettuare la validazione dei codici IUV inviati dall’applicazione	es. 99[0-9]*
Generazione IUV interna	Se il flag è attivo l’applicazione genera autonomamente i codici IUV relativi alle proprie pendenze, altrimenti detti codici saranno generati da GovPay

API Integrazione

In questa sottosezione sono contenute le informazioni che definiscono un’applicazione in tutti i suoi aspetti di interazione con il sistema dei pagamenti.

Sezione API Integrazione di un’applicazione

Dettagli della sezione API Integrazione di una nuova Applicazione

Campo	Significato	Note
API Integrazione	Endpoint del servizio del verticale che viene integrato da GovPay
Versione API	Versione delle interfacce di integrazione utilizzate dall’applicazione
Tipo Autenticazione	selezione a scelta tra: Nessuna, Http-Basic e SSL	In base al valore selezionato sarà necessario inserire i conseguenti dati di configurazione della specifica modalità di autenticazione

Autorizzazioni

In questa sezione il sistema permette di autorizzare:

• Specifici (o tutti) Enti Creditori all’utilizzo dell’applicazione
• Specifici (o tutti) Tipi Pendenze ad essere elaborate attraverso l’applicazione
• Specifici Ruoli all’utilizzo dell’applicazione

Inoltre in questa sottosezione è possibile definire se l’applicazione è in grado oppure no di interfacciarsi con le tre API (Pagamenti, Pendenze e Ragioneria) messe a disposizione da GovPay.

Sezione Autorizzazioni di un’applicazione

Dettaglio Applicazione

Selezionando una delle applicazioni presenti nella pagina di elenco si accede alla pagina di dettaglio, che permette di vedere i dati di sintesi dell’applicazione:

Vista di sintesi di un’applicazione

Con l’uso delle solite metafore (matita su cerchio verde) è possibile accedere alle modifiche puntuali della definizione dell’applicazione. In tale processo le informazioni rimangono esattamente quelle appena viste per la definizione di una nuova applicazione.

Operatori

Gli operatori rappresentano gli utenti autorizzati all’accesso al cruscotto di gestione di GovPay. Accedendo alla sezione Configurazioni > Operatori, il sistema visualizza l’elenco degli operatori già censiti. Sul lato sinistro della pagina è presente un form che consente di filtrare gli operatori in relazione al proprio stato. Gli elementi nell’elenco identificano gli operatori presenti visualizzando i campi principal e nome.

Nuovo Operatore

Tramite il pulsante presente nella pagina di elenco è possibile aprire il form di creazione di un operatore:

Definizione di un nuovo Operatore

Informazioni di dettaglio di un nuovo Operatore

Campo	Significato	Note
Principal	Identificativo dell’operatore dato da PagoPa	Obbligatorio
Nome	Nome e cognome dell’operatore	Obbligatorio
Abilitato	Indica se l’operatore ha o meno l’accesso al Cruscotto di gestione
Domini	Indica i domini su cui può svolgere compiti l’Operatore	E” presente l’opzione Tutti che permette a una sola utenza di operare trasversalmente a più domini
Tipi pendenza	Selezione delle pendenze su cui l’operatore può operare	Presente l’opzione Tutti
Ruoli	Ruoli cui l’utente è abilitato: ogni ruolo ha un perimetro autorizzativo che l’operatore eredita

Dettaglio Operatore

Dalla pagina elenco degli operatori, selezionando uno degli elementi, si giunge alla relativa pagina con le informazioni di sintesi.

Vista di sintesi di un Operatore

Da quest’ultima è possibile, con l’uso delle solite metafore (matita su cerchio verde in basso a destra), accedere alle modifiche puntuali della definizione di un operatore. In tale processo le informazioni rimangono esattamente quelle appena viste per la definizione di una nuova applicazione, con una sola informazione non modificabile, ovvero principal.

Ruoli

I ruoli rappresentano una delle modalità con cui assegnare le autorizzazioni a operatori e applicazioni. I ruoli vengono acquisiti da GovPay tramite il profilo utente ottenuto dal sistema che gestisce il processo di autenticazione. Dopo aver effettuato l’accesso a GovPay, l’operatore o applicazione ottiene le autorizzazioni che gli sono state concesse puntualmente (vedi sezioni 7.3.2.3 e 7.4.2.3) in aggiunta a quelle associate ai ruoli posseduti.

La sezione Configurazioni > Ruoli mostra l’elenco dei ruoli già presenti nel sistema.

Vista iniziale dei ruoli censiti

Nuovo Ruolo

Utilizzando l’apposito pulsante presente nella pagina di elenco, è possibile creare un nuovo ruolo:

Definizione di un Nuovo Ruolo

Informazioni di dettaglio di un nuovo Ruolo

Campo	Significato	Note
Identificativo	Identificativo assegnato al ruolo	Obbligatorio
Lista risorse	Lista delle risorse su cui il ruolo ha accesso in Lettura o Scrittura

Dettaglio Ruolo

In modo del tutto analogo a quanto visto con le altre entità, selezionando un elemento dall’elenco dei ruoli si accede al suo dettaglio. Quest’ultimo è modificabile semplicemente premendo la matita in basso a destra.

Conduzione

Al termine delle fasi di installazione e configurazione del prodotto si passa all’utilizzo effettivo nell’ambito del processo alla base del ciclo di vita dei pagamenti. Le attività supportate per la fase di conduzione comprendono le operazioni di manutenzione delle entità presenti nell’archivio dei pagamenti unitamente agli strumenti per il monitoraggio dei relativi flussi in transito.

Pendenze

Questa sezione è dedicata alla consultazione delle pendenze di pagamento presenti nel repository dei pagamenti in attesa. Le pendenze sono abilitate al modello di pagamento 3 tramite Avviso di pagamento AgID.

Gli stati della Pendenza

Si noti come, all’interno del sistema, il diagramma di stato delle pendenze sia il seguente:

Diagramma degli stati della Pendenza

Si noti come si arrivi a e si parta da lo stato annullata solo a seguito di azioni dell’operatore.

Stati della pendenza

Stato	Descrizione	Note
Da pagare	Stato iniziale della pendenza
Pagata	Stato che indica il regolare pagamento della pendenza
Riconciliata	Stato che indica il completamento del processo di riconciliazione della pendenza con la somma incassata
Annullata	Stato assegnato alla pendenza dopo che ne è stato richiesto l’annullamento

Area iniziale

Area iniziale delle Pendenze

L’area iniziale è composta dai seguenti elementi:

• Sulla sinistra è presente il form per impostare i criteri di filtro sulle pendenze su cui si intende agire.
• Sulla destra è presente l’elenco delle pendenze che corrispondono ai criteri di filtro impostati, con un insieme sommario di dati. Oltre al titolo, troviamo la codifica IUV, l’importo complessivo, lo stato e la data.

Dopo aver effettuato una ricerca è possibile ottenere un CSV di esportazione relativo all’elenco delle pendenze che soddisfano i criteri di ricerca forniti. L’esportazione dell’elenco si effettua selezionando il collegamento Scarica Resoconto che compare sul menu a discesa in alto a destra, come mostrato in figura:

Scarica csv delle pendenze trovate

I campi del csv (compresso in formato zip) sono i seguenti:

• Identificativo univoco della pendenza
• Identificativo del dominio
• Denominazione del dominio
• Numero di avviso
• Importo
• Data del caricamento della pendenza
• Data di validità della pendenza
• Tipo di avviso
• Stato della pendenza

Selezionando uno degli elementi presenti in elenco si procede alla visualizzazione del dettaglio della pendenza, abilitando l’eventuale modifica.

Dettaglio Pendenza

La pagina di dettaglio fornisce una vista delle singole informazioni che compongono la pendenza stessa.

Dettaglio della pendenza

In testa, sulla destra, è presente un menu a discesa che consente, nel caso si possiedano le necessarie autorizzazioni, di effettuare le seguenti operazioni:

• Annulla/Ripristina Pendenza

  Se la pendenza si trova in uno stato diverso da «Eseguito» è possibile effettuare l’annullamento facendola transitare nello stato «Annullato». All’atto dell’annullamento viene richiesto di fornire un testo di motivazione dell’operazione che verrà visualizzato nella pagina di elenco e veicolato ai PSP nel caso ne venisse tentato il pagamento. Successivamente è possibile tornare indietro tramite l’operazione «Ripristina» che consente di far transitare la pendenza nello stato «Non Eseguito». Anche nel caso del ripristino è possibile opzionalmente inserire un testo di descrizione della motivazione.

• Scarica resoconto

  Consente di scaricare un archivio in formato ZIP che contiene i documenti che compongono la pendenza, quali:

  • Documento PDF con i dati della pendenza (IUV, scadenza, importo), il dettaglio delle voci di pagamento presenti e le eventuali segnalazioni.
  • RPT e relative RT generate per la pendenza in formato XML.
  • Le versioni PDF delle RT.
  • Documento CSV contenente gli eventi scaturiti dagli scambi con pagoPA.
  • Avviso di Pagamento in PDF se previsto dalla pendenza.

La presentazione dei dati di dettaglio della pendenza è articolata in tre differenti sezioni raggiungibili selezionando altrettanti schede:

• Dati Pendenza
• Tentativi di Pagamento
• Eventi

Nel seguito si dettagliano i gruppi informativi appena elencati.

Dati Pendenza

Dati pendenza

La pagina riporta nella sezione Riepilogo i dati principali che compongono la pendenza (ente creditore, debitore, IUV, scadenza, importo, stato, …). Il valore assunto dallo stato è un elemento importante che consente ad esempio, in fase di ricerca, di selezionare le sole pendenze che non risultino pagate.

La sezione Dettaglio Importi fornisce l’elenco delle singole voci di pagamento contenute nella pendenza (titolo, importo, stato).

La sezione Note riporta le eventuali segnalazioni associate alla pendenza che sono state rilevate dal sistema durante il suo ciclo di vita. Il sistema consente di inserire nuove note con la solita modalità (click sul tasto più)

Tentativi di Pagamento

Questa sezione mostra i dati relativi alle transazioni di pagamento che sono state effettuate per pagare la pendenza (la banca, la data, l’importo, l’esito). Il clic su ciascun elemento in elenco comporta un’espansione con la visualizzazione di ulteriori dati di dettaglio, se disponibili.

Tentativi di pagamento di una data pendenza

Eventi

Questa sezione mostra l’elenco degli eventi, presenti nel Giornale degli Eventi, previsto dalla specifica pagoPA, che sono scaturiti nel corso del ciclo di vita della pendenza che si sta consultando. Maggiori dettagli su questi elementi sono riportati nella sezione 6, dove è descritta la funzionalità di consultazione generale del Giornale degli Eventi.

Pagamenti

La sezione «Pagamenti» è dedicata alla consultazione delle operazioni di pagamento che sono state richieste a Govpay in seguito all’interazione tra l’utente pagatore e il portale dei servizi di pagamento dell’ente creditore.

Gli stati del Pagamento

Si noti come, all’interno del sistema, il diagramma di stato dei pagamenti sia il seguente:

Diagramma degli stati del Pagamento

In particolare:

• Lo stato rifiutato si verifica quando un pagamento è stato richiesto a GovPay ma non è stato autorizzato su PagoPa
• Lo stato decorso si verifica quando AgID

Area iniziale

Area iniziale dei Pagamenti

L’area iniziale è composta dai seguenti elementi:

• Sulla sinistra è presente il form per impostare i criteri di filtro sui pagamenti che si vuole consultare.
• Sulla destra è presente l’elenco dei pagamenti che corrispondono ai criteri di filtro impostati. Di ciascun elemento della lista è visualizzato il titolo che corrisponde a quello di una delle pendenze comprese nel pagamento e la dicitura «e altre X pendenze» nel caso in cui il pagamento sia composto da un carrello di pendenze di numero superiore a 1. Oltre al titolo, identificano un elemento della lista anche l’importo complessivo, lo stato e la data.

Dopo aver effettuato una ricerca è possibile ottenere un CSV di esportazione relativo all’elenco dei pagamenti che soddisfano i criteri di ricerca forniti. L’esportazione dell’elenco si effettua selezionando il collegamento Scarica Resoconto che compare sul menu a discesa in alto a destra, come mostrato in figura:

Scarica Resoconto dei Pagamenti

I campi del csv (compresso in formato zip) sono i seguenti:

• Identificativo univoco del pagamento
• Data richiesta pagamento
• Importo
• Stato
• Identificativo del soggetto versante
• Anagrafica del soggetto versante
• Conto di addebito

Selezionando uno degli elementi presenti in elenco si procede alla visualizzazione del dettaglio del pagamento, abilitando l’eventuale modifica: si noti come sia presente una sezione dedicata agli eventi di dettaglio del pagamento stesso.

Dati Pagamento

La pagina dei dati di dettaglio del pagamento comprende:

• Sezione di riepilogo dei dati che caratterizzano l’operazione di pagamento in questione (banca, importo, tipo di pagamento, …)
• Sezione che elenca le pendenze che compongono il carrello associato all’operazione di pagamento. Per ciascuna pendenza in elenco sono visualizzati i dati identificativi comprensivi di singolo importo e stato di avanzamento.
• Sezione Note

Dettaglio del Pagamento

Per aggiungere una nota, premere il pulsante +, il sistema presenta quindi la seguente maschera:

Immissione nota

Con la voce di menu in alto a destra (Scarica Resoconto), è possibile scaricare i documenti salienti associati al pagammento:

Scarica Resoconto

Viene scaricato in questo modo un archivio in formato zip,

Contenuto archivio zip di resoconto del Pagamento

Contenuto Archivio zip del singolo pagamento

File	Formato	Significato
RPT	xml	Richiesta associata al pagamento
RT	xml	Ricevuta telematica associata al pagamento
RT	pdf	Ricevuta telematica in formato pdf

Una ricevuta di pagamento in formato pdf avrebbe il seguente aspetto (si noti la presenza del logo del dominio in alto a destra)

Ricevuta di Pagamento in formato pdf (esempio)

Eventi

Il sistema presenta, associato al dettaglio del pagamento, anche tutti gli eventi intercorsi relativi al pagamento stesso, come mostrato in figura:

Eventi associati a un pagamento

Gli eventi non sono modificabili né ulteriormente espandibile (non è presente un dettaglio ulteriore).

Cruscotto

La sezione Cruscotto mira a dare evidenza grafica immediata alla situazione dei pagamenti all’interno dei domini di cui si ha visibilità.

Area iniziale

Area iniziale Cruscotto

Il sistema propone: * in rosso gli eventi eccezionali * in grigio gli eventi esaminati o corretti

Selezionando una delle caselle si accede al dettaglio dei pagamenti rifiutati o sospesi.

Pagamenti Rifiutati

Cruscotto: pagamenti rifiutati

Cliccando sulla casella del cruscotto, il sistema effettua una ricerca sui pagamenti con il filtro sui pagamenti rifiutati, consentendone l’esame. Esaminare i pagamente implica che il colore della segnalazione su cruscotto viri dal rosso al grigio.

Pagamenti Sospesi

La logica è identica a quanto visto per i pagamenti rifiutati. Cliccando sulla casella del cruscotto, anche in questo caso il sistema effettua una ricerca sui pagamenti con il filtro sui pagamenti sospesi, consentendone l’esame. La logica rimane la stessa anche per il viraggio dei colori (rosso -> grigio)

Giornale degli Eventi

La sezione Giornale degli Eventi mostra le comunicazioni (tecniche e di dettaglio), ed il relativo esito, avvenute con la piattaforma pagoPA secondo quanto previsto dalle specifiche AgID.

Area iniziale

Area iniziale del Giornale degli Eventi

L’elenco degli eventi visualizzati si può filtrare, utilizzando il form presente sulla sinistra.

Gli elementi dell’elenco riassumono i dati principali dell’evento e, in caso di evento di errore, risulta evidenziato tale stato.

Dopo aver effettuato una ricerca è possibile ottenere un CSV di esportazione relativo all’elenco degli eventi che soddisfano i criteri di ricerca forniti. L’esportazione dell’elenco si effettua selezionando il collegamento «Esporta» che compare sul menu a discesa azionato con l’icona in alto a destra nella pagina. Il file prodotto con l’esportazione è un tracciato CSV in cui ciascun record contiene i dati dell’evento.

Il csv contiene le seguenti informazioni:

• Identificatore univoco evento
• Componente
• Categoria Evento
• Ruolo
• Tipo Evento
• Esito
• Data Evento
• Durata Evento
• Sottotipo Esito
• Dettaglio Esito
• idDominio
• iuv
• ccp
• idA2A
• idPendenza
• idPagamento
• dati PagoPA

Selezionando uno degli elementi dell’elenco si accede al dettaglio dell’evento, una pagina che visualizza tutte le proprietà dell’evento.

Dettaglio Evento

Dettaglio di un Evento

Il dettaglio di un evento assiema i seguenti gruppi di informazioni relativi all’evento considerato:

• Le informazioni interne, ovvero tutti i puntatori tecnologici e di processo connessi all’evento
• Gli eventuali dati relativi a PagoPa connessi all’evento (presenti solo per alcune tipologie di eventi)

Funzioni Avanzate

Rendicontazioni

La sezione “Funzioni Avanzate > Rendicontazioni” è dedicata alla consultazione dei flussi di rendicontazione acquisiti da pagoPA. La pagina iniziale mostra l’elenco dei flussi di rendicontazione presenti nel repository.

Area Generale Rendicontazioni

Per ciascuna rendicontazione in elenco, oltre ai riferimenti identificativi (identificativo, psp, ente creditore, …), sono segnalati, con indicazione dello stato, i casi di errore.

È possibile filtrare gli elementi visualizzati utilizzando il form presente sul lato sinistro.

È possibile scaricare un file CSV con i dati delle rendicontazioni, visualizzate con il criterio di ricerca impostato, utilizzando la voce «Scarica Resoconto» presente nel menu a destra sulla testata della pagina.

La selezione di un elemento dell’elenco ne visualizza il dettaglio, come mostrato:

Dettaglio Rendicontazione

Dettaglio Rendicontazione

La pagina di dettaglio della rendicontazione si compone delle seguenti sezioni:

• Riepilogo Informazioni: riporta i dati identificativi della rendicontazione (identificativo flusso, psp, ente creditore, importo, …)
• Pagamenti Rendicontati: Le singole voci di rendicontazione che riguardano ciascun pagamento rendicontato (voce, importo, stato, …)
• Segnalazioni: L’elenco delle eventuali segnalazioni che sono state sollevate dal sistema durante la gestione del flusso di rendicontazione.

Riscossioni

La sezione Funzioni Avanzate > Riscossioni è dedicata alla consultazione delle somme che sono state correttamente riscosse tramite i versamenti operati dai debitori.

Anche in questo caso risulta possibile filtrare gli elementi presenti nella pagina tramite il form presente sul lato sinistro. Di rilevante importanza è la possibilità di filtrare in base allo stato della riscossione:

• Riscossa - è lo stato iniziale relativo agli importi riversati ma non ancora riconciliati.
• Riconciliata - è lo stato finale che indica che tutti gli importi di una determina pendenza sono stati già riconciliati con le somme riversate.

È inoltre possibile selezionare le riscossioni in base al tipo. Esistono due tipi di riscossione:

• Entrata in Tesoreria: Sono cifre riscosse dai PSP che verranno riversate sul conto della banca tesoriera dell’ente creditore. Si tratta di somme soggette a riconciliazione.
• Marca da Bollo Telematica: Sono cifre riscosse dai PSP per il rilascio di una marca da bollo. Tali importi non saranno accreditati all’ente e quindi non sono soggetti a riconciliazione.

Area Generale Riscossioni

È possibile scaricare un file CSV con i dati delle riscossioni, visualizzate con il criterio di ricerca impostato, utilizzando la voce «Scarica Resoconto» presente nel menu a destra sulla testata della pagina.

Selezionando il singolo elemento dall’elenco si accede alla pagina di dettaglioche riporta ulteriori informazioni non modificabili:

Dettaglio Riscossione

Caricamento Pendenze

La sezione Funzioni Avanzate > Caricamento Pendenze è dedicata all’immissione massiva delle pendenze nel sistema. Tali tracciati vengono caricati dagli utenti del cruscotto utilizzando il pulsante di aggiunta. Il form di caricamento permette di selezionare il file da caricare che deve essere in formato JSON e rispettare la sintassi descritta nel manuale di integrazione. All’interno di un tracciato si definiscono le operazioni da eseguire sulle pendenze, che possono essere:

• Inserimento di una nuova pendenza
• Annullamento di pendenza esistente

È possibile filtrare gli elementi, in base al proprio stato di elaborazione, utilizzando il form presente sul lato sinistro.

L’elenco a destra riporta gli elementi, visualizzandone i principali dati identificativi (identificativo del tracciato, data di caricamento e stato dell’elaborazione).

È possibile scaricare un file CSV con i dati di riepilogo dei tracciati, visualizzati con il criterio di ricerca impostato, utilizzando la voce «Scarica Resoconto» presente, a destra, nel menu sulla testata della pagina.

Caricamento massivo pendenze

Dettaglio Tracciato

La selezione di un elemento dell’elenco ne visualizza il dettaglio, che comprende le seguenti informazioni:

• Riepilogo Informazioni: dati generali del tracciato (identificativo del tracciato, data di caricamento e stato dell’elaborazione, operatore che ha effettuato il caricamento, contatori delle operazioni totali, operazioni eseguite, operazioni fallite, … )
• Operazioni: L’elenco delle operazioni eseguite a partire dal tracciato (tipo operazione, esito esecuzione, applicazione, identificativo pendenza, … ).

È possibile scaricare un file compresso in formato zip contentente il tracciato originale, il tracciato di esito generato dall’elaborazione e gli avvisi di pagamento per le pendenze caricate.

Riconciliazioni

Area Generale

La sezione “Riconciliazioni” è dedicata alla consultazione delle voci di riconciliazione delle riscossioni notificate dalla banca tesoriera. Tali informazioni vengono registrate sulla piattaforma dagli applicativi che gestiscono il processo di riconciliazione con la Banca Tesoriera.

È possibile filtrare gli elementi visualizzati nella pagina utilizzando il form presente sul lato sinistro in cui si seleziona l’ente creditore su cui si intende agire.

L’elenco sul lato destro riporta gli elementi visualizzandone i principali dati identificativi:

Area iniziale Riconciliazioni

È possibile scaricare un file CSV con i dati delle riconciliazioni, visualizzate con il criterio di ricerca impostato, utilizzando la voce «Scarica Resoconto» presente nel menu sulla testata della pagina a destra. Il sistema permetterà il download di un file in formato zip che contiene un file riassuntivo in formato csv, con le informazioni tecniche relative a: - idDominio - idIncasso - causale - importo - sct

Dettaglio Riconciliazione

La selezione di un elemento dell’elenco ne visualizza il dettaglio, che comprende le seguenti informazioni:

• Riepilogo Informazioni – dati generali della riscossione con i riferimenti del movimento bancario che lo ha determinato.
• Riscossioni – elenco delle riscossioni riconciliate con le pendenze di origine.

Dettaglio Riconciliazione

Nuova Riconciliazione

Il sistema permette la creazione di una nuovo riconciliazione con le abituali metafore grafiche (tasto + in basso a destra):

Nuova Riconciliazione

Il sistema permette la selezione di un Ente Creditore e, iniziata la scrittura dei primi caratteri del identificativo IUV ne permette la selezione a partire da quanto effettivamente presente in termini di pagamenti e pendenze. Una volta selezionato il corretto identificativo IUV occorre immettere il codice SCT e salvare.

Manutenzione

Accedendo alla sezione Manutenzione si ha la possibilità di effettuare in modalità immediata alcune operazioni solitamente effettuate in modalità temporizzata dagli schedulatori interni di GovPay.

Le operazioni disponibili sono:

• Acquisisci Rendicontazioni: avvia il processo di acquisizione dei flussi di rendicontazione.
• Recupera pagamenti: forza il processo di aggiornamento dei pagamenti per i quali non è stata ancora acquisita la ricevuta telematica.

Nota

Le credenziali per il primo accesso sono state scelte durante la procedura di installazione.

Appendici

Glossario

NDP

Nodo dei Pagamenti SPC. Piattaforma tecnologica per l’interconnessione e Phtteroperabilitit tra le Pubbliche Amministrazioni e i Prestatori di Servizi di Pagamento, di cui all’art. 5, comma 2 del CAD. architrave del sistema pagoPA PA Pubblica Amministrazione (Centrale e Locale).

SPC

Sistema Pubblico di Connettività: è una cornice nazionale di interoperabilità: definisce, cioè, le modalità preferenziali che i sistemi informativi delle pubbliche amministrazioni devono adottare per essere tra loro interoperabili.

AgID

Agenzia per l’Italia Digitale Ente istituito ai sensi del decreto legge n. 83 del 22 giugno 2012 convertito con legge n. 134 del 7 agosto 2012 (già DigitPA). Gestore del Nodo dei Pagamenti-SPC.

RPT

Richiesta di Pagamento Telematico Oggetto informatico inviato dall’Ente Creditore al Prestatore Servizi di Pagamento attraverso il Nodo dei Pagamenti-SPC al fine di richiedere l’esecuzione di un pagamento.

RT

Ricevuta Telematica Oggetto informatico inviato dal Prestatore Servizi di Pagamento all’Ente Creditore attraverso il Nodo dei Pagamenti-SPC in risposta ad una Richiesta di Pagamento Telematico effettuata da un Ente Creditore.

IUV

Identificativo Unico Pagamento.

CCP

Codice Contesto Pagamento.

PSP

Prestatori Servizi Pagamento.

Documentazione

ID	Titolo	Versione
SANP	Specifiche Attuative del Nodo dei Pagamenti-SPC	v.2.2.4 – Luglio 2019
SACIV	Specifiche Attuative dei Codici Identificativi di Versamento, Riversamento e Rendicontazione	v.1.3.1 – Gennaio 2018
PEMP	Pagamento Elettronico della Marca da Bollo digitale	v.1.0 – Febbraio 2015
MYBANK	Transazioni MyBank attraverso il Nodo dei Pagamenti-SPC	v.2.0 – Dicembre 2018
GP-API	GovPay – Manuale di Integrazione	v.3.1 - Luglio 2019
GP-INS	GovPay – Manuale di Installazione	v.3.1 - Luglio 2019

Storia delle modifiche del documento

Data	Versione	Modifiche	Note
2019-07-17	3.1.1	Stesura iniziale del documento
2019-07-24	3.1.2	Revisione del documento alla luce delle nuove funzionalità su Ruoli, Tipi Pendenza e Applicazioni

Integrazione

L’integrazione è l’attività necessaria per consentire l’interazione tra i sistemi gestionali e GovPay al fine di realizzare i principali scenari d’uso previsti dalla piattaforma di pagamento pagoPA.

Gli argomenti trattati sono quindi rivolti agli sviluppatori software che devono realizzare l’integrazione a GovPay delle proprie applicazioni software interne al dominio applicativo dei pagamenti degli Enti Creditori (come portali di pagamento, applicazioni verticali che richiedano pagamenti di tributi e/o servizi o applicazioni di ragioneria).

Gli scenari d’uso descritti richiamano le specifiche AgID, disponibili sulla pagina del progetto pagoPA (https://www.agid.gov.it/it/piattaforme/pagopa/linee-guida-documentazione-tecnica), a cui si rimanda per ogni ulteriore informazione sulla specifica pagoPA.

L’architettura della piattaforma di pagamento

Nella figura seguente è sintetizzato lo scenario architetturale di riferimento, evidenziando il ruolo di GovPay, dei sistemi dell’Ente Creditore e dei servizi centrali del progetto pagoPA.

Architettura della piattaforma di pagamento

Gli Attori principali del Progetto pagoPA

I componenti principali del progetto pagoPA, erogati centralmente da AgID, sono:

• il Nodo SPC: componente che funge da gateway tra la rete SPC degli Enti Creditori e la rete interbancaria dei PSP;
• il WISP: interfaccia grafica che guida l’utente nella scelta del PSP con cui perfezionare il pagamento.

Gli attori che interagiscono nell’ambito del progetto sono:

• l”Ente Creditore, aderente a pagoPA e interessato alla pubblicazione sulla piattaforma delle proprie posizioni debitorie, a governare l’iter del loro pagamento ed alla successiva gestione dell’incassato.
• i Soggetti Debitori: cittadini, o altri soggetti, che detengono posizioni pendenti o richiedono servizi soggetti a pagamento verso l’Ente Creditore;
• i PSP: i Prestatori di Servizi di Pagamento aderenti a pagoPA. Ciascun PSP espone un’interfaccia web, il Portale PSP, per permettere al cittadino di perfezionare i pagamenti delle posizioni presenti su pagoPA;
• la Banca Tesoriera: Istituti gestori dei conti di accredito dell’Ente Creditore.

I principali attori interni all’Ente Creditore

Questo documento si concentra sull’organizzazione interna dell’Ente Creditore, al fine di focalizzare le esigenze di integrazione dei diversi software applicativi dell’Ente. A tal fine nella figura appema vista sono stati introdotti i principali attori interni all’Ente Creditore, ovvero:

• Helpdesk: Personale dedicato ai servizi di helpdesk di primo o secondo livello inerenti ai pagamenti pagoPA.
• Portale di Pagamento: I portali dedicati ai pagamenti nel dominio amministrativo dell’Ente Creditore.
• Gestionale Posizioni: Il verticali competenti per le diverse posizioni debitorie afferenti all’Ente Creditore.
• Sistema Amministrativo Contabile: applicazioni verticali che ricevono il giornale di cassa dalle Banche Tesoriere che attestano i riversamenti dei PSP debitori sui conti di accredito dell’Ente Creditore e responsabili della riconciliazione con i pagamenti operati sulla piattaforma pagoPA.
• GovPay: gateway di pagamento verso la piattaforma pagoPA che realizza le funzioni di backend richieste dalla specifica AgID. Consente l’integrazione Application-To-Application dei portali di pagamento e dei sistemi verticali dell’Ente creditore tramite le seguenti API:
  • API Pagamento: Servizi, ad uso dei portali di pagamento dell’Ente, disponibili per la realizzazione di pagamenti ad iniziativa Ente e di consultazione della posizione debitoria e dello storico dei pagamenti.
  • API Pendenze: Servizi per l’interscambio dei dati relativi alle pendenze di pagamento, ad uso dei verticali gestori delle posizioni debitorie.
  • API Riconciliazione: Servizi dedicati ai sistemi degli Uffici Amministrativi Contabili dell’Ente Creditore responsabili della riconciliazione dei pagamenti.
  • API Backoffice: Servizi dedicati all’integrazione di cruscotti di gestione e monitoraggio alternativi alla GovPay Console.
  • API pagoPA: le API native previste dal protocollo pagoPA, utilizzate internamente dal Connettore pagoPA per le interazioni con il Nodo SPC del progetto pagoPA.
• GovPay Console: Interfaccia utente attraverso cui gli operatori abilitati dell’Amministrazione possono configurare la piattaforma di pagamento e monitorarne l’operatività sia dei processi di pagamento che di riconciliazione. Realizza le funzioni di Tavolo Operativo richiesti dalle specifiche pagoPA.

Nel seguito saranno descritte le modalità di integrazione richieste ai sistemi applicativi dell’Ente Creditore, facendo riferimento a diverse varianti dei seguenti casi d’uso:

Varianti dei casi d’uso

Sintesi	Descrizione
Pagamenti ad iniziativa Ente	Scenari d’utilizzo in cui il soggetto debitore utilizza il portale dei pagamenti dell’ente per effettuare uno o più pagamenti
Pagamenti ad iniziativa PSP	Scenari d’utilizzo in cui l’utente effettua uno o più pagamenti presso il PSP tramite gli avvisi di pagamento
Riconciliazione dei pagamenti	Scenari di utilizzo di GovPay che coinvolgono i sistemi contabili dell’ente, responsabili della riconciliazione dei pagamenti realizzati da pagoPA con le entrate in tesoreria

API di Integrazione

La realizzazione degli scenari descritti nei capitoli successivi, prevede l’utilizzo di servizi di integrazione, esposti da GovPay come API REST, finalizzati all’integrazione dei sistemi verticali dell’Ente Creditore. Nella tabella seguente sono indicati sia gli indirizzi di base di erogazione di ciascun servizio, sia il riferimento alla definizione OpenAPI per la documentazione di dettaglio.

API Pagamento	base url: /govpay/frontend/api/pagamento
API Pendenze	base url: /govpay/backend/api/pendenze
API Riconciliazione	base url: /govpay/backend/api/riconciliazione
API Backoffice	base url: /govpay/backend/api/backoffice
API Verifica e notifica	base url: definita dall’ente creditore

Pagamenti ad iniziativa ente

In questo scenario il Soggetto Debitore utilizza il Portale dei Pagamenti dell’Ente Creditore per effettuare i pagamenti dovuti. Il flusso di pagamento è illustrato nella figura seguente

Pagamento ad iniziativa Ente

1. L’utente debitore utilizza gli strumenti offerti dal Portale dei Pagamenti dell’Ente per giungere alla formalizzazione di una richiesta di pagamento.
2. Dopo aver ricevuto la conferma dal cittadino, il portale avvia il processo di pagamento con GovPay.
3. Il processo di pagamento prosegue indirizzando la navigazione dell’utente sul WISP affinché possa selezionare il PSP e la modalità di pagamento preferita.
4. Dal WISP, la navigazione dell’utente prosegue sul Portale PSP, da lui scelto, dove viene perfezionato il pagamento con la modalità prescelta.
5. Al termine dell’esecuzione del pagamento sul Portale PSP, l’utente viene rediretto sul Portale dei Pagamenti dell’Ente che dà conferma dell’esito del pagamento e ne predispone la ricevuta.

Il flusso descritto si realizza integrando il Portale dei Pagamenti a GovPay e implementando le interazioni individuate dal seguente sequence diagram:

Squence Diagram del pagamento

Predisposizione del pagamento

In questa fase l’utente utilizza i servizi del portale per identificare le pendenze che intende pagare. Questa fase darà luogo a scenari che differiscono solo sulle modalità di reperimento dei dati relativi alle pendenze da pagare:

1. Pendenze disponibili al Portale di Pagamento
2. Pendenze caricate nell’archivio dei pagamenti in attesa di GovPay
3. Pendenze recuperate a partire dall’avviso di pagamento pagoPA

Le pendenze individuate, tramite uno o più dei metodi sopra elencati, andranno a costituire un carrello di pagamento oggetto delle fasi successive. Vediamo in che modo GovPay partecipa nella realizzazione degli scenari sopra citati.

Pagamento di una pendenza disponibile al Portale di Pagamento

In questo scenario l’utente interagisce con il portale per la predisposizione dei dati delle pendenze oggetto di pagamento. Tali dati possono essere:

• Presenti nei sistemi verticali dell’ente dai quali il portale si occupa di reperirli.
• Forniti direttamente dall’utente tramite la compilazione di un form.

In ogni caso il portale necessita del dettaglio completo delle pendenze per procedere alla successiva fase di pagamento e per farlo non è previsto il coinvolgimento di GovPay.

Pagamento di una pendenza caricata nell’archivio dei pagamenti in attesa di GovPay

In questo scenario l’utente accede al Portale Ente e consulta la propria posizione debitoria dall’archivio dei pagamenti in attesa di GovPay, individuando alcune pendenze che desidera pagare. Dopo averle selezionate ed aggiunte al carrello, avvia il pagamento.

La realizzazione di questo scenario prevede due interazioni con GovPay:

1. Il caricamento della pendenza nell’archivio dei pagamenti in attesa: i verticali, gestori delle posizioni debitorie, tramite l’operazione PUT /pendenze/{idA2A}/{idPendenza} dell’API Pendenze, alimentano l’archivio dei pagamenti in attesa con le pendenze generate a valle dei propri processi di istruttoria.
2. L’acquisizione della posizione debitoria di un soggetto debitore: il portale di pagamento acquisisce la posizione debitoria del soggetto autenticato, richiedendo, tramite l’operazione GET /pendenze della API Pagamento, la lista delle pendenze disponibili sul sistema filtrando per identificativo debitore. Le pendenze ottenute saranno visualizzate all’utente che procederà alla selezione e successivo pagamento.

Al termine della selezione, il portale necessita dei soli riferimenti identificativi delle pendenze, ovvero la coppia di parametri idA2A e idPendenza, per la successiva fase di avvio del pagamento.

Pagamento di una pendenza con avviso

In questo scenario l’utente accede al Portale Ente ed individua una pendenza da pagare tramite gli estremi identificativi di un Avviso di Pagamento pagoPA, ovvero:

• Identificativo dominio: codice fiscale dell’Ente Creditore.
• Numero avviso: identificativo dell’avviso per l’Ente Creditore che lo ha emesso.

Con queste informazioni, acquisite tramite scansione dei glifi grafici o inserimento manuale dell’utente, il Portale di Pagamento può verificare lo stato ed i dettagli della pendenza associata tramite l’operazione GET /avvisi/{idDominio}/{numeroAvviso}.

Per informazioni inerenti le modalità di predisposizione e consegna dell’Avviso di Pagamento pagoPA si rimanda al capitolo 5 “Pagamenti ad iniziativa PSP“

Il portale necessita dei soli estremi dell’avviso per la successiva fase di avvio del pagamento.

Avvio del Pagamento

Al termine della fase di predisposizione del pagamento, il portale dispone di un carrello di pendenze in forma completa, riferite per identificativo pendenza oppure per estremi dell’avviso di pagamento, a seconda della modalità di identificazione descritta in precedenza.

Ottenuta dall’utente la conferma a procedere, il Portale avvia il pagamento eseguendo l’operazione POST /pagamenti, inserendo nel corpo della richiesta la lista delle pendenze nei tre possibili formati esplorati nella fase di predisposizione del pagamento. In assenza di errori si ottengono in risposta, tra le altre, le seguenti informazioni necessarie alle successive fasi:

• La URL contenuta in redirect a cui indirizzare l’utente per proseguire nella successiva fase di esecuzione del pagamento;
• L’identificativo idSession necessario a riconciliare la sessione di pagamento al ritorno dell’utente sul portale, nella fase conclusiva di esito;
• La URL contenuta in location per richiedere aggiornamenti sullo stato del pagamento;

Vediamo un esempio:

POST /pagamenti
{
    "urlRitorno":"https://pagamenti.ente.it/pagopa/",
    "pendenze":
    [
        {
            "idA2A":"PAG-GEST-ENTE",
            "idPendenza":"1527844941778",
            "idDominio":"02314420920",
            "causale":"Prestazione n.1527844941778",
            "soggettoPagatore":
            {
                "tipo":"F",
                "identificativo":"RSSMRA30A01H501I",
                "anagrafica":"Mario Rossi"
            },
            "importo":45.01,
            "numeroAvviso":"002152784494177803",
            "dataCaricamento":"2018-06-01",
            "dataValidita":"2018-06-01",
            "tassonomia":"Ticket n.1527844941778",
            "tassonomiaAvviso":"Ticket e prestazioni sanitarie",
            "voci":
            [
                {
                "indice":1,
                "idVocePendenza":"1527844941778-1100",
                "importo":45.01,
                "descrizione":"Compartecipazione alla spesa per prestazioni sanitarie (ticket)",
                "codiceContabilita":"COD_CONTABILITA_11",
                "ibanAccredito":"IT02L1234512345123456789012",
                "tipoContabilita":"ALTRO"
                }
            ]
        }
    ]
}

HTTP 201 CREATED
{
    "id":"e4518f13ecc14381a689c770449f3711",
    "location":"/pagamenti/e4518f13ecc14381a689c770449f3711",
    "redirect":"http://localhost:8080/govpay-ndpsym/wisp/rs/scelta?idSession=6966661822b14c078191f9e251b1038a",
    "idSession":"6966661822b14c078191f9e251b1038a"
}

Selezione del PSP ed Esecuzione del versamento

Il portale avvia la fase di esecuzione effettuando la redirezione dell’utente alla URL ricevuta da GovPay. Il flusso di navigazione guiderà l’utente sul WISP per la selezione del PSP e, successivamente, sul Portale del PSP selezionato per il perfezionamento del versamento.

Al termine delle operazioni, l’utente viene reindirizzato al Portale di Pagamento per consultare l’esito del pagamento.

Esito del Pagamento

Al ritorno sul Portale di Pagamento, al termine delle operazioni, l’utente include nella url di redirezione due parametri che l’integratore deve estrarre dalla query string:

• idSession: corrisponde all’omonimo parametro ottenuto da GovPay in fase di avvio, necessario a riconciliare la sessione di pagamento;
• esito: informazione usabile dal portale per la selezione della pagina da presentare all’utente. È importante sottolineare che l’esito certo del pagamento è comunque dato dalla Ricevuta Telematica (RT). I valori di esito possono essere:
  • OK: l’operazione di pagamento sul Portale del PSP si è conclusa con l’addebito dell’importo necessario.
  • ERROR: l’operazione di pagamento sul Portale del PSP si è conclusa senza l’addebito dell’importo necessario.
  • DIFFERITO: l’esito dell’operazione sarà disponibile solo alla ricezione della RT.

In caso di esito di ERROR, il Portale Ente può mostrare all’utente una pagina di errore, in alternativa visualizza una pagina interlocutoria mentre richiede l’esito del pagamento a GovPay.

Non appena disponibile l’esito del pagamento, GovPay invia una notifica al gestionale tramite un apposito servizio messo a disposizione da quest’ultimo. La notifica inviata contiene anche la ricevuta telematica, come nell’esempio seguente:

POST /pagamenti/02315520920/152784500130106
{
    "idA2A":"PAG-GEST-ENTE",
    "idPendenza":"1527845001301",
    "rpt":
    {
        "versioneOggetto":"6.2",
        "dominio":
        {
            --[OMISSIS]--
        },
        "identificativoMessaggioRichiesta":"46fea36dbf6a4d2ea9e43142d78dfc36",
        "dataOraMessaggioRichiesta":"2018-06-01",
        "autenticazioneSoggetto":"N_A",
        "soggettoVersante":
        {
        --[OMISSIS]--
        },
        "soggettoPagatore":
        {
            --[OMISSIS]--
        },
        "enteBeneficiario":
        {
            --[OMISSIS]--
        },
        "datiVersamento":
        {
            --[OMISSIS]--
        }
    },
    "rt":
    {
        "versioneOggetto":"6.2",
        "dominio":
        {
            --[OMISSIS]--
        },
        "identificativoMessaggioRicevuta":"46fea36dbf6a4d2ea9e43142d78dfc36",
        "dataOraMessaggioRicevuta":"2018-06-01",
        "riferimentoMessaggioRichiesta":"46fea36dbf6a4d2ea9e43142d78dfc36",
        "riferimentoDataRichiesta":"2018-06-01",
        "istitutoAttestante":
        {
            --[OMISSIS]--
        },
        "enteBeneficiario":
        {
            --[OMISSIS]--
        },
        "soggettoVersante":
        {
            --[OMISSIS]--
        },
        "soggettoPagatore":
        {
            --[OMISSIS]--
        },
        "datiPagamento":
        {
            --[OMISSIS]--
        }
    },
    "riscossioni":
    [
        {
            "iur":"idRisc-152784500130106",
            "indice":1,
            "idVocePendenza":"1527845001301-1100",
            "stato":null,
            "tipo":null,
            "importo":45.01,
            "data":"2018-06-01",
            "commissioni":null,
            "allegato":null,
        }
    ]
}

Le sezioni rpt ed rt omesse nell’esempio corrispondono ai tracciati rpt ed rt scambiati con il nodo, per la cui sintassi e semantica si rimanda alle specifiche SANP distribuite da AgID.

L’elemento riscossioni risulta valorizzato solo in caso di pagamento completato con successo.

Per la realizzazione della pagina di esito, il portale può utilizzare le informazioni ottenute tramite il servizio di notifica dell’esempio precedente (modalità push), oppure tramite l’invocazione dell’API di pagamento (modalità pull), tramite l’operazione GET /pagamenti/{idPagamento} utilizzando la url location acquisita nella precedente fase di avvio.

Vediamo un esempio:

GET /pagamenti/e4518f13ecc14381a689c770449f3711
{
    "id":"e4518f13ecc14381a689c770449f3711",
    "nome":"Prestazione n.1527845471301",
    "dataRichiestaPagamento":"2018-06-01",
    "idSessionePortale":null,
    "idSessionePsp":"13a3b51f0e6f4875acac761ac96a53a8",
    "importo":45.01,
    "stato":"ESEGUITO",
    "pspRedirectUrl":"http://lab.link.it/govpay-ndpsym/wisp/rs/scelta?idSession=13a3b51f0e6f4875acac761ac96a53a8",
    "urlRitorno":"https://portale.ente.it/pagopa/?idSession=5d9455e14a50419abf065253030b6a14",
    "contoAddebito":null,
    "dataEsecuzionePagamento":null,
    "credenzialiPagatore":null,
    "soggettoVersante":
    {
        --[OMISSIS]--
    },
    "autenticazioneSoggetto":null,
    "lingua":"IT",
    "pendenze":
    [
        {
            "causale":"Prestazione n.1527845471301",
            "soggettoPagatore":
            {
                --[OMISSIS]--
            },
            "importo":45.01,
            "numeroAvviso":"002152784547130177",
            "dataCaricamento":"2018-06-01",
            "dataValidita":"2018-06-01",
            "dataScadenza":null,
            "annoRiferimento":null,
            "cartellaPagamento":null,
            "datiAllegati":null,
            "tassonomia":"Ticket n.1527845471301",
            "tassonomiaAvviso":"Ticket e prestazioni sanitarie",
            "idA2A":"PAG-GEST-ENTE",
            "idPendenza":"1527845471301",
            "dominio":
            {
                --[OMISSIS]--
            },
            "unitaOperativa":null,
            "stato":"ESEGUITA",
            "segnalazioni":null,
            "rpp":"/rpp?idA2A=PAG-GEST-ENTE&idPendenza=1527845471301",
            "pagamenti":"/pagamenti?idA2A=PAG-GEST-ENTE&idPendenza=1527845471301"
        }
    ],
    "rpp":
    [
        {
            "stato":"RT_ACCETTATA_PA",
            "dettaglioStato":null,
            "segnalazioni":null,
            "rpt":
            {
                --[OMISSIS]--
            },
            "rt":
            {
                --[OMISSIS]--
            },
            "pendenza":"/pendenze/PAG-GEST-ENTE/1527845471301"
        }
    ]
}

Nella risposta, tra le altre informazioni, si individua il parametro stato che può assumere i seguenti valori:

• IN CORSO: non sono ancora state acquisite tutte le ricevute di pagamento da pagoPA e l’esito della transazione non è quindi determinabile;
• ESEGUITO: le ricevute telematiche sono state tutte acquisite e presentano lo stato di successo.
• NON ESEGUITO: le ricevute telematiche sono state acquisite e tutte presentano lo stato di insuccesso.
• ESEGUITO PARZIALE: le ricevute telematiche sono state tutte acquisite e presentano esiti discordanti.

La risposta inoltre presenta i riferimenti necessari ad acquisire le ricevute telematiche nei formati messi a disposizione da GovPay.

Oltre al servizio di richiesta dello stato di pagamento, GovPay notifica l’esito di ciascun pagamento al verticale che gestisce la pendenza associata con l’operazione POST /pagamenti delle API Notifica.

Pagamenti ad iniziativa PSP

In questo scenario al cittadino viene fornito un Avviso di Pagamento AgID relativo ad una pendenza. Egli si reca presso le strutture del PSP (sportello, ATM, Home banking, Mobile APP, etc…) per l’esecuzione del versamento.

Pagamento ad iniziativa PSP

Il flusso di questo scenario è il seguente:

1. L’Ente Creditore, alla predisposizione di una nuova pendenza, stampa l’Avviso di Pagamento pagoPA ad essa associata e la consegna al Soggetto Debitore, in formato digitale o cartaceo, secondo le modalità previte dell’Ente.
2. Munito dell’avviso, il Soggetto Debitore interagisce con il PSP che acquisisce gli estremi dell’Avviso, tramite scansione dei glifi grafici o trascrizione manuale dei codici di riferimento.
3. Il PSP verifica gli estremi di pagamento della pendenza, eventualmente interagendo con il Gestionale Pendenze, e li prospetta al Soggetto Debitore.
4. Il Soggetto Debitore perfeziona il pagamento e GovPay lo notifica al Gestionale Pendenze.

Nell’ambito di questa tipologia di pagamento individuiamo i seguenti casi:

• Consegna dell’Avviso di Pagamento

L’ente creditore, alla predisposizione di una nuova pendenza, stampa l’Avviso di Pagamento pagoPA ad essa associata e la consegna al cittadino.

• Verifica della pendenza collegata all’Avviso di Pagamento

Il cittadino si reca presso il PSP per pagare tramite l’avviso Avviso di Pagamento. Il sistema verifica gli estremi della pendenza associata prima di autorizzare le operazioni di riscossione dell’importo dovuto.

• Notifica del pagamento di un Avviso di Pagamento

Al termine delle operazioni di riscossione, il gestionale viene notificato dell’esito del pagamento per aggiornare lo stato della pendenza.

Avvisatura della pendenza

L’ente creditore, alla predisposizione di una nuova pendenza, ottiene la stampa dell’Avviso di Pagamento pagoPA ad essa associato e lo consegna al cittadino. E” sufficiente indicare nella richiesta di caricamento di una pendenza (invocando l’operazione PUT /pendenze/{idA2A}/{idPendenza} delle API Pendenze) il parametro stampaAvviso valorizzato a true.

Inoltre, valorizzando a true anche il patametro avvisaturaDigitale, istruisce la piattaforma a gestire in autonomia i processi di avvisatura digitale previsti da pagoPA, aprendo, aggiornando e chiudendo la posizione debitoria associata alla pendenza nelle varie fasi del ciclo di vita del pagamento.

In alternativa, il Gestionale Pendenze può avvisare in autonomia il pagamento generando internamente il numero avviso identificativo e non alimentare l’archivio dei pagamenti in attesa di GovPay.

Pagamento dell’Avviso pagoPA

Il Soggetto Debitore avvia con il PSP il pagamento dell’Avviso pagoPA, ad esempio tramite scansione dei codici grafici, utilizzando l’applicazione mobile di home banking, o presentandone una stampa allo sportello di una filiale. Questa fase non prevede nessuna interazione con l’Ente Creditore.

Verifica della pendenza

Il tentativo di pagamento di un Avviso attiva una serie di verifiche da parte della piattaforma pagoPA. GovPay gestisce il colloquio e, se necessario, effettua verso il Gestore Pendenze titolare dell’Avviso oggetto di pagamento una richiesta di verifica della pendenza associata all’avviso tramite l’operazione GET /avvisi/{idDominio}/{numeroAvviso}.

Ad esempio:

GET /avvisi/02315520920/000000000000141
HTTP 200 OK
{
    "idDominio":"02315520920",
    "causale":"Prestazione n.1527843621141",
    "soggettoPagatore":
    {
        "tipo":"F",
        "identificativo":"RSSMRA30A01H501I",
        "anagrafica":"Mario Rossi"
    },
    "importo":45.01,
    "numeroAvviso":"002000000000000141",
    "dataValidita":"2018-06-01",
    "dataScadenza":"2018-12-31",
    "tassonomiaAvviso":"Ticket e prestazioni sanitarie",
    "voci":
    [
        {
            "idVocePendenza":"1527843621141-1100",
            "importo":45.01,
            "descrizione":"Compartecipazione alla spesa per prestazioni sanitarie (ticket)",
            "codiceContabilita":"1100",
            "ibanAccredito":"IT02L1234512345123456789012",
            "tipoContabilita":"ALTRO"
        }
    ],
    "idA2A":"PAG-GEST-ENTE",
    "idPendenza":"1527843621141",
    "stato":"NON_ESEGUITA"
}

Ci sono due scenari in cui GovPay esegue la richiesta di verifica:

• se la pendenza associata all’avviso non è presente nell’archivio dei pagamenti in attesa;
• se la pendenza è presente in archivio, ma la data di validità comunicata risulti decorsa, pur essendo la pendenza non ancora scaduta;

Per data di validità si intende pertanto la data entro la quale la pendenza non subisce variazioni ai fini del pagamento. Alla sua decorrenza, il gestionale potrebbe applicare delle variazioni di importo a causa di sanzioni o interessi, che saranno recepiti da GovPay al momento del pagamento tramite le operazioni di verifica.

Quando invece decorre la data di scadenza, GovPay gestisce eventuali verifiche che l’avviso è scaduto, interrompendone il pagamento.

Notifica del pagamento

Superata la fase di verifica, il PSP perfeziona la riscossione degli importi dovuti e completa il processo di pagamento. GovPay gestisce il colloquio previsto con la piattaforma pagoPA e notifica l’esito delle operazioni al Gestionale Pendenze tramite l’operazione POST /pagamenti/{idDominio}/{iuv}.

Ad esempio:

POST /pagamenti/02315520920/000000000000141
{
    "idA2A":"PAG-GEST-ENTE",
    "idPendenza":"1527843621141",
    "rpt":
    {
        "versioneOggetto":"6.2",
        "dominio":
        {
            --[OMISSIS]--
        },
        "identificativoMessaggioRichiesta":"3014931b62ab4333be07164c2fda6fa3",
        "dataOraMessaggioRichiesta":"2018-06-01",
        "autenticazioneSoggetto":"N_A",
        "soggettoVersante":
        {
            --[OMISSIS]--
        },
        "soggettoPagatore":
        {
            --[OMISSIS]--
        },
        "enteBeneficiario":
        {
            --[OMISSIS]--
        },
        "datiVersamento":
        {
            --[OMISSIS]--
        }
    },
    "rt":
    {
        "versioneOggetto":"6.2",
        "dominio":
        {
            --[OMISSIS]--
        },
        "identificativoMessaggioRicevuta":"3014931b62ab4333be07164c2fda6fa3",
        "dataOraMessaggioRicevuta":"2018-06-01",
        "riferimentoMessaggioRichiesta":"3014931b62ab4333be07164c2fda6fa3",
        "riferimentoDataRichiesta":"2018-06-01",
        "istitutoAttestante":
        {
            --[OMISSIS]--
        },
        "enteBeneficiario":
        {
            --[OMISSIS]--
        },
        "soggettoVersante":
        {
            --[OMISSIS]--
        },
        "soggettoPagatore":
        {
            --[OMISSIS]--
        },
        "datiPagamento":
        {
            --[OMISSIS]--
        }
    },
    "riscossioni":
    [
        {
            "idDominio":"02315520920",
            "iuv":"000000000000141",
            "iur":"idRisc-152784362114159",
            "indice":1,
            "pendenza":"/pendenze/PAG-GEST-ENTE/1527843621141",
            "idVocePendenza":"1527843621141-1100",
            "rpp":"/rpp/02315520920/000000000000141/1871148690",
            "stato":null,
            "tipo":null,
            "importo":45.01,
            "data":"2018-06-01",
            "commissioni":null,
            "allegato":null,
            "incasso":null
        }
    ]
}

Si fa notare che una pendenza può essere oggetto di ripetuti tentativi di pagamento da parte del Soggetto Pagatore. In tal caso il Gestionale Pendenze deve saper gestire più notifiche di pagamento che si distinguono per il parametro ccp (Codice Contesto Pagamento) indicato nella notifica.

Riconciliazione degli incassi

Il rilascio della ricevuta di pagamento, da parte dell’Ente Creditore o del PSP a seconda del modello scelto, libera il Soggetto Debitore da ogni ulteriore adempimento. L’Ente Creditore deve invece concludere il ciclo di vita del pagamento verificando che gli importi riscossi dai PSP vengano correttamente riversati nei propri conti di accredito, gestiti dalla Banca Tesoriera.

Riconciliazione degli incassi

Il flusso di questo scenario è il seguente:

1. Le somme riscosse dai PSP tramite il circuito pagoPA sono riversate sui conti di accredito degli Enti Creditori.
2. Le Banche Tesoriere forniscono ai Sistemi Amministrativi Contabili, nelle modalità concordate con l’Ente Creditore, il Giornale di Cassa, contenente il dettaglio dei movimenti avvenuti sui conti di accredito.
3. Ciascun riversamento pagoPA viene riconciliato individuando i singoli pagamenti da quietanzare.

Riversamento delle somme

I movimenti di riversamento delle somme riscosse sono operati dai PSP secondo i tempi ed i modi indicati dalla specifica AgID “Specifiche Attuative dei Codici di Versamento, riversamento e rendicontazione”. In particolare, la specifica determina che il PSP del pagatore assicuri che l’importo dell’operazione venga accreditato sul conto dell’Ente Creditore entro la fine della giornata operativa successiva a quella indicata nella relativa Ricevuta Telematica, considerando che la giornata operativa termina alle ore 13,00 (cosiddetta “giornata operativa del Nodo dei Pagamenti-SPC”).

Comunicazione del Giornale di Cassa

Quotidianamente, o secondo quanto concordato con la Banca Tesoreria, i Sistemi Amministrativi Contabili ricevono il Giornale di Cassa relativo ai conti di accredito dell’Ente Creditore. Tale documento dettaglia i movimenti contabili avvenuti sui conti di accredito ed in particolare i movimenti di entrata determinati dai riversamenti pagoPA.

I riversamenti pagoPA sono riconoscibili poiché presentano, nel dato AT-05 dell’SCT, il riferimento alle riscossioni riversate in uno dei seguenti formati:

• /PUR/LGPE-RIVERSAMENTO/URI/<identificativoFlusso>
• /RFS/<IUV>/<importo>[/TXT/<descrizione>]
• /RFB/<IUV>[/<importo>][/TXT/<descrizione>]

GovPay gestisce la riscossione ed il riversamento delle singole voci di pendenza, pertanto rimane a carico dei sistemi gestionali dell’Ente Creditore verificare la completa riconciliazione delle pendenze prima di procedere al successivo quietanzamento.

Rinconciliazione delle entrate

Ciascuna entrata riconosciuta come riversamento pagoPA deve essere registrata dal Sistema Amministrativo Contabile in GovPay tramite l’operazione POST /incassi/{idDominio} utilizzando i dati acquisiti al passo precedente. In risposta riceve la lista delle riscossioni afferenti al riversamento.

Ad esempio:

POST /incassi
{
"causale": "/PUR/LGPE-RIVERSAMENTO/URI/2017-01-01ABI00000011234",
"importo": 100.01,
"dataValuta": "2020-12-31",
"dataContabile": "2020-12-31"
}

HTTP 201 CREATED
{
    "id": "12345",
    "causale": "/PUR/LGPE-RIVERSAMENTO/URI/2017-01-01ABI00000011234",
    "importo": 100.01,
    "dataValuta": "2020-12-31",
    "dataContabile": "2020-12-31",
    "riscossioni":
    [
        {
            "idDominio": "01234567890",
            "iuv": "RF23567483937849450550875",
            "iur": "1234acdc",
            "indice": 1,
            "pendenza": "/pendenze/A2A12345/abcdef12345",
            "idVocePendenza": "abcdef12345_1",
            "rpt": "/pendenze/01234567890/abcd12345/n%2Fa",
            "importo": 100.01,
            "ibanAccredito": "IT02L1234512345123456789012",
            "data": "2020-12-31",
            "commissioni": 1.5,
            "allegato":
            {
                "tipo": "Esito pagamento",
                "testo": "string"
            }
        }
    ]
}

Con queste informazioni il Gestionale dell’ente creditore è in grado di effettuare la chiusura contabile di ogni pendenza di pagamento.

In una fase distinta, il Gestionale può effettuare la chiamata a GET /riscossioni delle API di Rendicontazione. L’operazione viene eseguita fornendo i parametri di ricerca quali:

• stato della riscossione impostato a “riscossa”
• arco temporale di ricerca

Il risultato dell’operazione è l’elenco delle riscossioni, nel periodo richiesto, che si trovano ancora in stato “riscossa” e quindi tuttora non incassate, come nel seguente esempio:

GET /riscossioni?stato=RISCOSSA&tipo=ENTRATA&dataRiscossioneA=2017-12-31
HTTP 200 OK
{
    "numRisultati": "10",
    "numPagine": "10",
    "risultatiPerPagina": "1",
    "pagina": "1",
    "prossimiRisultati": "/riscossioni?stato=RISCOSSA&tipo=ENTRATA&dataRiscossioneA=2017-12-31&pagina=2&risultatiPerpagina=1",
    "risultati":
    [
        {
            "idDominio": "01234567890",
            "iuv": "RF23567483937849450550875",
            "iur": "1234acdc",
            "indice": 1,
            "pendenza": "/pendenze/01234567890/abcdef12345",
            "idVocePendenza": "abcdef12345_1",
            "rpt": "/pendenze/01234567890/abcd12345/n%2Fa",
            "importo": 10.01,
            "ibanAccredito": "IT02L1234512345123456789012",
            "data": "2020-12-31",
            "commissioni": 1.5,
            "allegato":
            {
                "tipo": "Esito pagamento",
                "testo": "string"
            }
        }
    ]
}

Quest’ultima operazione ha valenza nell’ambito delle verifiche periodiche atte ad individuare situazioni anomale.

Acquisizione delle rendicontazioni

I flussi di rendicontazione acquisiti da GovPay possono essere recuperati tramite le API di Rendicontazione.

Per l’acquisizione dei flussi di rendicontazione si procede in prima istanza a individuare i flussi presenti, eventualmente filtrando per dominio o data di emissione. L’operazione di ricerca si effettua tramite invocazione della GET /flussiRendicontazione, fornendo i parametri di ricerca richiesti.

Ad esempio:

GET /flussiRendicontazione?idDominio=01234567890&dataDa=2017-11-21&dataA=2017-12-31&pagina=2
HTTP 200 OK
{
    "numRisultati": "30",
    "numPagine": "2",
    "risultatiPerPagina": "25",
    "pagina": "1",
    "prossimiRisultati": "/rendicontazioni?idDominio=01234567890&dataDa=2017-11-21&dataA=2017-12-31&pagina=2",
    "risultati":
    [
        {
            "idFlusso": "2017-11-21ABI12345-10:27:27.903",
            "dataFlusso": "2020-12-31",
            "trn": "TRN123445",
            "dataRegolamento": "2020-12-31",
            "idPsp": "ABI-12345",
            "bicRiversamento": "BIC-12345",
            "idDominio": "01234567890",
            "numeroPagamenti": 1,
            "importoTotale": 100.01
        },
        {
            …
        },
    ]
}

Dalla lista dei risultati forniti si estraggono gli identificativi dei flussi che interessano e si procede all’acquisizione del dettaglio tramite l’invocazione dell’operazione GET /flussiRendicontazione/{idFlusso}.

Ad esempio:

GET /flussiRendicontazione/2017-11-21ABI12345-10:27:27.903
Accept: application/json
HTTP 200 OK
{
    "idFlusso": "2017-11-21GovPAYPsp1-10:27:27.903",
    "dataFlusso": "2020-12-31",
    "trn": "idriversamento123445",
    "dataRegolamento": "2020-12-31",
    "idPsp": "ABI-12345",
    "bicRiversamento": "BIC-12345",
    "idDominio": "01234567890",
    "numeroPagamenti": 1,
    "importoTotale": 10.01
    "rendicontazioni":
    [
        {
            "iuv": "RF23567483937849450550875",
            "iur": "1234acdc",
            "indice": 1,
            "importo": 10.01,
            "esito": 0,
            "data": "2018-12-31",
            "riscossione":
            {
                "pendenza": "/pendenze/A2A_ENTE/abcdef12345",
                "idVocePendenza": "abcdef12345_1",
                "rpt": "/rpt/01234567890/RF23567483937849450550875/n%2Fa",
                "importo": 10.01,
                "ibanAccredito": "IT02L1234512345123456789012",
                "data": "2018-12-29",
                "commissioni": 1.5,
                "allegato":
                {
                    "tipo": "Esito pagamento",
                    "testo": "...."
                }
            }
        }
    ]
}

È possibile anche acquisire il tracciato del flusso in formato originale impostando l’header http Accept ad application/xml.

Altri scenari di integrazione

In questo capitolo si analizzano scenari meno usuali che l’Ente Creditore può realizzare e come GovPay ne supporti la realizzazione tramite i servizi di integrazione.

Scelta del modello di integrazione al WISP

La piattaforma pagoPA predispone versioni diverse del WISP che realizzano workflow di pagamento non compatibili tra loro. Il modello di intermediazione realizzato da GovPay rende trasparente al Portale di Pagamento il workflow utilizzato, lasciando comunque la possibilità di scelta in fase di avvio del pagamento.

La versione del workflow di pagamento realizzato da GovPay viene gestito a livello di configurazione, che per default è impostato alla versione 2.0. Il portale può comunque imporre la versione da implementare passando nella query string della richiesta di pagamento il parametro versioneInterfacciaWISP con uno dei valori possibili (1.3 o 2.0).

Redirezione con più portali di pagamento

La piattaforma pagoPA consente di configurare una url per Ente Creditore a cui i Soggetti Pagatori vengono rediretti al temine del processo di pagamento ad iniziativa Ente. Questa URL è la pagina del Portale di Pagamento dove il pagatore visualizza l’esito della transazione.

Nel caso in cui l’Ente Creditore disponga di più Portali di Pagamento, può gestire la redirezione tramite l’ausilio del componente Web Connector di GovPay. Il ritorno del Soggetto Pagatore può essere gestito specificando la URL di ritorno nella richiesta di pagamento.

Il Web Connecctor di GovPay si farà carico di redirigere il navigatore al corretto Portale di Pagamento includendo nella URL i parametri di esito e idSession previsti dalla specifica.

Gestione automatica delle interfacce

Una delle caratteristiche più interessanti di GovPay è quella di poter essere personalizzato tramite linguaggi formali atti a descrivere le interefacce verso il debitore: è possibile quindi definire le interfacce di pagamento (e anche quelle di inoltro, ad esempio, via mail della ricevuta telematica) attraverso file di testo con sintassi standard. Nel seguito della sezione si affronterà un caso pratico di definizione di intefaccia di una pendenza caricata su un Ente Creditore.

I Linguaggi di definizione utilizzati

La definizione delle interfacce e dei processi di elaborazione e validazione si appoggia ai seguenti standard industriali assai consolidati:

• Angular Json
• Freemarker

Nel primo caso (Angular) esiste una risorsa web che consente di verificare online il form che si sta definendo. Si noti come le sezioni seguenti non possano né vogliano sostituirsi a manualistica e tutorial per i framework prima citati: l’intento è solo quello di presentare alcuni casi d’uso frequenti nell’utilizzo e di semplice estensione.

Personalizzazione del tipo pendenza

La pendenza può essere personalizzata, ad esempio, in relazione alla sua instanza per l’Ente Creditore. Cerchiamo di modificare la sezione della Pendenza Sanzione Amministrativa in relazione a un Ente Creditore. Andando sull’Ente creditore:

Modifica del Tipo Pendenza all’interno di un Ente Ceditore

Selezionando questa modifica, il sistema propone

Interfacce personalizzabili attraverso script nel Tipo Pendenza

Le interfacce personalizzabili sono

Campo	Significato	Note
Layout Form Dati	Definizione dell’nterfaccia di caricamento dei dati dell’istanza della pendenza	Angular Json
Validazione	Interfaccia di validazione dei dati dell’istanza della pendenza	Angular Json
Trasformazione	Motore di traformazione dei dati dell’istanza della pendenza	Freemarker
Promemoria avviso di pagamento: oggetto	Definizione dell’oggetto della mail del promemoria avviso di pagamento	Freemarker
Promemoria avviso di pagamento: messaggio	Definizione del messaggio della mail del promemoria avviso di pagamento	Freemarker
Promemoria ricevuta telematica: oggetto	Definizione dell’oggetto della mail del promemoria ricevuta telematica	Freemarker
Promemoria ricevuta telematica: messaggio	Definizione del messaggio della mail del promemoria ricevuta telematica	Freemarker

Layout Forma Dati

Tramite lo script citato a seguire viene implementata un’interfaccia con i seguenti campi:

Campo	Note
Numero verbale	Campo libero per l’immissione del numero verbale
Anagrafica Debitore	Campo libero per l’immissione di nome e congnome del debitore, come evidenziato anche dall’etichetta
Codice Fiscale Debitore	Campo validato formalmente per l’immissione del codice fiscale del debitore
eMail Debitore	Campo validato formalmente (dev’essere un’email) per l’immissione della mail del debitore
Tipo Violazione	Campo a selezione in cui il debitore deve scegliere il tipo di violazione

Il risultato finale è il seguente:

Form Layout Completo

A titolo di esempio si consideri il campo di selezione, i cui valori sono stati inseriti nel json nella seguente sezione:

«tipoSanzione»: {

«type»: «string», «enum»: [«Violazione art. 123», «Violazione art. 456», «Violazione art. 789»] }

Il risultato è il seguente

Selezione del tipo di violazione

Lo script completo è (si noti le parti di definizione dei pattern di email e codice fiscale)

{
    "schema":
       {
    "type": "object",
            "required":
            [
        "idPendenza",
        "soggettoPagatore",
        "tipoSanzione"
            ],
            "properties":
            {
        "idPendenza":
        {
            "type": "string",
                            "pattern": "[A-Za-z0-9\\-_]{1,35}"
                    },
                    "soggettoPagatore":
                    {
                            "type": "object",
                            "required":
                            [
                                    "identificativo",
                                    "anagrafica"
                            ],
                            "properties":
                            {
                                    "identificativo":
                                    {
                                            "type": "string",
                                            "pattern": "[A-Z]{6}\\d{2}[A-Z]\\d{2}[A-Z]\\d{3}[A-Z]"
                                    },
                                    "anagrafica":
                                    {
                                            "type": "string"
                                    },
                                    "email":
                                    {
                                            "type": "string",
                                            "pattern": "[A-Za-z0-9_]+([\\-\\+\\.'][A-Za-z0-9_]+)*@[A-Za-z0-9_]+([\\-\\.][A-Za-z0-9_]+)*\\.[A-Za-z0-9_]+([\\-\\.][A-Za-z0-9_]+)*"
                                    }
                            }
                    },
                    "tipoSanzione":
                    {
                            "type": "string",
                            "enum": ["Violazione art. 123", "Violazione art. 456", "Violazione art. 789"]
                    }
            }
    },
    "layout":
       [
            {
                    "key": "idPendenza",
                    "title": "Numero verbale"
            },
            {
                    "key": "soggettoPagatore.anagrafica",
                    "title": "Anagrafica debitore",
                    "placeholder": "Nome e cognome"
            },
            {
                    "key": "soggettoPagatore.identificativo",
                    "title": "Codice fiscale debitore"
            },
            {
                    "key": "soggettoPagatore.email",
                    "title": "E-Mail debitore",
                    "placeholder": "Se indicato riceverà l'avviso di pagamento"
            },
            {
                    "key": "tipoSanzione",
                    "title": "Tipo di violazione"
            }
       ]
}

Validazione

Lo script di validazione è ancora espresso nel formato json angular schema. Nel nostro esempio si presenta in questo modo:

{
     "schema":
     {
             "type": "object",
             "required":
             [
                     "idPendenza",
                     "soggettoPagatore",
                     "tipoSanzione"
             ],
             "properties":
             {
                     "idPendenza":
                     {
                             "type": "string",
                             "pattern": "[A-Za-z0-9\\-_]{1,35}"
                     },
                     "soggettoPagatore":
                     {
                             "type": "object",
                             "required":
                             [
                                     "identificativo",
                                     "anagrafica"
                             ],
                             "properties":
                             {
                                     "identificativo":
                                     {
                                             "type": "string",
                                             "pattern": "[A-Z]{6}\\d{2}[A-Z]\\d{2}[A-Z]\\d{3}[A-Z]"
                                     },
                                     "anagrafica":
                                     {
                                             "type": "string"
                                     },
                                     "email":
                                     {
                                             "type": "string",
                                             "pattern": "[A-Za-z0-9_]+([\\-\\+\\.'][A-Za-z0-9_]+)*@[A-Za-z0-9_]+([\\-\\.][A-Za-z0-9_]+)*\\.[A-Za-z0-9_]+([\\-\\.][A-Za-z0-9_]+)*"
                                     }
                             }
                     },
                     "tipoSanzione":
                     {
                             "type": "string",
                             "enum": ["Violazione art. 123", "Violazione art. 456", "Violazione art. 789"]
                     }
             }
     },
     "layout":
     [
     {
                     "key": "idPendenza",
                     "title": "Numero verbale"
             },
             {
                     "key": "soggettoPagatore.anagrafica",
                     "title": "Anagrafica debitore",
                     "placeholder": "Nome e cognome"
             },
             {
                     "key": "soggettoPagatore.identificativo",
                     "title": "Codice fiscale debitore"
             },
             {
                     "key": "soggettoPagatore.email",
                     "title": "E-Mail debitore",
                     "placeholder": "Se indicato riceverà l'avviso di pagamento"
             },
             {
                     "key": "tipoSanzione",
                     "title": "Tipo di violazione"
             }
     ]
}

Un’osservazione attenta dello script ne mostra la sostanziale equivalenza con quello di definizione del layout. In effetti lo script afferma che: 1. I campi necessari sono idPendenza, soggettoPagatore e tipoSanzione, che si mappano su quelli definiti nel punto precedente 2. idPendenza è una stringa alfanumerica lunga fino a 35 caratteri 3. l’email non è necessaria: per essa è comunque fornita un’espressione regolare che impedisce l’immissione di email non valide 4. Il tipo sanzione ammette solo tre valori (123, 456, 789)

In effetti, immettendo lo script nel simulatore prima segnalato si ottiene il seguente risultato

Validazione

Si nota dai messaggi che il simulatore mostra come le componenti di validazione siano correttamente interpretate.

Ci si potrebbe chiedere il perchè di questa ripetizione (Layout Form Dati e Validazione): la ragione di questa necessità risiede nel comportamento non omogeneo dei browser. La prima validazione è infatti demandata al lato client della filiera applicativa, che non ha alcun contratto sull’esecuzione dei controlli. In altre parole, la piattaforma non ha alcuna sicurezza che i controlli immessi nel Layout Form saranno davvero effettuati lato client: l’unica strategia davvero cautelativa, in casi come questi, è pertanto quella di avere uno strato server di gestione degli errori che, prima di interpretare i dati e trasformarli, provveda alla validazione di quanto immesso anche se arrivato al server senza controlli clienti (comportamento del browser). Per i motivi appena descritti, si consiglia sempre di implementare i controlli formali anche in questa sezione.

Trasformazione

Questa sezione provvede all’instradamento, previa loro trasformazione, dei dati immessi nel form verso i servizi che li consumeranno (applicazione selezionata nella sezione Inoltro). Vediamone un esempio complessivo i cui blocchi commenteremo in modo dettagliato:

<#assign jsonUtilities = class["org.openspcoop2.utils.json.JSONUtils"].getInstance()>
<#assign request = jsonUtilities.getAsNode(jsonPath.read("$"))>
<#assign calendar = class["java.util.Calendar"]>
<#assign now = new("java.util.Date")>
<#assign calendarInstance = calendar.getInstance()>
<#assign xxx = calendarInstance.setTime(now)!>
<#assign yyy = calendarInstance.add(calendar.MONTH, 1)!>
<#assign zzz = calendarInstance.set(calendar.DATE, calendarInstance.getActualMaximum(calendar.DAY_OF_MONTH))!>
<#assign dataValidita = calendarInstance.getTime()?string("yyyy-MM-dd")>
<#if request.get("tipoSanzione").asText() = "Violazione art. 123">
     <#assign importo = "54.01">
<#elseif request.get("tipoSanzione").asText() = "Violazione art. 456">
     <#assign importo = "123.6">
<#elseif request.get("tipoSanzione").asText() = "Violazione art. 678">
     <#assign importo = "307">
<#setting locale="en_US">

{
     "idA2A": "A2A-DEMO",
     "idPendenza": "${request.get("idPendenza").asText()}",
     "idDominio": "${pathParams["idDominio"]}",
     "idTipoPendenza": "${pathParams["idTipoPendenza"]}",
     "causale": "Sanzione amministrativa - Verbale n. ${request.get("idPendenza").asText()}",
     "soggettoPagatore":
     {
             "tipo": "F",
             "identificativo": "${request.get("soggettoPagatore").get("identificativo").asText()}",
             "anagrafica": "${request.get("soggettoPagatore").get("anagrafica").asText()}",
             "email": "${request.get("soggettoPagatore").get("email").asText()}"
     },
     "importo": "${importo}",
     "dataValidita": "${dataValidita}",
     "dataScadenza": "${dataValidita}",
     "tassonomiaAvviso": "Servizi erogati dal comune",
     "voci":
     [
             {
                     "idVocePendenza": "1",
                     "importo": "${importo}",
                     "descrizione": "${request.get("tipoSanzione").asText()}",
                     "ibanAccredito": "IT02L1234500000111110000001",
                     "tipoContabilita": "ALTRO",
                     "codiceContabilita": "${pathParams["idTipoPendenza"]}"
             }
     ]
}

Al fine di contestualizzare in modo opportuno il discorso fin qui fatto, è opportuno ricordare il sottostante di questo passo della filiera di elaborazione dei dati, come da interfaccia di configurazione:

Contesto di riferimento della trasformazione

Analizziamo ora le diverse parti dello script

<#assign jsonUtilities = class["org.openspcoop2.utils.json.JSONUtils"].getInstance()>
<#assign request = jsonUtilities.getAsNode(jsonPath.read("$"))>
<#assign calendar = class["java.util.Calendar"]>
<#assign now = new("java.util.Date")>
<#assign calendarInstance = calendar.getInstance()>
<#assign xxx = calendarInstance.setTime(now)!>
<#assign yyy = calendarInstance.add(calendar.MONTH, 1)!>
<#assign zzz = calendarInstance.set(calendar.DATE, calendarInstance.getActualMaximum(calendar.DAY_OF_MONTH))!>
<#assign dataValidita = calendarInstance.getTime()?string("yyyy-MM-dd")>
<#if request.get("tipoSanzione").asText() = "Violazione art. 123">
     <#assign importo = "54.01">
<#elseif request.get("tipoSanzione").asText() = "Violazione art. 456">
     <#assign importo = "123.6">
<#elseif request.get("tipoSanzione").asText() = "Violazione art. 678">
     <#assign importo = "307">
<#setting locale="en_US">

in questa sezione, oltre al trattamento abbozzato delle date di inizio e fine validità (si ricordi che si è in presenza di un esempio) si assegna l’importo in funzione del tipo di sanzione, con la relativa logica di controllo (<#if e seguenti)

Vediamo la sezione di trasformazione vera e propria, con la logica di alimentazione del servizio web di inoltro:

{
     "idA2A": "A2A-DEMO",
     "idPendenza": "${request.get("idPendenza").asText()}",
     "idDominio": "${pathParams["idDominio"]}",
     "idTipoPendenza": "${pathParams["idTipoPendenza"]}",
     "causale": "Sanzione amministrativa - Verbale n. ${request.get("idPendenza").asText()}",
     "soggettoPagatore":
     {
             "tipo": "F",
             "identificativo": "${request.get("soggettoPagatore").get("identificativo").asText()}",
             "anagrafica": "${request.get("soggettoPagatore").get("anagrafica").asText()}",
             "email": "${request.get("soggettoPagatore").get("email").asText()}"
     },
     "importo": "${importo}",
     "dataValidita": "${dataValidita}",
     "dataScadenza": "${dataValidita}",
     "tassonomiaAvviso": "Servizi erogati dal comune",
     "voci":
     [
             {
                     "idVocePendenza": "1",
                     "importo": "${importo}",
                     "descrizione": "${request.get("tipoSanzione").asText()}",
                     "ibanAccredito": "IT02L1234500000111110000001",
                     "tipoContabilita": "ALTRO",
                     "codiceContabilita": "${pathParams["idTipoPendenza"]}"
             }
     ]
}

Possiamo notare che: * idPendenza viene preso dal corrispondente campo definito nella sezione di layout. Occorre porre particolare attenzione a che il wording sia il medesimo di quello in definizione formale del form * idDominio, idTipoPendenza vengono valorizzati nello stesso modo * si definisce l’input, per il campo composto voci, come idVocePendenza, importo, descrizione (preso direttamente dalla request), ibanAccredito imposto come fisso, tipo e codice contabilità

In buona sostanza, esiste una parte preparatoria, con una vera logica di trasformazione e definizione di variabili intermedie, ed una parte di elencazione dei parametri del servizio di inoltro che viene implementata a partire dai semilavorati della prima parte. Il risultato è comunque di avere un sistema di input, trasformazione ed elaborazione configurato e pronto per la produzione tramite la scrittura di alcuni semplici script, ovvero senza le costose, classiche fasi di costruzione di un front-end dedicato propriamente detto. Questa metodologia assicura l’ottimizzazione di tempi e costi e la possibilità di effettuare modifiche praticamente in tempo reale.

Promemoria avviso di pagamento

La piattaforma intende semplificare anche la corispondenza mail con il soggetto debitore (ovviamente a patto che sia presente e presidiata la mail di quest’ultimo), automatizzando l’invio degli avvisi di pagamento. Possiamo, nella sezione apposita, immettere due script freemarker, uno dedicato all’oggetto della mail, il secondo pensato per generare automaticamente il corpo della stessa.

Promemoria pagamento: ${versamento.getCausaleVersamento().getSimple()}

A partire dall’oggetto versamento, lo script estrae la causale, generando l’oggetto della mail dell’avviso di pagamento.

Gentile ${versamento.getAnagraficaDebitore().getRagioneSociale()},
le notifichiamo che e' stata elevata una sanzione amministrativa a suo carico: verbale n. ${versamento.getCodVersamentoEnte()}.
Puo' effettuare il pagamento on-line dal portale ${dominio.getRagioneSociale()} al seguente indirizzo:
https://demo.govcloud.it/govpay-portal/?idDominio=01234567890&numeroAvviso=${versamento.getNumeroAvviso()}.
Oppure stampare l'avviso che trova allegato alla presente email per effettuare il pagamento presso un qualsiasi
prestatore di servizi di pagamento aderente al circuito pagoPA.
Distinti saluti.

Ancora una volta si noti l’estrema personalizzabilità del sistema, che rende possibile variare i messaggi a seconda del dominio e del tipo di sanzione in modo trasparente e praticamente in tempo reale. Il messaggio può dipendere, in toni e riferimento, anche dall’eventuale ritardo rispetto alle scadenze, con tempistiche differenziate: ciò comporta la scrittura di logica di processo in termini elementari.

Promemoria ricevuta telematica

A valle del processo di pagamento della pendenza, la piattaforma, similmente a quanto fatto con l’avviso di pagamento, semplifica l’invio di una ricevuta telematica al soggetto pagatore. Possiamo, nella sezione apposita, immettere due script freemarker, uno dedicato all’oggetto della mail, il secondo pensato per generare automaticamente il corpo della stessa.

<#if rpt.getEsitoPagamento().getCodifica() = 0>
  Notifica pagamento eseguito: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
<#elseif rpt.getEsitoPagamento().getCodifica() = 1>
  Notifica pagamento non eseguito: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
<#elseif rpt.getEsitoPagamento().getCodifica() = 2>
  Notifica pagamento eseguito parzialmente: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
<#elseif rpt.getEsitoPagamento().getCodifica() = 3>
  Notifica decorrenza termini pagamento: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}
<#elseif rpt.getEsitoPagamento().getCodifica() = 4>
  Notifica decorrenza termini pagamento: ${rpt.getCodDominio()}/${rpt.getIuv()}/${rpt.getCcp()}

A partire dall’oggetto versamento, lo script estrae la causale, generando l’oggetto della mail dell’avviso di pagamento.

<#assign dataRichiesta = rpt.getDataMsgRichiesta()?string("yyyy-MM-dd HH:mm:ss")>
Il pagamento di "${versamento.getCausaleVersamento().getSimple()}" effettuato il ${dataRichiesta} risulta concluso con esito
${rpt.getEsitoPagamento().name()}:
Ente creditore: ${dominio.getRagioneSociale()} (${dominio.getCodDominio()})
Istituto attestante: ${rpt.getDenominazioneAttestante()} (${rpt.getIdentificativoAttestante()})
Identificativo univoco versamento (IUV): ${rpt.getIuv()}
Codice contesto pagamento (CCP): ${rpt.getCcp()}
Importo pagato: ${rpt.getImportoTotalePagato()}

Distinti saluti.

Questo tipo di soluzione per la ricevuta telematica possiede tutte le caratteristiche positive dell’avviso di pagamento viste nella sezione precedente.