GovPay

GovPay è una piattaforma open source (GPL v3), che implementa il protocollo di dialogo tra Enti, Intermediari o Partner Tecnologici con il Nodo dei Pagamenti 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:

• Contesto - Un inquadramento generale del contesto di attuazione

• Installazione - Il processo di installazione e dispiegamento del prodotto nell’ambiente dell’ente

• Cruscotto - Le funzionalità disponibili nel cruscotto grafico govpayConsole, ripartite in:

  • Configurazione - Operazioni di configurazione del prodotto a carico degli amministratori del sistema
  • Conduzione - Gestione delle pendenze, monitoraggio e riconciliazione

• Integrazione - La documentazione tecnica delle interfacce applicative (API) per l’integrazione dei sistemi verticali in adozione nell’ambiente tecnologico dell’ente

• Scenari - Una presentazione degli scenari tipici per l’utilizzo di GovPay

• How-To - Una raccolta di best practices per affrontare problematiche di utilizzo comuni

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 Java 8
• Application Server WildFly 18

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

• PostgreSQL 8.x o superiore
• MySQL 5.7 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.

Produzione dell’installer dai sorgenti

La compilazione dei sorgenti richiede:

• Maven 3.5 o successivo
• Java 1.8 o successivo

L’installer può essere prodotto con la seguente procedura:

1. Scaricare i sorgenti dal sito GitHub del progetto: https://github.com/link-it/govpay/
2. Compilare con il comando mvn -Denv=installer_template clean install
3. Spostarsi nella cartella src/main/resources/setup/ ed eseguire lo script prepareSetup.sh

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: selezionare uno degli application server proposti
• DB Platform: selezionare la piattaforma RDBMS utilizzata
• 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.
• Visualizza Impostazioni Avanzate: opzioni per abilitare funzionalità avanzate del prodotto, saranno visualizzate in un passaggio più avanti.

Riferimenti Accesso GovPay

Questo passaggio prevede che vengano inseriti i dati per l’accesso all’istanza di GovPay e le credenziali del cruscotto di gestione:

• Protocollo di Trasporto: indicare il protocollo di trasporto attivo (HTTP | HTTPS)
• Nome Host o IP: inserire l’hostname tramite il quale saranno raggiungibili i servizi di GovPay (ad esempio la console di monitoraggio).
• Porta: indicare la porta

Credenziali dell’utente amministratore:

• Nome e Cognome: nome e cognome da associare alle credenziali di amministrazione
• Username: indicare l’identificativo dell’utenza di amministrazione per l’accesso alla console di gestione e monitoraggio.
• Password: indicare la password seguendo i vincoli «deve contenere almeno una maiuscola, una minuscola, un numero, un carattere speciale ed essere lunga almeno 8 caratteri».

Riferimenti Accesso GovPay

Il Database

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

Informazioni accesso al DB

• 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.
• Nome modulo driver postgres: il nome del modulo con cui è stato deployato il driver JDBC in wildfly

Nota

Il nome del modulo driver viene richiesto sono in caso di istallazione su PostgreSQL

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.

Configurazioni Avanzate

La schermata «Configurazioni Avanzate» è presente solo se nel passaggio «Informazioni Preliminari» è stata selezionata l’opzione «Visualizza Impostazioni Avanzate».

Configurazioni Avanzate

Configurazione Spring Security

• Usa file di configurazione esterni: opzione che abilita i file di configurazione esterni di Spring per l’accesso alle funzionalità avanzate, come la configurazione delle modalità di autenticazione (Modalità di Autenticazione).

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 database per ospitare le tabelle dell’applicazione avente il nome indicato durante la fase di setup. Il charset da utilizzare è UTF-8.

2. Creare un utente sul RDBMS avente i medesimi valori di username e password indicati in fase di setup e diritti di lettura, inserimento e modifica sulle tabella nel database creato in precedenza.

3. Garantire la raggiungibilità dell’application server al RDBMS indicato in fase di setup.

4. Eseguire lo script sql/gov_pay.sql per la creazione dello schema del database utilizzando un’utenza con sufficienti diritti per la creazione delle tabelle. Ad esempio, nel caso di PostgreSQL, si potrà eseguire il comando:

   • psql -h <hostname> -d <database> -U <username> -f sql/gov_pay.sql

5. Copiare il file datasource/govpay-ds.xml, contenente la definizione del datasource, nella directory <JBOSS_HOME>/standalone/deployments dell’application server.

6. Copiare le applicazioni presenti nella directory archivi nella directory <JBOSS_HOME>/standalone/deployments dell’application server.

7. Installare il DriverJDBC, relativo al tipo di RDBMS indicato in fase di setup, come modulo dell’application server.

8. Editare i datasources installati al punto 5 sostituendo la keyword NOME_DRIVER_JDBC.jar con il nome del modulo corrispondente al driver jdbc.

9. 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.

10. In ambiente linux, intallare i pacchetti fontconfig e urw-fonts necessari alle stampe degli avvisi di pagamento

11. Impostare le seguenti properties nella JVM dell’Application Server:

    • java.awt.headless=true
    • file.encoding=UTF-8

12. Avviare l’application server (ad esempio su Linux con il comando <JBOSS_HOME>/bin/standalone.sh oppure utilizzando il relativo service).

Modalità di Autenticazione

Il processo di configurazione e dispiegamento fin qui descritto prevede che vengano attivate le modalità di autenticazione di default sulle API. Le modalità di autenticazione attivate per default sono le seguenti:

• SSL per le API che interfacciano i servizi pagoPA
• HTTP-BASIC ed SSL per tutte le altre API di GovPay

Per abilitare/disabilitare ulteriori modalità di autenticazione, rispetto a quelle attive per default, è necessario procedere con le seguenti operazioni:

1. Abilitare la configurazione esterna di spring-security

   • durante l’esecuzione dell’installer (Configurazione dei moduli applicativi), selezionare l’opzione «Visualizza impostazioni avanzate» nel passaggio «Informazioni Preliminari», quindi l’opzione «Usa file di configurazione esterni» per la configurazione di Spring Security nel passaggio «Configurazione Avanzata».

2. Estrarre le configurazioni di Spring Security

   • copiare dagli archivi war contenuti nell’ear, i file /WEB-INF/classes/spring-sec/api-$$$-applicationContext-security.xml nella della work directory (default /etc/govpay/)

3. Commentare o scommentare le modalità di autenticazione desiderate

   • la configurazione di spring contiene già il codice necessario a tutte le modalità di autenticazione. I vari commenti individuano i blocchi di codice che gestiscono ciascuna modalità eventualmente inclusa in blocchi commentati. Rimuovendo i commenti o impostandoli se ne determina l’abilitazione o disabilitazione.

Eventuali modifiche richiedono il riavvio dell’applicazione per renderle operative. Per i dettagli sulle modalità di autenticazione supportate si faccia riferimento alla sezione Modalità di Autenticazione.

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.

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.

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:

Aggiornamento di versione

GovPay viene costantemente aggiornato per la risoluzione di problemi o l’implementazione di nuove funzionalità, pertanto può risultare necessario effettuare l’installazione di una nuova versione nella propria piattaforma.

GovPay segue il versionamento semantico, pertanto si presentano solitamente due casistiche:

• Aggiornamento di una patch version
• Aggiornamento di una minor version

Non tratteremo il caso di aggiornamento di una major version poichè attualmente non previste.

Aggiornamento di una patch version

Nel caso di aggiornamento di una patch version, ad esempio per aggiornare la versione 3.1.1 alla 3.1.3, è sufficiente sostituire l’archivio EAR dispiegato nell’Application Server.

Si consiglia di effettuare l’aggiornamento dell’EAR con l’Application Server spento.

Aggiornamento di una minor version

Nel caso di aggiornamento di una minor version, ad esempio per aggiornare la versione 3.1.1 alla 3.3.3, è necessario sostituire l’archivio EAR dispiegato nell’Application Server ed applicare in sequenza le patch 3.2.sql e 3.3.sql.

Si consiglia di effettuare le operazioni di aggiornamento con l’Application Server spento e di eseguire un backup del DB prima di applicare le patch.

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

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

L’adesione di un Ente Creditore alla piattaforma deve essere preliminarmente essere eseguita sui sistemi pagoPA tramite il Portale delle Adesioni:

1. Il Referente dei Pagamenti (RP) aggiunge una nuova connessione intermediata all’Ente Creditore individuando il Partner/Intermediario
2. Il Referente Tecnico del Partner/Intermediario associa l’Ente Creditore alla stazione, individuando il codice di segregazione.

Eseguita questa procedura, si può perfezionare la configurazione in GovPay per abilitare l’intermediazione.

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

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

Parametri adesione pagoPA

Campo	Descrizione
Intermediario	Intermediario o Partner di integrazione a pagoPA
Stazione	Stazione di intermediazione a pagoPA
Codice interbancario	Codice CBILL assegnato da pagoPA
Aux Digit	Come individuato in sede di associazione alla stazione sul Portale delle Adesioni
Codice di segregazione	Come individuato in sede di associazione alla stazione sul Portale delle Adesioni

Altre informazioni

Campo	Descrizione
Autorizzazione stampa BT	Autorizzazione alla stampa in proprio assegnata da Poste Italiane
Sintassi IUV	Prefisso degli IUV generati da GovPay per questo dominio. Il prefisso, numerico, può contenere dei placeholder indicati successivamente
Sfoglia…	Araldo dell’Ente Creditore da apporre nelle stampe di avvisi o ricevute. Preferibilmente vettoriale monocromatico

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): codifica dell’applicazione
• %(p): codifica del tipo pendenza
• %(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	Conti di accredito utilizzati dall’Ente Creditore in pagoPA.
Tipi Entrata	Anagrafica delle entrate, riferibili dalle voci pendenza delle posizioni.
Tipi Pendenza	Anagrafica delle tipologie di pendenza.
Connettori	Configurazione dei connettori di esportazione dati.

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

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	Descrizione
Id unità	Codice identificativo, ad uso interno, dell’unità operativa
Ragione Sociale	Ragione sociale dell’Unità Operativa
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 devono essere censiti su GovPay:

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	Descrizione
IBAN Accredito	Codice IBAN del conto di accredito
BIC Accredito	BIC del conto di accredito
Descrizione	Descrizione del conto per una più agevole ricerca
Intestatario del conto	Visualizzato se postale, valorizza l’omonimo campo nel bollettino postale.
Autorizzazione stampa PT	Visualizzato se postale, consente di sovrascrivere il valore nel dettaglio dell’Ente Creditore.
Postale	Indica se l’iban è riferito ad un conto corrente postale
Abilitato	Indica se l’IBAN è abilitato o meno

Tornando all’elenco degli Iban, è possibile scegliere le operazioni di modifica degli elementi precedentemente creati.

Tipi entrata

Nella definizione di una pendenza è possibile specificare fino a 5 voi di importo, ciascuna con i dati di contablità e conto di accredito. Queste informazioni possono essere fornite esplicitamente nella pendenza dall’applicativo chiamante oppure riferire un codice Entrata che individua un Tipo Entrata in questa anagrafica dove si possono configurare questi dati.

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	Descrizione
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
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. Fa eccezione l’entrata preconfigurata “Marca da Bollo Telematica” per la quale si ha la sola possibilità di modificare i parametri di contabilizzazione.

Tipi pendenze

Questa sezione permette la scelta e la personalizzazione delle tipologie di pendenza ammissibili per l’Ente Creditore tra quelle registrate nell’anagrafica dei Tipi Pendenze. Il sistema dà la possibilità, una volta aggiunta una nuova pendenza, di personalizzarla per l’Ente Creditore rispetto alla configurazione di base eventualmente definita nel registro Tipi Pendenze.

Associando un Tipo Pendenza ad un Ente Creditore è possibile indicare le seguenti informazioni generali:

Informazioni generali

Campo	Descrizione
Tipo pendenza	Tipologia di pendenza da associare tra quelle registrate nell’omonima anagrafica
Codifica IUV	Codice numerico associato alla tipologia pendenze, usato nella generazione degli IUV, se previsto
Pagabile da terzi	Indica se la tipologia di pendenza è pagabile anche da soggetti diversi dall’intestatario. Al momento l’informazione non viene utilizzata in nessun controllo.
Abilitato	Abilita o disabilita l’associazione

Le funzioni a valore aggiunto che è possibile configurare sono le seguenti:

Servizi aggiuntivi configurabili per tipologie di pendenza

Servizio	Descrizione
Inserimento pendenza da Operatore	Configurazione del tipo pendenza per il caricamento manuale da operatore.
Pagamento spontanto	Configurazione del tipo pendenza per il pagamento spontaneo.
Comunicazioni via Mail	Configurazione dell’avvisatura al cittadino via Email
Comunicazioni via AppIO	Configurazione dell’avvisatura al cittadino via AppIO
Altre funzioni	Configurazione di servizi ancillari.

Connettori

I connettori sono dei servizi utili all’esportazione dei dati dei pagamenti all’Ente Creditore presenti in GovPay verso l’esterno in formati e modalità compatibili con applicativi terzi. Di seguito i connettori supportati:

Connettori

Connettore	Descrizione
GovPay	Connettore per l’esportazione dei pagamenti in sandard GovPay
MyPivot	Connettore per l’esportazione dei pagamenti verso MyPIVOT
SECIM	Connettore per l’esportazione dei pagamenti verso SECIM

Configurazione del tipo pendenza per il caricamento manuale da operatore.

E” possibile predisporre delle form personalizzate nella Console di GovPay per consentire l’inserimento delle pendenze richiedendo all’operatore un set minimale di informazioni e codificando la logica di creazione della pendenza.

Inserimento pendenze da operatore

Form inserimento Dati

In questa sezione viene definito il layout della form di acquisizione dei dati necessari all’istruttoria della posizione che saranno poi l’input alla successiva fase di validazione:

Form inserimento Dati

Campo	Descrizione
Tipo layout	Indica il motore di interpretazione della definizione della form
Definizione	File che definisce la form nel formalismo scelto in Tipo Layout

I tipi di layout al momento disponibili sono i seguenti:

• Angular json schema form: Progetto GitHub - Playground

Validazione

E” possibile configurare in questa sezione il JSON Schema con cui validare i dati inviati dalla form definita nella sezione precedente.

Trasformazione dati

In questa sezione può essere configurato il processo che, dai dati inseriti nella form, produce una pendenza. Il dato di Input è il JSON prodotto dalla form di inserimento dati, mentre l’output deve essere un JSON che rispetta lo schema di una PendenzaPost. oppure un JSON compatibile con il successivo servizio di inoltro, se configurato.

Inoltro

E” possibile inviare i dati ricevuti ed eventualmente trasformati ad una applicazione per il processo di istruttoria. Il JSON ritornato da tale servizio deve rispettare lo schema di una PendenzaPost.

Configurazione del tipo pendenza per il pagamento spontaneo.

E” possibile predisporre delle form personalizzate nel Portale di Pagamento per consentire il pagamento spontaneo di pendenze richiedendo al cittadino debitore un set minimale di informazioni e codificando la logica di creazione della pendenza.

Pagamento spontaneo da portale

Form inserimento Dati

In questa sezione viene definito il layout della form di acquisizione dei dati necessari all’istruttoria della posizione che saranno poi l’input alla successiva fase di validazione. Il Portale deve essere in grado di acquisire le informazioni dei servizi tramite le API Pagamento e visualizzarle al cittadino. Un esempio di implementazione e” il Portale di Pagamento GovPay:

Form inserimento Dati

Campo	Descrizione
Tipo layout	Indica il motore di interpretazione della definizione della form
Definizione	File che definisce la form nel formalismo scelto in Tipo Layout
Impaginazione	Definisce testi ed immagini a corredo della form di input

I tipi di layout al momento disponibili sono i seguenti:

• Angular json schema form: Progetto GitHub - Playground.

La struttura del documento di impaginazione dipende dall’implementazione del Portale al cittadino. Nel caso del Portale di Pagamento GovPay il JSON deve rispettare il seguente schema

Validazione

E” possibile configurare in questa sezione il JSON Schema con cui validare i dati inviati dalla form definita nella sezione precedente.

Trasformazione dati

In questa sezione può essere configurato il processo che, dai dati inseriti nella form, produce una pendenza. Il dato di Input è il JSON prodotto dalla form di inserimento dati, mentre l’output deve essere un JSON che rispetta lo schema di una Pendenza oppure un JSON compatibile con il successivo servizio di inoltro, se configurato.

Inoltro

E” possibile inviare i dati ricevuti ed eventualmente trasformati ad una applicazione per il processo di istruttoria. Il JSON ritornato da tale servizio deve rispettare lo schema di una PendenzaPost.

Configurazione dell’avvisatura al cittadino via Email

Se dalle impostazioni e” stato correttamente configurato il server di posta, è possibile predisporre delle comunicazioni automatiche verso il cittadino via e-mail. Queste comunicazioni sono ovviamente attivate se tra i dati anagrafici del cittadino viene indicato un indirizzo e-mail valido.

Avvisatura via e-mail

Notifica avviso di pagamento

La notifica di avviso di pagamento viene inviata quando viene creata una nuova pendenza oppure alla data indicata nel campo dataNotificaAvviso se la posizione sarà ancora pagabile.

Notifica avviso

Campo	Descrizione
Tipo template	Tipologia del template di trasformazione
Template oggetto	Template di traformazione per la produzione del testo usato come oggetto della mail
Template messaggio	Template di traformazione per la produzione dell’html usato come corpo della mail
Abilitato	Indica se il servizio di notifica deve o meno essere operativo
Allega pdf avviso	Indica se allegare alla mail il pdf dell’avviso di pagamento

Promemoria scadenza pagamento

All’approssimarsi della data di scadenza indicata sull’avviso, il sistema può inviare una mail di promemoria. Il promemoria viene inviato nella data indicata nel campo dataPromemoriaScadenza o qualche giorno prima della scadenza se la pendenza risulta ancora pagabile.

Promemoria scadebza

Campo	Descrizione
Giorni di preavviso	Numero di giorni dalla scadenza in cui comunicare il promemoria
Tipo template	Tipologia del template di trasformazione
Template oggetto	Template di traformazione per la produzione del testo usato come oggetto della mail
Template messaggio	Template di traformazione per la produzione dell’html usato come corpo della mail
Abilitato	Indica se il servizio di notifica deve o meno essere operativo

Notifica ricevuta pagamento

A fronte di un tentativo di pagamento il sistema può inviare al debitore ed al pagatore, qualora diversi, un messaggio di notifica dell’esito con allegata la stampad della ricevuta:

Notifica ricevuta

Campo	Descrizione
Tipo template	Tipologia del template di trasformazione
Template oggetto	Template di traformazione per la produzione del testo usato come oggetto della mail
Template messaggio	Template di traformazione per la produzione dell’html usato come corpo della mail
Abilitato	Indica se il servizio di notifica deve o meno essere operativo
Allega pdf ricevuta	Indica se allegare alla mail il pdf della ricevuta di pagamento
Notifica solo eseguiti	Indica se inviare la notifica solo nel caso di transazioni avvenute con successo

Configurazione dell’avvisatura al cittadino via AppIO

Nel caso in cui l’Ente abbia correttamente eseguito l’adesione al backoffice IO e configurato tale servizio nelle impostazioni, è possibile predisporre delle comunicazioni automatiche verso il cittadino tramite l’AppIO. Queste comunicazioni sono ovviamente attivate se il cittadino ha installato l’AppIO su uno dei suoi dispositivi personali.

Avvisatura via e-mail

Per attivare il servizio è necessario specificare l”ApiKey fornita dal backoffice IO per il servizio oggetto di pagamento.

Notifica avviso di pagamento

La notifica di avviso di pagamento viene inviata quando viene creata una nuova pendenza oppure alla data indicata nel campo dataNotificaAvviso se la posizione sarà ancora pagabile.

Notifica avviso

Campo	Descrizione
Tipo template	Tipologia del template di trasformazione
Template oggetto	Template di traformazione per la produzione del testo usato come oggetto del messaggio
Template messaggio	Template di traformazione per la produzione del Markdown usato come corpo del messaggio
Abilitato	Indica se il servizio di notifica deve o meno essere operativo

Promemoria scadenza pagamento

All’approssimarsi della data di scadenza indicata sull’avviso, il sistema può inviare una mail di promemoria. Il promemoria viene inviato nella data indicata nel campo dataPromemoriaScadenza o qualche giorno prima della scadenza se la pendenza risulta ancora pagabile.

Promemoria scadebza

Campo	Descrizione
Giorni di preavviso	Numero di giorni dalla scadenza in cui comunicare il promemoria
Tipo template	Tipologia del template di trasformazione
Template oggetto	Template di traformazione per la produzione del testo usato come oggetto della mail
Template messaggio	Template di traformazione per la produzione del Markdown usato come corpo della mail
Abilitato	Indica se il servizio di notifica deve o meno essere operativo

Notifica ricevuta pagamento

A fronte di un tentativo di pagamento il sistema può inviare al debitore ed al pagatore, qualora diversi, un messaggio di notifica dell’esito con allegata la stampad della ricevuta:

Notifica ricevuta

Campo	Descrizione
Tipo template	Tipologia del template di trasformazione
Template oggetto	Template di traformazione per la produzione del testo usato come oggetto della mail
Template messaggio	Template di traformazione per la produzione del Markdown usato come corpo della mail
Abilitato	Indica se il servizio di notifica deve o meno essere operativo
Notifica solo eseguiti	Indica se inviare la notifica solo nel caso di transazioni avvenute con successo

Connettore per l’esportazione dei pagamenti verso SECIM

Questo connettore consente di esportare i dati dei pagamenti gestiti da GovPay in formato compatibile con l’applicativo di riconciliazione sei servizi cimiteriali SECIM.

Configurazione del Connettore SECIM

Parametri di configurazione

Campo	Descrizione
Versione	Versione del tracciato utilizzata per l’esportazione
Codice cliente	Identificativo sull’Indice della Pubblica Amministrazione usato nella compilazione del CSV
Modalità di consegna	Canale di trasmissione del CSV verso l’ente
Tipi pendenza	Elenco dei tipi pendenza oggetto di esportazione

Il tracciato esportato viene nominato con il seguente pattern: «GOVPAY_» + idDominio + «_» + idunivoco + «.csv»

Il batch di esportazione viene eseguito quotidianamente alle 3 di mattina.

Versione 1.0

Il tracciato risulta una personalizzazione del Tracciato di Riconciliazione di Poste Italiane valorizzando i campi con le seguenti convenzioni:

Valori di esportazione

Campo	Descrizione
CODICE ISTITUTO [1..5]	Da configurazione del connettore oppure rt.istitutoAttestante.identificativoUnivocoAttestante.codiceIdentificativoUnivoco se ABI oppure 00000
CODICE CLIENTE [6..12]	Da configurazione del connettore
FILLER [13..22]	Spazi bianchi
TIPO FLUSSO [23..30]	pendenza.vocePendenza.contabilita.proprietaCustom.tipoFlusso oppure NDP001C0
DATA CREAZIONE FLUSSO [31..38]	Data esecuzione del batch
FILLER [39..77]	Spazi bianchi
PROGRESSIVO RECORD [78..90]	Numero di linea
OPERAZIONE [91..93]	Valore fisso “RIS”
FILLER [94..163]	Spazi bianchi
IUV [205..239]	rt.datiPagamento.identificativoUnivocoVersamento
RATA [240..274]	“S” o “T” più numero della rata
FILLER [275..344]	Spazi bianchi
RIFERIMENTO CREDITORE [345..379]	“SECIM” o pendenza.vocePendenza.contabilita.proprietaCustom.tipoRiferimentoCreditore concatenato a pendenza.vocePendenza.contabilita.proprietaCustom.riferimentoCreditore o pendenza.voce.idVoce
FILLER [380..457]	Spazi bianchi
IMPORTO VERSAMENTO [458..472]	pendenza.importoTotale
FILLER [473..517]	Spazi bianchi
CAUSALE VERSAMENTO [518..657]	rt.datiPagamento.datiSingoloPagamentoRT.causaleVersamento
FILLER [658..713]	Spazi bianchi
TIPO DEBITORE [714..716]	rt.soggettoPagatore.identificativoUnivocoPagatore.tipoIdentificativoUnivoco (“F” o “G”)
TIPO CODICE DEBITORE [717..718]	se rt.soggettoPagatore.identificativoUnivocoPagatore.tipoIdentificativoUnivoco == “F” allora “CF” altrimenti “PI”
CODICE DEBITORE [719..753]	rt.soggettoPagatore.identificativoUnivocoPagatore.codiceIdentificativoUnivoco
ANAGRAFICA DEBITORE [754..803]	rt.soggettoPagatore.anagraficaPagatore
FILLER [804..838]	Spazi bianchi
INDIRIZZO DEBITORE [839..888]	rt.soggettoPagatore.indirizzoPagatore
NUMERO CIVICO DEBITORE [889..893]	rt.soggettoPagatore.civicoPagatore
CAP DEBITORE [894..898]	rt.soggettoPagatore.capPagatore
LOCALITA DEBITORE [899..948]	rt.soggettoPagatore.localitaPagatore
PROVINCIA DEBITORE [949..950]	rt.soggettoPagatore.provinciaPagatore
STATO DEBITORE [951..985]	rt.soggettoPagatore.nazionePagatore
FILLER [986..1055]	Spazi bianchi
DATA PAGAMENTO [1056..1063]	rt.ctDatiSingoloPagamentoRT.dataEsitoSingoloPagamento
DATA INCASSO [1064..1071]	rt.ctDatiSingoloPagamentoRT.dataEsitoSingoloPagamento
ESERCIZIO DI RIFERIMENTO [1072..1075]	Valore fisso “0000”
NUMERO PROVVISORIO [1076..1082]	Valore fisso “0000000”
CODICE RETE INCASSO [1083..1085]	Valore fisso “NDP”
CODICE CANALE INCASSO [1086..1088]	Spazi bianchi
CODICE STRUMENTO INCASSO [1089..1091]	Valore fisso “NDP”
NUMERO BOLLETTA [1092.1104]	Spazi bianchi
IMPORTO PAGATO [1105..1119]	rt.datiPagamento.importoTotalePagato
FILLER [1120..1172]	Spazi bianchi
IMPORTO COMMISSIONE PA [1173..1187]	Valore fisso “000000000000000”
IMPORTO COMMISSIONE DEBITORE [1188..1202]	rt.datiPagamento.datiSingoloPagamento[i].commissioniApplicatePSP se presenti altrimenti 0
FILLER [1203..1589]	Spazi bianchi
CCP [1590..1601]	Spazi bianchi
FILLER [1602..2000]	Spazi bianchi

Connettore per l’esportazione dei pagamenti in sandard GovPay

Questo connettore consente di esportare i dati dei pagamenti gestiti da GovPay per l’esportazione verso applicativi terzi:

Configurazione del Connettore GovPay

Parametri di configurazione

Campo	Descrizione
Versione	Versione del tracciato utilizzata per l’esportazione
Modalità di consegna	Canale di trasmissione del CSV verso l’ente
Tipi pendenza	Elenco dei tipi pendenza oggetto di esportazione

Il tracciato esportato viene nominato con il seguente pattern: GovPay_Export_{idTracciato}.zip

Il batch di esportazione viene eseguito quotidianamente alle 3 di mattina.

Versione 1.0

L’archivio contiene le seguenti informazioni:

• File json con i metadati dell’estrazione, come il periodo di osservazione, tipipendenza estratti, versione, etc.. (metadata.json)
• File CSV con la sintesi dei pagamenti ricevuti (govpay_rendicontazione.csv)
• File CSV con la sintesi dei flussi rendicontazione (govpay_flussi_rendicontazione.csv)
• File XML originale pagoPA delle ricevute telematiche: (./RT/{idDominio}_{iuv}_{ccp}.xml)
• File XML originale pagoPA dei flussi di rendicontazione: (./FlussiRendicontazione/{idFlusso}_{dataOraFlusso}.xml)

Tracciato CSV dei pagamenti ricevuti

Per ciascuna riscossione viene aggiunto un record nel tracciato con le seguenti informazioni

• idA2A: da pendenza
• idPendenza: da pendenza
• idDocumento: da pendenza
• codiceRata: da pendenza
• dataScadenza: da pendenza
• idVocePendenza: da pendenza
• idTipoPendenza: da pendenza
• descrizione: da pendenza.causale
• descrizioneVoce: da vocePendenza.descrizione
• anno: da pendenza
• identificativoDebitore: da RT
• anagraficaDebitore: da RT
• identificativoDominio: da RT
• identificativoUnivocoVersamento: da RT
• codiceContestoPagamento:da RT
• indiceDati: da RT
• identificativoUnivocoRiscossione: da RT
• modelloPagamento: da RT
• singoloImportoPagato: da RT
• dataEsitoSingoloPagamento: da RT
• causaleVersamento: da RT
• datiSpecificiRiscossione: da RT
• datiAllegati: da Pendenza
• datiAllegatiVoce: da vocePendenza
• denominazioneAttestante: da RT
• identificativoAttestante: da RT
• contabilita: da vocePendenza

Tracciato CSV delle rendicontazioni

Per ciascuna rendicontazione contenuta nei flussi ricevuti da pagoPA viene aggiunto un record nel tracciato con le seguenti informazioni:

• identificativoFlusso: da FR.identificativoFlusso
• dataOraFlusso: da FR.dataOraFlusso
• identificativoDominio: da FR.codDominio
• identificativoUnivocoRegolamento: da FR.identificativoUnivocoRegolamento
• dataRegolamento: da FR.dataRegolamento
• codiceBicBancaDiRiversamento: da FR.codiceBicBancaDiRiversamento
• numeroTotalePagamenti: da FR.numeroTotalePagamenti
• importoTotalePagamenti: da FR.importoTotalePagamenti
• identificativoUnivocoVersamento: da FR.ctDatiSingoliPagamenti[i].identificativoUnivocoVersamento
• identificativoUnivocoRiscossione: da FR.ctDatiSingoliPagamenti[i].identificativoUnivocoRiscossione
• indiceDatiSingoloPagamento: da FR.ctDatiSingoliPagamenti[i].indiceDatiSingoloPagamento
• singoloImportoPagato: da FR.ctDatiSingoliPagamenti[i].singoloImportoPagato
• codiceEsitoSingoloPagamento: da FR.ctDatiSingoliPagamenti[i].codiceEsitoSingoloPagamento
• dataEsitoSingoloPagamento: da FR.ctDatiSingoliPagamenti[i].dataEsitoSingoloPagamento
• denominazioneMittente: da FR.istitutoMittente.denominazioneMittente
• identificativoMittente: da FR.istitutoMittente.identificativoUnivocoMittente.codiceIdentificativoUnivoco
• denominazioneRicevente: da FR.istitutoRicevente.denominazioneRicevente
• identificativoRicevente: da FR.istitutoRicevente.identificativoUnivocoRicevente.codiceIdentificativoUnivoco

Connettore per l’esportazione dei pagamenti verso MyPIVOT

Questo connettore consente di esportare i dati dei pagamenti gestiti da GovPay in formato compatibile con l’applicativo di riconciliazione MyPIVOT. Il batch di esportazione viene eseguito quotidianamente alle 3 di mattina.

Configurazione del Connettore MyPIVOT

Parametri di configurazione

Campo	Descrizione
Versione	Versione del tracciato utilizzata per l’esportazione
Codice IPA	Identificativo sull’Indice della Pubblica Amministrazione usato nella compilazione del CSV
Modalità di consegna	Canale di trasmissione del CSV verso l’ente
Tipi pendenza	Elenco dei tipi pendenza oggetto di esportazione

Il tracciato CSV esportato viene nominato con il seguente pattern: «GOVPAY_» + idDominio + «_» + idunivoco + «.csv»

Versione 1.0

Il tracciato è conforme alla nota tecnica MyPivot Integrazione Ente valorizzando i campi con le seguenti convenzioni:

Valori di esportazione

Campo	Descrizione
IUD	idA2A@idPendenza
codIuv	rt.datiPagamento.soggettoPagatore.identificativoUnivocoPagatore.tipoIdentificativoUnivoco
tipoIdentificativoUnivoco	rt.datiPagamento.soggettoPagatore.identificativoUnivocoPagatore.tipoIdentificativoUnivoco
codiceIdentificativoUnivoco	rt.datiPagamento.soggettoPagatore.identificativoUnivocoPagatore.codiceIdentificativoUnivoco
anagraficaPagatore	rt.datiPagamento.soggettoPagatore.anagraficaPagatore
indirizzoPagatore	rt.datiPagamento.soggettoPagatore.indirizzoPagatore
civicoPagatore	rt.datiPagamento.soggettoPagatore.civicoPagatore
capPagatore	rt.datiPagamento.soggettoPagatore.capPagatore
localitaPagatore	rt.datiPagamento.soggettoPagatore.localitaPagatore
provinciaPagatore	rt.datiPagamento.soggettoPagatore.provinciaPagatore
nazionePagatore	rt.datiPagamento.soggettoPagatore.nazionePagatore
e-mailPagatore	rt.datiPagamento.soggettoPagatore.e-mailPagatore
dataEsecuzionePagamento	rt.datiPagamento.datiSingoloPagamento[0].dataEsitoSingoloPagamento
importoDovutoPagato	rt.datiPagamento.importoTotalePagato
commissioneCaricoPa	vuoto
tipoDovuto	pendenza.vocePendenza[0].contabilita.proprietaCustom.tipoDovuto o versamento.tassonomiaEnte o versamento.codTipoPendenza
tipoVersamento	vuoto
causaleVersamento	rt.datiPagamento.datiSingoloPagamento[0].causaleVersamento
datiSpecificiRiscossione	rt.datiPagamento.datiSingoloPagamento[0].datiSpecificiRiscossione
bilancio	xml costruito con le informazioni indicate in pendenza.vocePendenza[0].contabilita.quote

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

La piattaforma GovPay utilizza le API di Notifica e Verifica esposte dagli applicativi integrati per completare gli scenari d’uso descritti nelle sezioni di integrazione. In questa sezione si definiscono i dettagli del connettore per l’invocazione delle API.

Connettore alle API di Integrazione

Dettagli della sezione API Integrazione di una Applicazione

Campo	Significato
API Integrazione	URL di invocazione del servizio esposto dall’applicazione
Versione API	Versione delle API da invocare
Tipo Autenticazione	Modalità di autenticazione di GovPay verso le API

Autorizzazioni

In questa sezione è possibile specificare le autorizzazioni dell’Applicazione sulle API di integrazione:

Sezione Autorizzazioni di un’applicazione

Dettagli della sezione API Integrazione di una Applicazione

Campo	Significato
Tipi pendenza	Lista delle tipologie di pendenza su cui l’applicazione può operare
Ruoli	Ruoli autorizzativi sulle API di Backoffice
API Pagamenti	Abilita/disabilita l’utilizzo delle Api di pagamento
API Pendenze	Abilita/disabilita l’utilizzo delle Api di pendenze
API Ragioneria	Abilita/disabilita l’utilizzo delle Api di ragioneria
Enti creditori	Lista degli Enti ed unità operative su cui l’applicazione può operare

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 ottie 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.

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)

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

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.

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 tramite tracciato.

Dal pulsante azione si apre la form di caricamento seguente:

Caricamento massivo pendenze

Il form di caricamento il formato del tracciato di caricamento tra JSON e CSV. Nel caso di formato JSON la sintassi è quella prevista dalle API Backoffice per la POST /pendenze/tracciati/. Nel caso di formato CSV consultare il Formato di default del tracciato CSV di caricamento pendenze, tenendo presente che la sintassi di default può essere personalizzata sia a livello di impostazioni generali della piattaforma che di tipologia di pendenza.

Il form di caricamento permette di selezionare il file da caricare che deve essere in formato JSON secondo. 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.

Formato di default del tracciato CSV di caricamento pendenze

Il tracciato CSV standard di GovPay per il caricamento pendenze prevede una prima linea di intestazione con i nomi delle campi ed una linea per ciascuna pendenza da caricare, utilizzando come separatore la virgola e come carattere di escape il doppio apice.

Il tracciato è il risultato della de-strutturazione della richiesta di caricamento pendenze prevista dalle API Pendenze in formato JSON, alla quale specifica si rimanda per un maggior formalismo nella definzione dei vincoli sintattici e semantici.

Descrizione dei campi CSV

#	Nome	Descrizione	Vincoli
1	idA2A	Identificativo del gestionale responsabile della pendenza, come censito in anagrafica	Obbligatorio
2	idPendenza	Identificativo della pendenza, univoco per gestionale responsabile	Obbligatorio, max 35 caratteri
3	idDominio	Codice fiscale dell’ente creditore, come censito in anagrafica	Obbligatorio
4	numeroAvviso	Identificativo dell’avviso di pagamento. Se non fornito, viene assegnato da GovPay.	Opzionale, sintassi AgID.
5	tipoPendenza	Tipologia della pendenza, come censito in anagrafica	Opzionale, default LIBERO
6	idUnitaOperativa	Identificativo dell’unità interna all’ente creditore beneficiaria del pagamento, come censita in anagrafica	Opzionale
7	causale	Descrizione della pendenza	Obbligatoria, max 140 caratteri
8	annoRiferimento	Anno di riferimento della pendenza	Opzionale, numerico 4 cifre
9	cartellaPagamento	Identificativo della cartella di pagamento a cui afferisce la pendenza	Opzionale, max 35 caratteri
10	datiAllegati	Dati applicativi allegati dal gestionale secondo un formato proprietario	Opzionale
11	direzione	Identificativo della direzione interna all’ente creditore	Opzionale, max 35 caratteri
12	divisione	Identificativo della divisione interna all’ente creditore	Opzionale, max 35 caratteri
13	importo	Importo della pendenza	Obbligatorio, deve corrispondere alla somma degli importi delle voci. Max 10 cifre compresi due decimali separati dal punto (.)
14	dataValidita	Data di validità dei dati della pendenza, decorsa la quale la pendenza può subire variazioni	Opzionale, data nella forma yyyy-MM-dd
15	dataScadenza	Data di scadenza della pendenza, decorsa la quale la pendenza non è più pagabile	Opzionale, data nella forma yyyy-MM-dd
16	tassonomiaAvviso	Macro categoria della pendenza secondo la classificazione Agid	Opzionale, enumerazione: [ Cartelle esattoriali, Diritti e concessioni, Imposte e tasse, IMU, TASI e altre tasse comunali, Ingressi a mostre e musei, Multe e sanzioni amministrative, Previdenza e infortuni, Servizi erogati dal comune, Servizi erogati da altri enti, Servizi scolastici, Tassa automobilistica, Ticket e prestazioni sanitarie, Trasporti, mobilità e parcheggi ]
17	tipoSoggettoPagatore	Tipologia del soggetto pagatore	Obbligatorio, Enumerazione: [ F, G ] per Fisica o Giuridica
18	identificativoPagatore	Identificativo del soggetto pagatore. Codice fiscale, Partita iva o ANONIMO se non identificato	Obbligatorio, max 35 caratteri
19	anagraficaPagatore	Anagrafica del soggetto pagatore. Nome e Cognome, Ragione sociale o ANONIMO se non identificato	Obbligatorio, max 70 caratteri
20	indirizzoPagatore	Indirizzo di residenza del soggetto pagatore	Opzionale, max 70 caratteri
21	civicoPagatore	Numero civico di residenza del soggetto pagatore	Opzionale, max 16 caratteri
22	capPagatore	Codice di avviamento postale di residenza del soggetto pagatore	Opzionale, max 16 caratteri
23	localitaPagatore	Località di residenza del soggetto pagatore	Opzionale, max 35 caratteri
24	provinciaPagatore	Provincia di residenza del soggetto pagatore	Opzionale, max 35 caratteri
25	nazionePagatore	Nazione di residenza del soggetto pagatore	Opzionale, 2 caratteri
26	emailPagatore	Email del soggetto pagatore	Opzionale
27	cellularePagatore	Numero di cellulare del soggetto pagatore	Opzionale, nella forma +39 000 1234567
–	idVoce*	Identificativo della i-esima voce di pagamento della pendenza, univoco per pendenza.	Obbligatorio, max 35 caratteri
–	importoVoce*	Importo della i-esima voce di pagamento della pendenza	Obbligatorio, max 10 cifre compresi due decimali separati dal punto (.)
–	descrizioneVoce*	Descrizione della i-esima voce di pagamento della pendenza	Obbligatorio, max 140 caratteri
–	ibanAccreditoVoce*	Identificativo del conto di accredito della i-esima voce di pagamento della pendenza, censito in anagrafica	Obbligatorio in alternativa a tipoEntrataVoce* o tipoBolloVoce*
–	ibanAppoggioVoce*	Identificativo del conto di appoggio della i-esima voce di pagamento della pendenza, censito in anagrafica	Opzionale se valorizzato ibanAccreditoVoce*, altrimenti ignorato
–	tipoContabilitaVoce*	Tipologia di codifica del capitolo di bilancio della i-esima voce di pagamento della pendenza	Obbligatorio se valorizzato ibanAccreditoVoce*, enumerazione: [ CAPITOLO, SPECIALE, SIOPE, ALTRO ], altrimenti ignorato
–	codiceContabilitaVoce*	Codice del capitolo di bilancio della i-esima voce di pagamento della pendenza	Obbligatorio se valorizzato ibanAccreditoVoce*, altrimenti ignorato
–	tipoEntrataVoce*	Riferimento alla tipologia di entrata della i-esima voce di pagamento della pendenza, censita in anagrafica	Obbligatorio in alternativa a ibanAccreditoVoce* o tipoBolloVoce*
–	tipoBolloVoce*	Tipologia di bollo della i-esima voce di pagamento della pendenza	Obbligatorio in alternativa a ibanAccreditoVoce* o tipoEntrataVoce*, enumerazione: [ 01 ] dove 01 è la Marca da Bollo Telemarica
–	hashBolloVoce*	Digest in base64 del documento informatico associato alla marca da bollo della i-esima voce di pagamento della pendenza	Obbligatorio se valorizzato tipoBolloVoce*, altrimenti ignorato
–	provinciaBolloVoce*	Sigla automobilistica della provincia di residenza del soggetto pagatore della i-esima voce di pagamento della pendenza	Obbligatorio se valorizzato tipoBolloVoce*, altrimenti ignorato. Due caratteri maiuscoli.
82	dataAvvisatura	Data di spedizione dell’avvisatura, se prevista dalla configurazione.	Opzionale, se non impostata si intende immediata. Se valorizzato con MAI l’avvisatura viene inibilita
83	idDocumento	Identificativo del documento a cui afferisce la pendenza, se ne esiste uno.	Opzionale, da usare in caso di rateizzazioni.
84	descrizioneDocumento	Titolo del documento. Verra” utilizzato per la stampa dell’avviso pagoPA.	Opzionale, se non valorizzato sarà usata la causale della pendenza.
85	numeroRata	Numero di rata in caso di pagamento rateale. In caso di pagamenti con soglia temporale, usare la sintassi ENTROxxx o OLTRExxx dove xxx è il numero di giorni previsto.	Opzionale, non valorizzare per il pagamento in soluzione unica.
86	linguaSecondaria	Indica la seconda lingua da affiancare all’italiano nella stampa dell’avviso di pagamento, le lingue supportate sono Sloveno (sl), Inglese (en), Tedesco (de) e Francese (fr). Il valore speciale false forza la stampa nella sola lingua italiana. Opzionalmente è possibile indicare anche la traduzione della causale separandola con il carattere | (pipe).	Opzionale, Enumerazione: [ de, en, fr, sl, false ], non valorizzare per gli avvisi di pagamento stampati solo in italiano.

I campi che determinano una voce di pagamento della pendenza si ripetono sostituendo l’asterisco con la posizione della voce, ovvero: idVoce1, importoVoce1, …., idVoce2, importoVoce2, … etc…

Si suggerisce di valorizzare il parametro dataAvvisatura in modo tale da avere l’opportunità di intervenire prima dell’avvisatura al cittadino in caso di caricamenti indesiderati

Si precisa che, per vincoli pagoPA, sono consentite un massimo di 5 voci di pagamento per una pendenza e che sono pagabili ad iniziativa PSP solo pendenze con una sola voce di pagamento.

Annullamento di una pendenza

Il tracciato CSV descritto in precedenza può essere utilizzato anche per effettuare l’annullamento di una pendenza. Per farlo è sufficiente valorizzare i campi idA2A e idPendenza con i valori della pendenza da annullare e l’importo a 0. Tutti gli altri campi sono ignorati dal parser.

Manutenzione

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

Le operazioni disponibili sono:

• Acquisisci Rendicontazioni: avvia manualmente il processo di acquisizione dei flussi di rendicontazione. Il processo è normalmente eseguito automaticamente ogni quattro ore.
• Recupera pagamenti: avvia manualmente il processo di recupero dei pagamenti per i quali non è stata acquisita la ricevuta telematica nei tempi consueti. Il processo viene normalmente eseguito automaticamente ogni ora.
• Resetta la cache: svuota la cache delle configurazioni per rendere immediatamente operative le eventuali modifiche effettuate dall’operatore. La cache viene normalmente svuotata ogni ora.

Impostazioni

TBD

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	Interfaccia
API Pendenze	base url: /govpay/backend/api/pendenze	Interfaccia
API Riconciliazione	base url: /govpay/backend/api/riconciliazione	Interfaccia
API Backoffice	base url: /govpay/backend/api/backoffice	Interfaccia
API Verifica e notifica	base url: definita dall’ente creditore	Interfaccia

Modalità di Autenticazione

Le modalità di autenticazione supportate dalle API di GovPay sono quelle indicate nella seguente tabella.

Modalità di Autenticazione

Modalità	Principal	Descrizione	AUTH_METHOD
basic	username	username e password fornite tramite header Authorization	basic
form	username	username e password fornite tramite form di autenticazione custom	form
ssl	subject del certificato	invocazione SSL con certificato client	ssl
ssl-header	subject del certificato	invocazione con certificato codificato in header HTTP	sslheader
header	valore dell’header	principal comunicato in header HTTP	header
spid	codice fiscale o partita iva dell’utenza spid	proprietà dell’utenza SPID propagate in header HTTP	spid
session	principal individuato in sede di creazione della sessione	autenticazione tramite sessione precedentemente creata	session
public	nessun principal	accesso anonimo	public

Il valore AUTH_METHOD viene utilizzato per costruire la URL di invocazione delle API con la modalità di autenticazione prescelta. Lo schema per construire la URL di invocazione è il seguente:

BASE_URL + /rs/ + AUTH_METHOD

Esempio di URL di invocazione: https://host-gp/govpay/frontend/api/pagamento/rs/basic/v2/pagamenti

L’utilizzo delle modalità di autenticazione ssl e ssl-header prevedono che i certificati utilizzati vengano autorizzati nella configurazione di livello trasporto su GovPay. La modalità session consente di riusare una sessione di autenticazione attiva, fornendo il relativo identificativo, evitando quindi di effettuare una nuova autenticazione. Seguendo le impostazioni di default, le modalità di autenticazione attive saranno le sole basic e ssl per tutte le API, con la sola eccezione della API di Pagamento dove è prevista per default la sola autenticazione ssl. È possibile abilitare/disabilitare le modalità di autenticazione descritte nella tabella Modalità di Autenticazione seguendo la modalità di deploy prevista in fase di installazione come descritto in Modalità di Autenticazione.

Modalità di Autorizzazione

A valle del processo di autenticazione, quindi dopo che è stato identificato l’utente che invocato una API, GovPay valuta i criteri di autorizzazione per stabilire quali operazioni sono consentite. La tabella che segue descrive le poliiche generali di autorizzazione che vengono applicate.

Modalità di Autorizzazione

API	Tipi di Autenticazione	Operazioni Consentite
Backoffice	Tutte tranne public	Il principal individuato deve essere associato ad un Operatore o Applicazione registrato in GovPay a cui sono assegnati uno o più ruoli che determinano le operazioni autorizzate limitatamente ad un insieme di Enti Creditori e Tipologie di Pendenza.
Pendenze	Tutte tranne public	Se il principal individua una applicazione autorizzata all’uso dell’API, questa può inserire nuove pendenze delle Tipologie e per gli Enti creditori autorizzati, mentre la consultazione e l’aggiornamento è limitata a quelle da lei create.
Pagamento	Tutte	Se il principal individua una applicazione autorizzata all’uso dell’API, questa può avviare transazioni di pagamento e consultare le pendenze delle Tipologie di Pendenza per gli Enti creditori autorizzati, mentre la consultazione delle transazioni di pagamento è limitata a quelle da lei create. Se il principal individua un cittadino, questi può vedere le pendenze e pagamenti di cui risulta pagatore o versante e avviare transazioni di pagamento per proprie pendenze, avvisi o spontanei. Se l’accesso è anonimo, l’utente può avviare pagamenti di avvisi o spontanei e consultare pagamenti associati alla sessione d’uso.
Ragioneria	Tutte tranne public	Se il principal individua un’applicazione autorizzata all’uso dell’API, questa può creare nuove riconciliazioni e consultare le rendicontazioni, le riscossioni e le transazioni per gli Enti creditori autorizzati, mentre la consultazione delle riconciliazioni di pagamento è limitata a quelle da lei create.
pagoPA	ssl o basic	Il principal deve corrispondere a quello indicato nel connettore pagoPA configurato nell’intermediario indicato.

Autorizzazione Applicazioni

Una volta determinate le modalità di autenticazione da adottare, e preso visione del partizionamento dei criteri di autorizzazione poc’anzi descritti, per consentire l’accesso ad un applicativo per invocare una determinata API è necessario procedere alla configurazione sul cruscotto di gestione. I passi seguenti descrivono un esempio nel caso delle API di Pagamento:

1. Censire una nuova applicazione (vedi Applicazioni) assegnando il principal adeguato alla modalità di autenticazione (come il subject del certificato nel caso ssl o la username nel caso basic).
2. Autorizzare l’applicazione alle API Pagamento per gli Enti e i Tipi Pendenza desiderati.
3. Per un immediato riscontro della configurazione effettuata procedere con il reset della cache (Manutenzione > Resetta la cache).

Protezione delle API pubbliche

GovPay integra alcune protezioni per le API di pagamento esposte ai cittadini per mitigarne l’uso improprio. Abilitando la relativa funzione nella pagina delle impostazioni, si attivano le seguenti funzioni:

• google reCAPTCHA: le operazioni POST /pagamenti e GET /avvisi vengono autorizzate se superati i controlli previste dal reCAPTCHA v2 o v3
• hardening delle url: per la GET /avvisi, in alternativa al reCAPTCHA, è possibile passare il parametro UUID in query string, utile per la predisposizione di link diretti alle pagine di pagamento.

Pagamenti ad iniziativa ente

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

L’utente utilizza le funzionalità del portale per identificare le pendenze che intende pagare. La composizione dei pagamenti da effettuare avviene in modo differente in base alla seguente casistica:

1. Le pendenze sono disponibili nell’ambito del Portale di Pagamento
2. Le pendenze sono state preventivamente caricate nell’archivio dei pagamenti in attesa di GovPay
3. Le pendenze vengono 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 di seguito le differenti modalità di interazione, previste con GovPay, in base alla diversa situazione tra quelle sopra elencate.

Pagamento di una pendenza disponibile al Portale di Pagamento

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

L’utente accede al Portale 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

Ll’utente accede al Portale 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;

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.

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. 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.

Si possono consultare degli esempi di invocazione delle API di integrazione, corrispondenti a quando descritto sopra, nelle sezioni Scenario «Pagamento di un dovuto ad iniziativa Ente» e Scenario «Pagamento spontaneo ad iniziativa ente».

Pagamenti ad iniziativa PSP

Il cittadino, provvisto di un Avviso di Pagamento AgID relativo ad una pendenza, 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 parametro 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}/{iuv}.

Ci sono due contesti 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}.

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.

Si può consultare un esempio di invocazione delle API di integrazione, corrispondente a quando descritto sopra, nella sezione Scenario «Pagamento di un dovuto ad iniziativa PSP».

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 /riconciliazioni/{idDominio} utilizzando i dati acquisiti tramite il Giornale di Cassa. La risposta ottenuta con tale invocazione contiene la lista delle riscossioni associate al riversamento. Con queste informazioni il Gestionale dell’ente creditore è in grado di effettuare la chiusura contabile di ogni pendenza di pagamento.

Si può consultare un esempio di invocazione delle API di Riconciliazione, corrispondente a quando descritto sopra, nella sezione Scenario «Riconciliazione dei Pagamenti con la Tesoreria».

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.

Per integrare il Web Connector nel workflow di pagamento, è sufficiente indicare sul Portale delle Adesioni la URL del Web Connector (``https://{host}/govpay/frontend/web/connector/ecsp/psp`) nel campo URL di redirezione della Stazione

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.

Scenari

Introduzione agli scenari

Pagamento di un dovuto ad iniziativa ente

In questo scenario la pendenza da pagare ha origine nel contesto dell’ente, che si connota come creditore nei confronti di un determinato cittadino. Quest’ultimo provvede al pagamento accedendo al portale dei pagamenti dell’ente ed avvia la transazione utilizzando gli strumenti disponibili.

Lo scenario si articola complessivamente nelle seguenti fasi:

1. L’applicativo gestionale dell’ente, che ha dato origine alla pendenza, effettua il caricamento della medesima sul GovPay, andando ad alimentare l’archivio dei pagamenti in attesa.
2. Il cittadino debitore accede al portale dei pagamenti dell’ente, utilizza gli strumenti a sua disposizione per identificare la pendenza di cui è debitore, procedendo poi al pagamento della medesima seguendo il flusso previsto da pagoPA.
3. Al termine del processo di pagamento, il portale recupera l’esito del pagamento e predispone il download della relativa ricevuta.

Le fasi che andiamo a descrivere per questo scenario sono le seguenti:

1. La Realizzazione, che prevede:
   • L’uso delle API Pendenze di GovPay per l’integrazione con i sistemi verticali gestionali e consentire il caricamento delle pendenze nell’archivio dei pagamenti in attesa.
   • L’uso delle API «Pagamento di GovPay per l’integrazione con il portale al cittadino e realizzare il workflow di pagamento ad iniziativa Ente previsto da pagoPA (aka Modello 1).
2. La Configurazione di GovPay per supportare lo scenario descritto utilizzando il cruscotto di gestione.
3. L”Esecuzione di un esempio utilizzando l’ambiente di simulazione.

Realizzazione

In questo scenario il cittadino debitore utilizza il portale di pagamento dell’ente creditore per consultare la propria posizione debitoria, precedentemente alimentata dai sistemi gestionali delle pendenze, predisporre un carrello di dovuti e procedere al suo pagamento.

La realizzazione di questo scenario prevede le seguenti tre fasi:

1. Il caricamento della pendenza nell’archivio dei pagamenti in attesa da parte del gestionale
2. La consultazione della posizione debitoria e la gestione del processo di pagamento da parte del portale ente
3. La visualizzazione dell’esito di pagamento e download della ricevuta telematica

Caricamento della Pendenza

Il caricamento della pendenza nell’archivio dei pagamenti in attesa di GovPay si realizza invocando l’operazione PUT /pendenze/{idA2A}/{idPendenza} dell’API Pendenze.

Di seguito un esempio di invocazione valida nell”Ambiente Demo:

Richiesta

 PUT /govpay/backend/api/pendenze/rs/basic/v2/pendenze/A2A-DEMO/987
 Authorization: Basic aWRBMkEtZGVtbzpwYXNzd29yZA==
 Content-type: application/json
 Accept: application/json

 {
   "idTipoPendenza": "SANZIONE",
   "idDominio": "01234567890",
   "causale": "Sanzione CdS n. abc00000",
   "soggettoPagatore": {
     "tipo": "F",
     "identificativo": "RSSMRA30A01H501I",
     "anagrafica": "Mario Rossi"
   },
   "importo": 105.01,
   "tassonomiaAvviso": "Multe e sanzioni amministrative",
   "dataValidita": "2019-12-31",
   "dataScadenza": "2020-12-31",
   "voci": [
     {
       "idVocePendenza": "987-SANZIONE",
       "importo": 100.01,
       "descrizione": "Sanzione per divieto di sosta",
       "ibanAccredito": "IT02L1234500000999990000001",
       "tipoContabilita": "ALTRO",
       "codiceContabilita": "SANZIONE"
     },
     {
       "idVocePendenza": "987-CONTRIBUTO",
       "importo": 5,
       "descrizione": "Contributo Regionale",
       "ibanAccredito": "IT02L1234500000111110000001",
       "tipoContabilita": "ALTRO",
       "codiceContabilita": "CONTRIBUTO"
     }
   ]
 }

Risposta

 HTTP 201 CREATED
 {
   "idDominio": "01234567890"
 }

Consultazione della Posizione Debitoria

Il cittadino, tramite il portale messo a disposizione dall’ente, deve individuare le pendenze di cui è debitore per avviarne il pagamento. A tale scopo GovPay espone le API di Pagamento che consentono di reperire la posizione debitoria di un cittadino ed avviarne il pagamento utilizzando

La prima operazione utilizzata è GET /pendenze applicando un filtro per codice fiscale e stato delle pendenze, ricevendo in risposta la posizione debitoria del cittadino.

Richiesta

 GET /govpay/frontend/api/pagamento/rs/basic/v2/pendenze?idDebitore=RSSMRA30A01H501I&stato=NON_ESEGUITA
 Accept: application/json"
 Authorization: Basic aWRBMkEtcG9ydGFsZTpwYXNzd29yZA==

Risposta

 HTTP 200 OK
 Content-type: application/json

 {
   "numRisultati": 1,
   "numPagine": 1,
   "risultatiPerPagina": 25,
   "pagina": 1,
   "risultati": [
     {
       "idA2A": "A2A-DEMO",
       "idPendenza": "987",
       "idTipoPendenza": "SANZIONE",
       "dominio": {
         "idDominio": "01234567890",
         "ragioneSociale": "Comune Dimostrativo",
         "indirizzo": "Piazzale Paolino Paperino",
         "civico": "1",
         "cap": "00000",
         "localita": "Roma",
         "provincia": "RO",
         "nazione": "IT",
         "email": "info@comunedimostrativo.it",
         "pec": "protocollo.generale@pec.comunedimostrativo.it",
         "tel": "00 1234 5678",
         "fax": "00 1234 5678",
         "web": "http://www.comunedimostrativo.it",
         "gln": "8088888000000",
         "logo": "/domini/01234567890/logo",
         "unitaOperative": "/domini/01234567890/unitaOperative",
         "tipiPendenza": "/domini/01234567890/tipiPendenza"
       },
       "stato": "NON_ESEGUITA",
       "causale": "Sanzione CdS n. abc00000",
       "soggettoPagatore": {
         "tipo": "F",
         "identificativo": "RSSMRA30A01H501I",
         "anagrafica": "Mario Rossi"
       },
       "importo": 10.01,
       "dataCaricamento": "2019-10-18",
       "dataValidita": "2019-12-31",
       "dataScadenza": "2020-12-31",
       "tassonomiaAvviso": "Multe e sanzioni amministrative",
       "rpp": "/rpp?idA2A=A2A-DEMO&idPendenza=987",
       "pagamenti": "/pagamenti?idA2A=A2A-DEMO&idPendenza=987"
     }
   ]
 }

Esecuzione del pagamento

Il portale, tramite le informazioni fornite da GovPay o presenti in archivi propri, consente al cittadino di predisporre un carrello di pagamenti dovuti. Una volta terminato, il portale avvia il pagamento

Richiesta

 POST /govpay/frontend/api/pagamento/rs/basic/v2/pagamenti
 Authorization: Basic aWRBMkEtcG9ydGFsZTpwYXNzd29yZA==
 Accept: application/json
 Content-type: application/json"

 {
   "pendenze": [
     {
       "idA2A": "A2A-DEMO",
       "idPendenza": "987"
     }
   ]
 }

Risposta

 HTTP 201 CREATED
 Content-type: application/json

 {
   "id": "1d16d7b741024c6a8a3e3596957482b8",
   "location": "/pagamenti/1d16d7b741024c6a8a3e3596957482b8",
   "redirect": "https://demo.govcloud.it/govpay-ndpsym/wisp/rs/scelta?idSession=18cb852db0f041068b0063d8d580380c",
   "idSession": "18cb852db0f041068b0063d8d580380c"
 }

La URL indicata dal campo redirect dovrà essere utilizzata dal portale per far proseguire l’utente nel pagamento, come previsto dal modello pagoPA.

Visualizzazione Esito del Pagamento

Al termine delle operazioni di pagamento su pagoPA, l’utente viene rediretto al portale dell’ente alla URL fornita a pagoPA in sede di configurazione della Stazione, con il parametro idSession nella queryString. Questo parameto può essere utilizzato per interrogare GovPay sull’esito del pagamento nell’operazione GET /pagamenti/byIdSession/{idSession}:

Richiesta

 GET /govpay/frontend/api/pagamento/rs/basic/v2/pagamenti/byIdSession/18cb852db0f041068b0063d8d580380c
 Authorization: Basic aWRBMkEtcG9ydGFsZTpwYXNzd29yZA==
 Accept: application/json

Risposta

 HTTP 200 OK
 Content-type: application/json

 {
   "autenticazioneSoggetto": "N/A",
   "id": "1d16d7b741024c6a8a3e3596957482b8",
   "nome": "Sanzione CdS n. abc00000",
   "stato": "NON_ESEGUITO",
   "importo": 10.01,
   "idSessionePsp": "18cb852db0f041068b0063d8d580380c",
   "pspRedirectUrl": "https://demo.govcloud.it/govpay-ndpsym/wisp/rs/scelta?idSession=18cb852db0f041068b0063d8d580380c",
   "dataRichiestaPagamento": "2019-10-21T14:16:07.022+0000",
   "rpp": [
     {
       "stato": "RT_ACCETTATA_PA",
       "rpt": { -- OMISSIS RPT --- },
       "rt": { -- OMISSIS RT --- }
       "pendenza": "/pendenze/A2A-DEMO/987"
     }
   ],
   "pendenze": [ -- OMISSIS PENDENZE --- ]
 }

Nella risposta ottenuta l’esito del pagamento è rappresentato dal campo stato con i seguenti possibili valori:

• IN_CORSO
• ESEGUITO
• NON_ESEGUITO
• PARZIALMENTE_ESEGUITO
• RIFIUTATO

In aggiunta si ottiene la lista delle coppie RPT ed RT scambiate con pagoPA e la lista delle pendenze oggetto del pagamento.

Configurazione

Oltre alla Configurazione di base, procedere con le seguenti configurazioni per predisporre l’ambiente necessario alla realizzazione dello scenario descritto:

1. Configurazione del tipo pendenza Deve essere censita una tipologia di pendenza che negli esempi è stata registrata con codice identificativo SANZIONE. Per maggiori dettagli sugli altri parametri di configurazione si faccia riferimento alla sezione Tipi Pendenze.
2. Configurazione dell’ente creditore Il tipo pendenza deve essere associato all’ente creditore. Per i dettagli di configurazione si consulti la sezione Enti Creditori.

Esecuzione

Lo scenario fin qui descritto è stato arricchito di una collection Postman che consente di eseguire autonomamente i passi dello scenario utilizzando come riferimento l”Ambiente Demo di GovPay.

Elenco operazioni presenti nella collection postman

Le operazioni elencate (postman_dovuto1_menu) possono essere eseguite in sequenza al fine di riprodurre i passi già descritti nella sezione di Realizzazione.

Di seguito la sequenza di esecuzione delle operazioni:

• PUT Pendenza: l’operazione prevede l’invio di un messaggio contenente una pendenza con due voci di pagamento (quindi senza la generazione dell’avviso). Per quanto riguarda i parametri:

  • Il primo parametro è l’identificativo dell’applicazione gestionale che inserisce la pendenza. In questo caso si utilizza l’applicazione A2A-DEMO, censita nell’ambiente demo.
  • Il secondo parametro è l’identificativo della pendenza, fornito dall’applicazione. In questo caso l’identificativo viene automaticamente generato tramite uno script che utilizza numeri casuali.

  L’operazione si ritiene conclusa con successo se restituisce il codice HTTP 201 (postman_dovuto1_put_response).

Risposta ottenuta dalla PUT Pendenza

• GET Posizione Debitoria: l’operazione, eseguita tipicamente dall’applicazione corrispondente al portale di pagamento, prevede la ricerca delle pendenze filtrando rispetto all’identificativo dell’utente debitore. Tra le pendenze restituite ci sarà quella caricata al passo precedente (postman_dovuto1_getposizione_response).

Risposta ottenuta dalla GET Posizione Debitoria

• POST Pagamento: l’operazione, eseguita in seguito alla conferma dell’utente per effettuare il pagamento, prevede che il body contenga i seguenti elementi:

  • idA2A: identificativo del gestionale che ha caricato la pendenza
  • idPendenza: identificativo della pendenza che si vuol pagare

  L’operazione si ritiene conclusa correttamente se viene restituito il codice HTTP 201 (postman_dovuto1_post_pagamento). La risposta ottenuta contiene i seguenti dati:

  • id: identificativo del pagamento creato
  • location: uri per la visualizzazione del dettaglio del pagamento
  • redirect: url per il reindirizzamento del browser utente verso il prossimo passo del flusso di pagamento
  • idSession: identificativo della sessione assegnato da pagoPA

Operazione POST Pagamento

• GET Pagamento: questa operazione viene eseguita dal portale di pagamento, al termine dell’operazione di versamento da parte dell’utente, per verificare l’esito dell’operazione e consentire lo scaricamento della ricevuta telematica (postman_dovuto1_get_pagamento). L’operazione utilizzata per il recupero del dettaglio del pagamento è quella che prevede la ricerca basata sull’identificativo di sessione assegnato da pagoPA. Tale valore viene estratto dalla risposta alla POST del passo precedente ed inserito nella richiesta corrente.

Operazione GET Pagamento

Pagamento spontaneo ad iniziativa ente

In questo scenario il pagamento ha origine per iniziativa dell’utente/cittadino che, per ottenere un determinato servizio (ad esempio una licenza di pesca), procede con l’immissione delle informazioni relative alla pendenza e richiede di procedere con il versamento attraverso il portale dei pagamenti dell’ente creditore.

Lo scenario si articola nei seguenti passaggi:

1. L’utente si collega al portale dell’ente creditore e, tipicamente tramite la compilazione di un form, fornisce tutti i dettagli della pendenza che intende pagare. In questa fase non rientra il coinvolgimento di GovPay. Quest’ultimo entra in gioco a partire dalla successiva fase di esecuzione del pagamento.
2. Quando l’utente conferma la volontà di procedere con il pagamento, il portale avvia la transazione tramite GovPay e riceve le informazioni per procedere con il flusso di pagamento. Questa fase include la selezione del PSP e l’esecuzione sul medesimo del versamento.
3. Ultimato il versamento, l’utente viene rediretto nuovamente sul portale dell’ente per visualizzare l’esito dell’operazione ed ottenere la ricevuta telematica.

Le fasi che andiamo a descrivere per questo scenario sono le seguenti:

1. La Realizzazione, che prevede:

   • L’uso delle API Pagamento per l’avvio del pagamento dopo aver acquisito i dati della pendenza dal portale
   • La ricezione della notifica di pagamento da GovPay tramite un servizio esposto dal portale ente (modalità PUSH), oppure l’acquisizione dell’esito, da parte del portale ente, in modalità PULL sempre tramite l”API Pagamento

2. La Configurazione di GovPay per supportare lo scenario descritto utilizzando il cruscotto di gestione.

Realizzazione

In questo scenario, Modello 1 - Pagamento spontaneo ad iniziativa ente, il cittadino procede tramite il portale dell’ente creditore alla definizione della pendenza e quindi procede al relativo pagamento sempre dal portale. I passi in cui il cittadino inserisce i dati e compone la pendenza da pagare non coinvolgono GovPay e non sono quindi esposti in questo scenario. Successivamente, con la conferma del cittadino pagatore, si avvia il processo di pagamento tramite GovPay con l’attuazione dei seguenti passaggi che saranno descritti di seguito:

• Avvio Pagamemto

  Il portale dell’ente creditore, dopo aver raccolto le informazioni necessarie alla formazione della pendenza, invia la richiesta di pagamento a GovPay.

• Acquisizione Esito

  il portale dell’ente creditore, al termine del flusso di navigazione che ha portato al completamento del versamento, acquisisce l’esito da visualizzare e la ricevuta telematica da mettere a disposizione per il download.

Avvio Pagamento

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 (i cui dati sono stati acquisiti dal portale).

Vediamo di seguito un esempio di invocazione della POST /pagamenti

Richiesta POST /pagamenti

POST /pagamenti
{
    "urlRitorno":"https://pagamenti.ente.it/pagopa/",
    "pendenze":
    [
        {
            "idA2A":"GestPag",
            "idPendenza":"1527844941778",
            "idDominio":"01234567890",
            "causale":"Prestazione n.1527844941778",
            "soggettoPagatore":
            {
                "tipo":"F",
                "identificativo":"RSSMRA30A01H501I",
                "anagrafica":"Mario Rossi"
            },
            "importo":45.01,
            "voci":
            [
                {
                        "idVocePendenza":"1527844941778-1100",
                        "importo":45.01,
                        "descrizione":"Compartecipazione alla spesa per prestazioni sanitarie (ticket)",
                        "tipoContabilita":"ALTRO",
                        "codiceContabilita":"0501100TS/",
                        "ibanAccredito":"IT02L1234512345123456789012"
                }
            ]
        }
    ]
}

Risposta POST /pagamenti

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

In assenza di errori, la risposta ottenuta contiene le seguenti informazioni:

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

Una volta confermato il corretto avvio del pagamento, il portale effettua la redirezione dell’utente sulla URL ottenuta come redirect, per procedere con la fase di esecuzione del versamento.

Acquisizione Esito

Quando l’utente ha completato l’esecuzione del versamento, tramite il PSP, torna automaticamente sul portale dove quest’ultimo gli visualizza l’esito complessivo dell’operazione. 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.

GovPay può comunicare l’esito del pagamento con le seguenti modalità:

1 - Se in configurazione è stato fornito un riferimento ad un servizio per la ricezione delle notifiche, GovPay invia una notifica di pagamento comprensiva di RPT, RT e il dettaglio delle riscossioni (quest’ultimo solo nel caso di esito positivo)

Notifica di pagamento inviata da GovPay all’ente creditore (modalità PUSH)

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

2 - Se l'ente non prevede l'esposizione di un servizio per la ricezione delle notifiche di pagamento, può utilizzare il metodo PULL e quindi interrogare di propria iniziativa GovPay per ottenere l'esito del pagamento. In questo caso può utilizzare la URL ottenuta nella risposta dell'avvio pagamento con il campo **location**:

Richiesta dettaglio del pagamento (modalità PULL)

GET /pagamenti/e4518f13ecc14381a689c770449f3711

{
    "id":"e4518f13ecc14381a689c770449f3711",
    "nome":"Prestazione n.1527844941778",
    "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=6966661822b14c078191f9e251b1038a",
    "contoAddebito":null,
    "dataEsecuzionePagamento":null,
    "credenzialiPagatore":null,
    "soggettoVersante":
    {
        --[OMISSIS]--
    },
    "autenticazioneSoggetto":null,
    "lingua":"IT",
    "pendenze":
    [
        {
            "causale":"Prestazione n.1527844941778",
            "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.1527844941778",
            "tassonomiaAvviso":"Ticket e prestazioni sanitarie",
            "idA2A":"GestPag",
            "idPendenza":"1527844941778",
            "dominio":
            {
                --[OMISSIS]--
            },
            "unitaOperativa":null,
            "stato":"ESEGUITA",
            "segnalazioni":null,
            "rpp":"/rpp?idA2A=GestPag&idPendenza=1527844941778",
            "pagamenti":"/pagamenti?idA2A=GestPag&idPendenza=1527844941778"
        }
    ],
    "rpp":
    [
        {
            "stato":"RT_ACCETTATA_PA",
            "dettaglioStato":null,
            "segnalazioni":null,
            "rpt":
            {
                --[OMISSIS]--
            },
            "rt":
            {
                --[OMISSIS]--
            },
            "pendenza":"/pendenze/GestPag/1527844941778"
        }
    ]
}

Configurazione

Oltre alla Configurazione di base, procedere con le seguenti configurazioni per predisporre l’ambiente necessario alla realizzazione dello scenario descritto:

1. Configurazione del tipo pendenza Deve essere censita una tipologia di pendenza per il pagamento spontaneo da supportare, che negli esempi è stata registrata con codice identificativo TICKET. Per maggiori dettagli sugli altri parametri di configurazione si faccia riferimento alla sezione Tipi Pendenze.
2. Configurazione dell’ente creditore Il tipo pendenza deve essere associato all’ente creditore. Per i dettagli di configurazione si consulti la sezione Enti Creditori.

Pagamento di un dovuto ad iniziativa PSP

In questo scenario la pendenza da pagare ha origine nel contesto dell’ente, che si connota come creditore nei confronti di un determinato cittadino. L’ente creditore genera l”Avviso di Pagamento che viene consegnato al debitore, tramite il quale egli si reca presso le strutture del PSP (sportello, ATM, Home banking, Mobile APP, …) per l’esecuzione del versamento.

Lo scenario si articola complessivamente nelle seguenti fasi:

1. L’Ente Creditore, alla predisposizione di una nuova pendenza, stampa l’Avviso di Pagamento pagoPA ad essa associato e lo 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.

Le fasi che andiamo a descrivere per questo scenario sono le seguenti:

1. La Realizzazione, che prevede:
   • L’uso delle API Pendenze di GovPay per l’integrazione con i sistemi verticali gestionali e consentire il caricamento delle pendenze nell’archivio dei pagamenti in attesa e generare l’avviso di pagamento.
   • L’uso delle API Verifica e Notifica, esposte dall’ente, per consentire a GovPay l’interrogazione del gestionale dell’ente nei casi in cui sia necessario accedere ai dati della pendenza in corso di pagamento. Le stesse API sono successivamente usate da GovPay per notificare all’ente l’avvenuto pagamento.
2. La Configurazione di GovPay per supportare lo scenario descritto utilizzando il cruscotto di gestione.

Realizzazione

In questo scenario, Modello 3 - Pagamento ad Inziativa PSP, il cittadino debitore, in possesso dell’avviso di pagamento fornitogli dall’ente creditore, effettua il pagamento tramite il PSP che ha scelto.

Ai fini dell’integrazione tra GovPay e l’Ente Creditore, per questo scenario, individuiamo i seguenti passaggi chiave:

• Stampa Avviso di Pagamento

  L’ente creditore genera l’avviso di pagamento da fornire al cittadino debitore.

• Verifica della Pendenza

  Il PSP chiede l’aggiornamento dei dati di pagamento a GovPay. Nei casi in cui GovPay non disponga della pendenza, o se la data attuale è compresa tra quella di validità e quella di scadenza della pendenza, si procede con l’interrogazione del sistema di gestione dei pagamenti dell’ente, prima di autorizzare le operazioni di riscossione dell’importo dovuto.

• Notifica del Pagamento

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

Stampa Avviso di Pagamento

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. Distinguiamo:

• Caso Alimentazione Pendenza su GovPay

  È 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, nel caso vengo valorizzato a true anche il parametro avvisaturaDigitale, si istruisce GovPay 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.

• Caso Solo generazione avviso senza caricamento pendenza

  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.

Il seguente esempio mostra l’invocazione della PUT /pendenze/{idA2A}/{id_pendenza} per caricare la pendenza con la restituzione dell’avviso di pagamento sulla risposta. Si assume che l’applicazione sia stata regitrata con identificativo GestPag e la pendenza abbia id ABC-001.

Richiesta PUT /pendenze/{idA2A}/{id_pendenza}

PUT https://demo.govcloud.it/govpay/backend/api/pendenze/rs/basic/v2/pendenze/GestPag/ABC-001?stampaAvviso=true
{
        "idDominio":"01234567890",
        "idTipoPendenza":"TICKET",
        "soggettoPagatore":
        {
                "tipo":"F",
                "identificativo":"RSSMRA30A01H501I",
                "anagrafica":"Mario Rossi",
                "email":"mario@dimostrativo.it"
        },
        "causale":"Prestazione n.ABC-001",
        "importo":45.01,
        "voci":
        [
                {
                        "idVocePendenza":"ABC-001-1100",
                        "importo":45.01,
                        "descrizione":"Compartecipazione alla spesa per prestazioni sanitarie (ticket)",
                        "ibanAccredito":"IT02L1234512345123456789012",
                        "tipoContabilita":"ALTRO",
                        "codiceContabilita":"1100"
                }
        ]
}

Risposta PUT /pendenze/{idA2A}/{id_pendenza}

HTTP 200 OK
{
        "idDominio":"01234567890",
        "numeroAvviso":"001110000000000164"
        "pdf":"...BASE64..."
}

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. Ci sono due scenari in cui GovPay esegue la richiesta di verifica:

1. Se la pendenza associata all’avviso non è presente nell’archivio dei pagamenti in attesa
2. Se la pendenza è presente in archivio, ma la data di validità comunicata risulta 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.

GovPay interroga il gestionale dell’ente, per verificare gli estremi della pendenza da pagare, tramite l’operazione GET /avvisi/{idDominio}/{numeroAvviso}. I riferimenti dell’avviso generato al passo precedente sono:

• idDominio: 01234567890
• numeroAvviso: 001110000000000164

Verifica Pendenza con GET /avvisi/{idDominio}/{numeroAvviso}

GET /avvisi/01234567890/001110000000000164

HTTP 200 OK
{
    "idDominio":"01234567890",
    "causale":"Prestazione n.ABC-001",
    "soggettoPagatore":
    {
                "tipo":"F",
                "identificativo":"RSSMRA30A01H501I",
                "anagrafica":"Mario Rossi"
    },
    "importo":45.01,
    "numeroAvviso":"001110000000000164",
    "dataValidita":"2018-06-01",
    "dataScadenza":"2018-12-31",
    "tassonomiaAvviso":"Ticket e prestazioni sanitarie",
    "voci":
    [
                {
                    "idVocePendenza":"ABC-001-1100",
                    "importo":45.01,
                    "descrizione":"Compartecipazione alla spesa per prestazioni sanitarie (ticket)",
                    "codiceContabilita":"1100",
                    "ibanAccredito":"IT02L1234512345123456789012",
                    "tipoContabilita":"ALTRO"
                }
    ],
    "idA2A":"GestPag",
    "idPendenza":"ABC-001",
    "stato":"NON_ESEGUITA"
}

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}.

Notifica del Pagamento con POST /pagamenti/{idDominio}/{iuv}

POST /pagamenti/01234567890/000000000000141
{
    "idA2A":"GestPag",
    "idPendenza":"ABC-001",
    "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":"01234567890",
                    "iuv":"000000000000141",
                    "iur":"idRisc-152784362114159",
                    "indice":1,
                    "pendenza":"/pendenze/GestPag/ABC-001",
                    "idVocePendenza":"ABC-001-1100",
                    "rpp":"/rpp/01234567890/000000000000141/1871148690",
                    "stato":null,
                    "tipo":null,
                    "importo":45.01,
                    "data":"2018-06-01",
                    "commissioni":null,
                    "allegato":null,
                    "incasso":null
                }
    ]
}

Si noti 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 medesima.

Configurazione

Oltre alla Configurazione di base, sono necessarie le seguenti configurazioni per predisporre l’ambiente necessario alla realizzazione dello scenario descritto:

1. Configurazione del tipo pendenza Deve essere censita una tipologia di pendenza di tipo Dovuto, che negli esempi è stata registrata con codice identificativo TICKET. Per maggiori dettagli sugli altri parametri di configurazione si faccia riferimento alla sezione Tipi Pendenze.
2. Configurazione dell’ente creditore Il tipo pendenza deve essere associato all’ente creditore. Per i dettagli di configurazione si consulti la sezione Enti Creditori.

Riconciliazione dei pagamenti con la tesoreria

Con l’esecuzione del pagamento, il debitore acquisisce la ricevuta telematica e l’ente le somme versate che gli vengono accreditate dal PSP. Periodicamente la banca tesoriera fornisce all’ente creditore la documentazione di rendicontazione delle somme accreditate e sarà compito della ragioneria dell’ente stesso riconciliare tali elementi con i singoli pagamenti pagoPA cui fanno riferimento.

Lo scenario si basa sul seguente passaggio:

1. Riconciliazione Entrate

   A partire dal Giornale di Cassa, fornito dalla banca tesoriera, il sistema amministrativo contabile dell’ente creditore registra le entrate «pagoPA» e ottiene la riconciliazione dei movimenti bancari con i pagamenti di origine.

La descrizione dello scenario si compone dei seguenti elementi:

1. La Realizzazione, che descrive l’integrazione tra il gestionale di contabilità, che effettua la riconciliazione, e GovPay:

   • La riconciliazione degli incassi in banca tesoriera avviene con la chiamata a POST /riconciliazioni/{idDominio}

2. La Configurazione di GovPay per supportare lo scenario descritto.

Realizzazione

In questo scenario il Sistema di Gestione Contabile dell’ente creditore riconcilia i movimenti di accredito, presenti nel Giornale di Cassa fornito dalla banca tesoriera, con i singoli pagamenti effettuati su pagoPA. L’applicativo di contabilità effettua l’operazione di riconciliazione utilizzando l” API Riconciliazione.

Riconciliazione Entrate

L’operazione per la riconciliazione delle entrate è POST /riconciliazioni/{idDominio}. Qui di seguito vediamo un esempio di chiamata:

Registrazione di un movimento di entrata (Richiesta)

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

Il messaggio di richiesta prevede che vengano forniti i riferimenti al movimento sul Giornale di Cassa. In particolare sono obbligatori i seguenti dati:

• importo

  L’importo del movimento

• sct

  L’identificativo dell’operazione bancaria SCT

• uno tra i seguenti elementi identificativi:

  • iuv

    L’identificativo del singolo versamento pagoPA

  • idFlusso

    L’identificativo del flusso di versamento (riversamenti multipli)

  • causale

    La causale riportata per l’operazione (GovPay è in grado di estrarre autonomamente gli identificativi necessari). Nell’esempio è stata utilizzata questa modalità.

Registrazione di un movimento di entrata (Risposta)

HTTP 201 CREATED
{
    "id": "12345",
    "causale": "/PUR/LGPE-RIVERSAMENTO/URI/2017-01-01ABI00000011234",
    "importo": 100.01,
    "dataValuta": "2020-12-31",
    "dataContabile": "2020-12-31",
    "sct": "2017-01-01ABI00000011234",
    "idDominio": "01234567890",
    "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"
            }
        }
    ]
}

La risposta all’operazione invocata presenta un messaggio con la riconciliazione del movimento fornito in input con l’elenco delle riscossioni corrispondenti. Con queste informazioni il Gestionale dell’ente creditore è in grado di effettuare la chiusura contabile di ogni pendenza di pagamento.

Configurazione

Oltre alla Configurazione di base, procedere con le seguenti configurazioni per predisporre l’ambiente necessario alla realizzazione dello scenario descritto:

1. Autorizzazione dell’applicazione di contabilità

   Affinché vengano accettate le richieste inviate dall’applicativo di contabilità dell’ente creditore, è necessario che:

   • L’applicazione registrata su GovPay sia associata al dominio indicato nelle operazioni di riconciliazione
   • L’applicazione sia autorizzata all’invocazione delle API Riconciliazione

   Per maggiori dettagli sulla configurazione delle applicazioni fare riferimento a Applicazioni.

How-To

Pagamenti rateali o ridotti

In questa sezione vengono indicate le linee guida per gestire il caso di forme di pagamento rateizzate o in forma ridotta. L’obiettivo è quello di ottenere da GovPay le stampe degli avvisi di pagamento previste da pagoPA per questi scenari, mirati a ridurre il numero di pagine da stampare e postalizzare all’utente finale.

Pagamenti rateizzati

In caso di rateizzazione dei pagamenti, la specifica pagoPA per l’avvisatura analogica prevede nella prima pagina il pagamento in un’unica soluzione seguita dalle rate stampate in gruppi da due o tre pagamenti per pagina.

Per realizzare questo scenario occorre associare le pendenze che determinano il pagamento in unica soluzione e le pendenze corrispondenti alle rate al medesimo documento (o ruolo/cartella/fascicolo, a seconda della terminologia a cui si è abituati). Per farlo è sufficiente valorizzare in ciascuna pendenza l’elemento documento:

Esempio di pagamento rateale

{
  ...
  "documento": {
    "identificativo": "IMU-12345",
    "descrizione": "IMU 2020",
    "rata": 2
  }
  ...
}

Di seguito le indicazioni sulla valorizzazione dei campi:

• identificativo: deve essere univoco per l’ente creditore a cui afferisce la pendenza
• descrizione: viene utilizzata per la visualizzazione sulle console di gestione
• rata: numero di rata nel caso di pendenza relativa ad una rata. Non valorizzare nel caso di pagamento in soluzione unica.

Le medesime informazioni possono essere indicate anche nel caricamento pendenze tramite tracciato CSV.

Una volta caricate le posizioni, è possibile acquisire la stampa degli avvisi del documento con l’operazione GET /documenti/{idDominio}/{numeroDocumento}/avvisi

Pagamento in forma ridotta

Alcune tipologie di pendenza prevedono il pagamento in forma ridotta, come nel caso delle sanzioni del codice della strada. Il template degli avvisi pagoPA prevede l’indicazione entro XX giorni o oltre XX giorni per gestire questa casistica.

Per realizzare questo scenario è sufficiente le varie pendenze allo stesso documento come nel caso dei Pagamenti rateizzati visti in precedenza, utilizzando la seguente sintassi:

Esempio di pagamento ridotto

{
  ...
  "documento": {
    "identificativo": "CDS-12345",
    "descrizione": "Sanzione CDS",
    "soglia": {
      "tipo": "ENTRO",
      "giorni": 30
  }
  ...
}

Una volta caricate le posizioni, è possibile acquisire la stampa degli avvisi del documento con l’operazione GET /documenti/{idDominio}/{numeroDocumento}/avvisi

Marca da Bollo Telematica

La piattaforma pagoPA supporta la specifica @e.bollo per il pagamento della Marca da Bollo Telematica. In GovPay questo servizio è realizzabile in maniera analoga ad un qualsiasi pagamento ad iniziativa ente, compilando opportunamente la richiesta di pagamento.

Configurazione

Per autorizzare il pagamento della Marca da Bollo Telematica in GovPay è sufficiente abilitare il tipo tributo «Marca da Bollo» nella configurazione dell’Ente Creditore che ne richiede il pagamento.

Esecuzione del pagamento

Per avviare il pagamento di una Marca da Bollo Telematica è sufficiente valorizzare opportunamente una delle voci della pendenza dell’elemento voci:

Esempio di pagamento Imposta di bollo

{
  ...
  "voci":
  [
     {
     "idVocePendenza": "12345_1",
     "importo": 16.00,
     "descrizione": "MBT per certificato anagrafico prot 123456",
     "tipoBollo": "Imposta di bollo",
     "hashDocumento": "a/CWqtFtCEyA/ymBySahGSaqKMiak5mlX3BoX0jupy8=",
     "provinciaResidenza": "RO"
     }
  ]
  ...
}

Di seguito alcune informazioni aggiuntive per la valorizzazione dei campi:

• importo: importo della marca da bollo. Al momento della scrittura, pagoPA supporta solo il taglio da 16€
• hashDocumento: da specifiche pagoPA «Contiene l’impronta informatica (digest) del documento informatico cui è associata la marca da bollo digitale. L’algoritmo di hash da utilizzare è SHA-256. La stringa di 256 bit (32 ottetti) risultato di tale algoritmo deve essere convertito in base64»
• provinciaResidenza: da specifiche pagoPA «Sigla automobilistica della provincia di residenza del soggetto pagatore.»

In caso di successo, la Ricevuta Telematica inviata da pagoPA ha allegato il tracciato XML della Marca da Bollo acquistata, contenente l’impronta del documento associato firmata digitalmente per eventuali verifiche.

Esempio di Marca da Bollo

    <?xml version="1.0" encoding="UTF-8"?>
    <marcaDaBollo xmlns="http://www.agenziaentrate.gov.it/2014/MarcaDaBollo" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
       <PSP>
          <CodiceFiscale>99999999999</CodiceFiscale>
          <Denominazione>Banco di Ponzi S.p.A.</Denominazione>
       </PSP>
       <IUBD>5079389115013</IUBD>
       <OraAcquisto>2021-07-27T11:48:02+0200</OraAcquisto>
       <Importo>16.0</Importo>
       <TipoBollo>01</TipoBollo>
       <ImprontaDocumento>
          <DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
          <ns2:DigestValue>a/CWqtFtCEyA/ymBySahGSaqKMiak5mlX3BoX0jupy8=</ns2:DigestValue>
       </ImprontaDocumento>
       <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
          ....
       </Signature>
    </marcaDaBollo>

Informazioni aggiuntive

Gli importi riscossi per il pagamento delle Marche da Bollo non saranno accreditati su un conto dell’Ente Creditore, ma su un conto dell’Agenzia delle Entrate pertanto non saranno soggetti a riconciliazione.

Al momento della scrittura nessun PSP supporta il pagamento ad iniziativa PSP della Marca da Bollo, pertanto un Avviso pagoPA associato ad una Marca da Bollo Telematica risulterà non pagabile.

Avvisi pagoPA bilingue

La piattaforma GovPay supporta la possibilità di stampare gli Avvisi pagoPA in formato bilingue fornendo l’indicazione della lingua secondaria desiderata come parametro della pendenza.

Lingua secondaria nelle richieste json

E” possibile indicare la lingua secondaria come proprietà della pendenza:

Esempio di pagamento Imposta di bollo

{
  ...
  "proprieta": {
        "linguaSecondaria": "de",
        "linguaSecondariaCausale": "Zahlungsgegenstand"
  }
}

Lingua secondaria nel tracciato CSV

E” possibile indicare la lingua secondaria nel tracciato CSV valorizzando opportunamente il campo linguaSecondaria. Consultare la sezione specifica per maggiori informazioni