Logo

Status

Introduzione

Lo scopo del presente documento è semplificare l'integrazione con il sistema pagoPA per gli Enti Creditori (EC) ed offrire ad essi alcune best practices per l'integrazione degli attuali scenari di pagamento sulla piattaforma pagoPA stessa.

Le 3 fasi riportate nel documento evidenziano come procedere nell'attivazione del servizio di Pagamento e indicano come delegare e/o semplificare gran parte delle attività previste per la realizzazione del colloquio.

Nel capitolo "Interazioni con il toolkit pagoPA" descriveremo come queste fasi possono essere realizzate e/o semplificate mediante le procedure messe a disposizione dal toolkit-OS PagoPA.

Infine, nell'ultima parte del documento, verranno descritti dei casi d'uso reali, quindi verrà descritto come tutte le regole viste nei capitoli precedenti possono essere utilizzate per pagamenti di tributi o altre tipologie di pagamento.

Linee guida

Fase 1 - Caricamento e creazione delle Posizioni Debitorie

Il primo step per poter rendere una pendenza pagabile tramite il sistema pagoPA è quello di individuare le informazioni necessarie per effettuare il pagamento e creare un archivio dei pagamenti in attesa (APA) di essere pagati.

Tale archivio sarà consultabile dal Nodo dei Pagamenti SPC tramite le primitive descritte nelle Linee Guida Specifiche Attuative del Nodo dei Pagamenti-SPC (SANP), ed esso conterrà tutte le Posizioni Debitorie che l'Ente ha deciso di emettere e rendere pagabili.

Ad ogni pendenza viene associato un Identificativo Univoco del Versamento (IUV) a livello di Ente.

La scelta dell'algoritmo di generazione dello IUV dipende da diversi fattori:

  1. Modelli di pagamento attivati (Modello 1, Modello 3)
  2. Numero di partner tecnologici attivi per l'Ente

E' necessario consultare le Specifiche attuative dei codici identificativi di versamento, riversamento e rendicontazione (SACI) e adottare il tipo di algoritmo idoneo all'organizzazione dell'EC.

Altro aspetto importante è quello di garantire l'univocità del codice IUV generato per l'EC. Tale vincolo può essere garantito utilizzando i meccanismi messi a disposizione dai framework che si intende utilizzare per la realizzazione della propria piattaforma, ad esempio delegandolo ad un Sistema di Gestione di Base Dati tramite l'utilizzo di DB Sequences. Inoltre, è consigliabile utilizzare semplici strategie al fine di evitare l'esaurimento della numerazione dello IUV quali, ad esempio, l'utilizzo dell'anno corrente per le prime due cifre del codice IUV base in modo da azzerare la numerazione ogni anno.

Numerosi Prestatori di Servizi di Pagamento (PSP) al momento della richiesta di pagamento, tramite un numero avviso, effettuano dei controlli di validità sul codice IUV, pertanto è necessario porre particolare attenzione al calcolo del Check Digit, seguendo scrupolosamente le indicazioni fornite nelle SACI di riferimento.

Generato il codice identificativo univoco, la Posizione Debitoria può essere inserita dell'Archivio dei Pagamenti in Attesa. Al fine di garantire la correttezza di tali dati, su di essi posso essere eseguiti dei controlli di validazione.

Di seguito vengono riportati alcuni controlli che dovrebbero essere eseguiti prima dell'inserimento di una posizione debitoria in APA:

[a-zA-Z0-9_\.\+\-]+@[a-zA-Z0-9\-]+(\.[a-zA-Z0-9\-]+)*
[a-zA-Z]{????2,2}????[0-9]{????2,2}????[a-zA-Z0-9]{????1,30}????
[A-Z]{????6,6}????[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{????3,3}????){????0,1}????
[0129]{1}/\S{3,138}

Potrebbe essere utile corredare la Posizione Debitoria con un campo significativo dell'EC, ad esempio un campo ID_TENANT contenente il Numero della Fattura generata dal proprio Gestionale di Fatturazione.

Inoltre è importante inserire un valore chiaro e non ambiguo nel campo Causale del pagamento, poiché questo dato non solo verrà visualizzato dall'utente quando effettuerà il pagamento, ma sarà anche riportato nell'intestazione dell'Avviso di Pagamento inviato al cittadino.

Infine, il Pagamento Atteso può contenere al suo interno fino a 5 singoli versamenti per mantenere la corrispondenza con le strutture RPT ed RT definite nelle Linee Guida SANP. Tale proprietà diventa idonea nel caso in cui è necessario definire pagamenti di tipo multi-beneficiario, ovvero per i quali è necessario riversare l'importo della pendenza suddiviso per Beneficiari diversi.

Dopo aver effettuato tutti i controlli di validità ed obbligatorietà dei campi costituenti una Posizione Debitoria, si può procedere al salvataggio della pendenza in APA.

Fase 2 - Generazione dell'Avviso di Pagamento

Al fine di uniformare la produzione degli avvisi analogici, PagoPA S.p.A. mette a disposizione un documento tecnico di riferimento per la produzione della stampa dell'Avviso di Pagamento.

Queste istruzioni sono riportate nel documento Guida Tecnica Avviso Analogico v2.2.1

L'avviso analogico è composto da una pagina principale, di seguito descritta, e ulteriori pagine opzionali che possono essere prodotte nel caso in cui l'EC decida di rateizzare il debito al cittadino.

La pagina principale è composta da diverse sezioni:

La zona tecnica per i pagamenti presso Poste Italiane è facoltativa e dovrà essere valorizzata solo se l'EC ha un conto corrente postale sul quale vuole ricevere il riversamento dei pagamenti.

Inoltre, se si vuole generare tale sezione, è necessario ottenere da Poste Italiane l'autorizzazione alla stampa in proprio (maggiori approfondimenti qui). Per ottenere l'autorizzazione sarà necessario produrre 5 stampe di test ed inviarle a Poste per richiedere un codice di autorizzazione. Tale codice di autorizzazione dovrà poi essere stampato all'interno dell'avviso analogico seguendo le istruzioni riportate nel documento di specifiche tecniche di cui sopra.

Fase 3 - Modalità di pagamento

La terza fase consiste nel pagamento vero e proprio della pendenza da parte del cittadino; di seguito verranno esposti i due modelli di pagamento che possono essere messi a disposizione dall'EC ai cittadini.

Nel primo metodo di pagamento (Modello 1), il pagamento viene attivato direttamente da una piattaforma web messa a disposizione dall'EC. Sul portale dell'EC sarà adibita una pagina che illustrerà all'utente il modello di pagamento utilizzato e fornirà le informazioni per la fruizione dello stesso.

Il pagamento Modello 1 può essere attivato partendo da uno IUV già caricato sull'APA dell'Ente, quindi in questo caso il pagamento è atteso, oppure può essere inserito dall'utente pagatore in maniera facoltativa a partire dai dati in proprio possesso, quindi il pagamento è spontaneo.

Nel secondo caso il pagamento non è atteso dall'EC, ma viene effettuato a seguito di una richiesta di un servizio da parte del cittadino (ad esempio la richiesta di una licenza di pesca e caccia, una richiesta di un bollino verde per l'installazione di una caldaia, etc).

Di seguito viene riportato il workflow, che l'EC deve implementare per mettere a disposizione del cittadino il pagamento online della pendenza tramite il Modello 1:

  1. L'EC genera un codice IUV, secondo le specifiche pagoPA
  2. L'EC crea la Posizione Debitoria assegnando il codice IUV appena generato
  3. Il cittadino si collega al portale dell'EC (generalmente accedendo alla propria area privata) ed attiva il pagamento
  4. L'EC invia verso il Nodo dei Pagamenti SPC tutti i dati del pagamento tramite la RPT
  5. Il Nodo dei Pagamenti SPC in risposta fornisce il link con il quale l'EC, tramite una redirect, visualizza al pagatore il WISP (Wizard Interattivo di Scelta del Prestatore di Servizi di Pagamento), permettendo quindi l'esecuzione del pagamento
  6. Il Nodo dei Pagamenti SPC, al termine del pagamento, informa l'EC dell'esito del pagamento
  7. L'EC riceve la RT (Positiva/Negativa) e aggiorna lo stato del Pagamento Atteso sul proprio sistema interno
  8. Il cittadino può visualizzare e stampare la Ricevuta Telematica.

Nel Modello 3, invece, l'attivazione non avviene sul portale dell'EC, ma avviene direttamente sul PSP (Banche, ATM, Tabaccaio, Ricevitorie Sisal, Home Banking, etc), nonché sull'app IO.

Infatti il cittadino, attraverso i canali telematici o recandosi presso un qualsiasi punto fisico del PSP, attiva il pagamento tramite il Numero Avviso che gli è stato precedentemente comunicato dall'EC tramite l'Avviso di Pagamento.

Quando il cittadino inserisce o comunica il Numero Avviso per effettuare il pagamento, vengono attivati una serie di controlli per verificare la pagabilità della pendenza.

Di seguito viene riportato nel dettaglio il workflow di un pagamento tramite Modello 3:

  1. L'EC genera un codice IUV, secondo le specifiche pagoPA
  2. L'EC crea la Posizione Debitoria assegnandole il codice IUV appena generato
  3. L'EC stampa ed invia al cittadino l'Avviso di Pagamento analogico contenente tutti i dati necessari per effettuare il pagamento
  4. Il cittadino si reca presso un PSP ed attiva il pagamento
  5. Il Nodo dei Pagamenti SPC verifica lo stato del pagamento nell'APA dell'EC, verificandone la pagabilità
  6. Se la pendenza risulta pagabile, il PSP ne richiede la RPT e procede alla riscossione del debito verso il cittadino
  7. L'EC invia verso il Nodo dei Pagamenti SPC tutti i dati del pagamento tramite la RPT
  8. Il Nodo dei Pagamenti SPC invia all'EC la Ricevuta Telematica da archiviare

Un punto molto delicato nella gestione del pagamento Modello 3 è rappresentato dall'invio della RPT verso il Nodo dei Pagamenti SPC, poiché il mancato invio della suddetta provoca la generazione di un pagamento c.d. "Esito 9" (pagamento in assenza di RT) in fase di rendicontazione, che necessita di una gestione straordinaria rispetto alla gestione ordinaria dei pagamenti c.d. "Esito 0" (pagamenti standard con presenza della RT).

Un modo per poter evitare la generazione di un pagamento Esito 9 è quello di utilizzare dei sistemi di retry per l'invio delle RPT che, a causa di eventuali anomalie, non potrebbero non essere state correttamente inviate al Nodo dei Pagamenti SPC.

Oss: mediante il nuovo Modello di pagamento presso il PSP con Ente multi-beneficiario verranno risolte a monte parte delle precedenti problematiche.

Tutti i messaggi scambiati con il Nodo dei Pagamenti SPC tramite le primitive messe a disposizione da pagoPA devono essere scrupolosamente tracciate e archiviate sulla propria Base Dati, per soddisfare eventuali richieste di verifica su anomalie o richieste di controllo sui pagamenti.

Inoltre pagoPA richiede l'implementazione di un Giornale degli Eventi, descritto in maniera approfondita nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC (SANP), che può essere utilizzato da un Tavolo Operativo in caso di verifiche sui pagamenti.

Interazioni con il toolkit pagoPA

Modello 1 - Interazioni con il toolkit pagoPA

Di seguito viene riportato lo schema con la sequenza delle chiamate per un pagamento Modello 1, pagamenti attivati presso l'EC.

Lo schema utilizza il toolkit pagoPA, messo a disposizione degli EC per lo sviluppo della propria piattaforma di pagamento.

  1. L'EC utilizza il modulo di Generazione codice IUV, inoltrando i valori assegnati da PagoPA in fase di censimento sul Portale delle Adesioni; tale modulo restituisce il valore dello IUV, da cui è ottenibile il corrispondente Numero Avviso.

  2. L'EC inoltra al modulo di Generazione Pagamento Atteso tutte le informazioni necessarie per la creazione di una Posizione Debitoria; tale modulo restituisce un oggetto del tipo "Pagamento Atteso". L'EC può utilizzare l'output ricevuto per effettuare un salvataggio sulla propria Base Dati.

  3. Dopo che è stata creata la Posizione Debitoria, il cittadino può effettuare il pagamento tramite le funzionalità messe a disposizione dall'EC sul proprio portale web.

  4. Nel momento in cui il cittadino decide di attivare il pagamento, l'EC inoltra l'oggetto "PagamentoAtteso" al modulo di Generazione della RPT.

  5. Il modulo di Generazione della RPT restituisce la RPT, anche in formato XML, generata secondo quanto indicato nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC (SANP).

  6. L'EC inoltra al Nodo dei Pagamenti SPC la RPT appena creata e riceve, in risposta, la URL di redirect verso il WISP 2.0, permettendo al cittadino di completare l'esecuzione del pagamento.

  7. Il Nodo dei Pagamenti SPC, al termine del pagamento, informa l'EC dell'esito del pagamento.

  8. L'EC riceve la RT (Positiva/Negativa) e aggiorna lo stato del Pagamento Atteso sul proprio sistema interno.

Modello 3 - Interazioni con il toolkit pagoPA

  1. L'EC utilizza il modulo di Generazione codice IUV, inoltrando i valori assegnati da PagoPA in fase di censimento sul Portale delle Adesioni; tale modulo restituisce il valore dello IUV, da cui è ottenibile il corrispondente Numero Avviso.

  2. L'EC inoltra al modulo di Generazione Pagamento Atteso tutte le informazioni necessarie per la creazione di una Posizione Debitoria; tale modulo restituisce un oggetto del tipo "Pagamento Atteso". L'EC può utilizzare l'output ricevuto per effettuare un salvataggio sulla propria Base Dati.

  3. L'EC inoltra l'oggetto "PagamentoAtteso" al modulo di Generazione Avviso di Pagamento per la generazione e la stampa dell'avviso.

  4. Il modulo di Generazione Avviso di Pagamento restituisce un file pdf, creato come riportato nel documento Guida Tecnica Avviso Analogico v2.2.1; l'EC inoltra al cittadino pagatore l'Avviso di Pagamento (es: a mezzo postalizzazione, email, PEC, etc).

Utilizzo del toolkit - Inizializzazione

Di seguito vengono riportate le istruzioni operative per scaricare il toolkit ed utilizzarlo per attivare i pagamenti con la piattaforma pagoPA.

Anzitutto è necessario scaricare il software dal repository GitHub: https://github.com/pagopa/pagopa-toolkit-os-codebase.

Dopo aver effettuato il download è necessario lanciare la build di Maven:

mvn install -X -U

viene visualizzato un messaggio del tipo:

[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 11.334 s [INFO] Finished at: 2020-11-18T11:39:24+01:00 [INFO] ------------------------------------------------------------------------

Nei successivi capitoli vengono illustrate le funzionalità messe a disposizione dal Toolkit.

Utilizzo del Toolkit - Generazione codice IUV

Per la generazione dello IUV tramite i valori di auxDigit, segregationCode e applicationCode forniti da pagoPA, deve essere invocato il metodo generate sull'oggetto IuvCodeGeneration, nel seguente modo:

IuvCodeGeneration.generate(auxDigit, segregationCode, applicationCode);

Utilizzo del Toolkit - Generazione Pagamento Atteso

Il secondo modulo utilizzato nel workflow del pagamento è quello di Generazione del Pagamento Atteso.

Per la creazione del Pagamento Atteso è necessario preventivamente generare 3 oggetti:

  1. Payer, il pagatore del Pagamento Atteso; devono essere riportate tutte le informazioni del pagatore.

Di seguito la costruzione dell'oggetto Payer:

DebtPositionGeneration.generatePayer(uniqueIdentificationCode, uniqueIdentificationType, registry, address, numberStreet, locality, province, nation, postalCode, email, mobile));
  1. Payment Detail, i dati del Pagamento Atteso; devono essere riportate tutte le informazioni necessarie al pagamento della Posizione Debitoria.

Di seguito la costruzione dell'oggetto PaymentDetail:

DebtPositionGeneration.generatePaymentDetail(domainIdentifier, auxDigit, segregationCode, applicationCode, iuv, idTenant, totalAmountPayment, causal, expirationDate, specificCollectionData, documentNumber, installmentNumber, debitIban, debitBic));
  1. Single Payment Detail List, la lista dei singoli versamenti che devono essere associati alla posizione debitoria.

Di seguito la costruzione di un singolo oggetto SinglePaymentDetail:

DebtPositionGeneration.generateSinglePaymentDetail(amountSinglePayment, orderSinglePayment, causalDescriptionSinglePayment, creditIban, creditBic, supportIban, supportBic, datiMarcaBolloDigitale)

Una volta generate i 3 oggetti del Pagamento Atteso, può essere effettuata la creazione dell'oggetto DebitPosition, il Pagamento Atteso vero e proprio:

DebtPositionGeneration.generate(payer, paymentDetail, singlePaymentsDetailList)

Durante il ciclo di vita del pagamento può essere necessario modificare lo stato della Posizione Debitoria; in questo caso sono disponibili diversi metodi che vengono invocati con:

DebtPositionManagement.makeXXX(debtPosition)

I metodi disponibili sono:

Gli stati possibili di una Posizione Debitoria sono definiti in un'apposita enumeration.

Utilizzo del Toolkit - Generazione Avviso di Pagamento

Prima di richiedere la generazione del pdf è necessario creare l'oggetto CreditorInstitution come riportato di seguito:

PaymentNoticeGeneration.generateCreditorInstitution(logoByteArray, name, sector, info, fiscalCode, cbillCode, postalAccountHolder, postalAccountNumber, postalAuthorizationCode, website);

A questo punto può essere utilizzato il modulo per la Generazione dell'Avviso, a partire da uno o più oggetti di tipo DebtPosition:

PaymentNoticeGeneration.generate(debtPositionList, creditorInstitution, isModello1or2)

Se la richiesta di generazione di un Avviso di Pagamento viene effettuata a partire non da una singola DebtPosition, ma da molteplici DebtPosition, allora viene attivata la generazione delle sezioni dell'avviso riguardanti le rate del pagamento.

Sebbene il modulo prevede una serie di controlli di validazione sulle rate inserite nella lista delle DebtPosition, è consigliato prestare la massima attenzione nella valorizzazione di alcuni campi fondamentali a tale riguardo, quali appunto il Numero Documento (documentNumber) e soprattutto il numero della rata (installmentNumber). A tal proposito, è consigliato verificare che, nella lista delle DebtPosition, siano sempre presenti tutte le rate desiderate, mai ripetute nel numero rata; l'omissione di una rata potrebbe causare output indesiderati nell'utilizzo del modulo di Generazione dell'Avviso.

Utilizzo del Toolkit - Generazione della RPT

L'ultimo modulo del Toolkit è utilizzato per la creazione della RPT, sia in formato oggetto che in formato XML. Possono essere utilizzati due approcci diversi.

  1. Creazione della RPT a partire dal pagamento Atteso

E' il metodo più semplice per generare la RPT poiché sfrutta le potenzialità del Toolkit; infatti la Posizione Debitoria, precedentemente creata con il modulo di Generazione Pagamento Atteso, contiene già tutti i dati necessari per la costruzione della corrispondente RPT.

L'unico step ancora necessario è la definizione del Beneficiario del pagamento, il cui oggetto è ottenibile come di seguito riportato:

RptGeneration.generateEnteBeneficiario(identificativoUnivocoG, denominazioneEnteBeneficiario, codiceUnitOperEnteBeneficiario, denomUnitOperEnteBeneficiario, indirizzo);

Le componenti IdentificativoUnivocoG e Indirizzo, necessarie per la costruzione dell'oggetto EnteBeneficiario, sono ottenibili come di seguito riportato:

RptGeneration.generateIdentificativoUnivocoG(tipoIdentificativoUnivoco, codiceIdentificativoUnivoco);
RptGeneration.generateIndirizzo(indirizzo, civico, cap, localita, provincia, nazione);

Generato l'Ente Beneficiario, è possibile creare l'oggetto RPT finale di tipo RptContainer:

RptContainer rptContainer = RptGeneration.generate(idTenant, debtPosition, enteBeneficiario, commissioneCaricoPA);

Si noti come l'oggetto di tipo RptContainer non solo contiene la struttura della RPT, archiviabile sulla propria Base Dati, ma è arricchita anche di ulteriori dati quali l'idTenant dell'EC, lo stato della RPT (i cui possibili valori sono definiti in un'apposita enumeration) e - soprattutto - il formato XML della RPT, dato fondamentale per l'utilizzo dei servizi messi a disposizione da pagoPA.

  1. Creazione della RPT a partire dai singoli dati del pagamento

E' il metodo idoneo per generare la RPT in casi particolari come, ad esempio, l'impossibilità di gestire l'APA.

La procedura di generazione della RPT è leggermente più complessa, poiché richiede la generazione di tutte le diverse componenti che costituiscono una RPT (e quindi non solo dell'Ente Beneficiario):

RptGeneration.generateDominio(identificativoDominio, identificativoStazioneRichiedente);
RptGeneration.generateSoggetto(RptGeneration.generateIdentificativoUnivocoFG(tipoIdentificativoUnivoco, codiceIdentificativoUnivoco), anagrafica, RptGeneration.generateIndirizzo(indirizzo, civico, cap, localita, provincia, nazione), email);
RptGeneration.generateEnteBeneficiario(RptGeneration.generateIdentificativoUnivocoG(tipoIdentificativoUnivoco, codiceIdentificativoUnivoco), denominazioneEnteBeneficiario, codiceUnitOperEnteBeneficiario, denomUnitOperEnteBeneficiario, RptGeneration.generateIndirizzo(indirizzo, civico, cap, localita, provincia, nazione));
RptGeneration.generateDatiVersamento(importoTotaleDaVersare, tipoVersamento, identificativoUnivocoVersamento, ibanAddebito, bicAddebito, firmaRicevuta);
RptGeneration.generateDatiSingoloVersamento(importoSingoloVersamento, commissioneCaricoPA, ibanAccredito, bicAccredito, ibanAppoggio, bicAppoggio, credenzialiPagatore, descrizioneCausaleVersamento, iuv, datiSpecificiRiscossione, RptGeneration.generateDatiMarcaBolloDigitale(tipoBollo, hashDocumento, provinciaResidenza), ordineVersamento);

Una volta generate le diverse componenti che costituiscono la RPT, è possibile creare l'elemento RPT vero e proprio:

RptGeneration.generateRptElement(versioneOggetto, dominio, autenticazioneSoggetto, soggettoVersante, soggettoPagatore, enteBeneficiario, datiVersamento, datiSingoloVersamentoList);

Infine è possibile creare l'oggetto RPT finale di tipo RptContainer:

RptGeneration.generate(idTenant, rpt);

Come per la DebtPosition, il Toolkit mette a disposizione metodi per la modifica dello stato di una RPT, invocabili con:

RptManagement.makeXXX(rptContainer)

I metodi disponibili sono:

Casi d'uso

Generazione codice IUV

La generazione dello IUV è uno degli aspetti fondamentali nell'ambito dei pagamenti tramite pagoPA, poiché da esso dipende strettamente il Numero Avviso che appare sugli Avvisi di Pagamento e che consente il pagamento agli utenti in maniera immediata.

Lo IUV può avere una lunghezza variabile (solitamente 15 caratteri o, più spesso, 17), dipendente dai parametri di input necessari per la sua generazione, come di seguito indicato. Mentre il Numero Avviso ha sempre una lunghezza fissa di 18 caratteri, indipendentemente dalla lunghezza dello IUV a cui è legato.

Il Toolkit mette a disposizione una semplice funzionalità di generazione, basato sull'utilizzo di una sequenza numerica in modo da garantirne sempre l'univocità all'interno del dominio di un EC.

Il Toolkit ha la capacità di gestire autonomamente la generazione dello IUV: infatti è sufficiente generare una Posizione Debitoria (come indicato nei successivi casi d'uso) senza indicare alcun valore per lo IUV ed il Toolkit provvederà in maniera automatica alla sua creazione, inserendolo direttamente tra i dati della DebtPosition.

Diversamente, se si vuole procedere in maniera indipendente alla generazione del solo codice IUV, è sufficiente procedere come segue:

String iuv = IuvCodeGeneration.generate(auxDigit, segregationCode, applicationCode);

Lo IUV così generato è pronto per l'utilizzo, non sono necessarie ulteriori operazioni.

I dati di input necessari, auxDigit, segregationCode e applicationCode, sono dei dati di configurazione assegnati da PagoPA al momento dell'inizializzazione del servizio di pagamento dell'EC.

Il dato cardine è l'auxDigit, il cui valore definisce la struttura dello IUV e dipende dalla presenza, o meno, di molteplici punti di generazione dello stesso.

Entrando nello specifico, uno dei casi più frequenti gestito dal Toolkit è l'assegnazione - da parte di pagoPA - di un valore di auxDigit pari a 3. Cioè consente la generazione di IUV a 17 cifre anche tramite l'utilizzo del segregationCode (dato comunque assegnato da PagoPA, generalmente assume valore 01 o 02 o 03 etc..., quindi 2 caratteri). In questo caso il conseguente Numero Avviso è ottenibile semplicemente concatenando il valore dell'auxDigit (1 carattere) con il valore dello IUV (17 caratteri), dando luogo ad un valore di lunghezza 18 caratteri.

Per procedere ala generazione dello IUV in caso di auxDigit pari a 3 e, ad esempio, segregationCode pari a 01, è necessario procedere come di seguito riportato:

String iuv = IuvCodeGeneration.generate(3, 01, null);

Un altro caso frequente, comunque gestito dal Toolkit, è il valore di auxDigit pari a 0, che consente la generazione di IUV a 15 cifre. In questo caso il conseguente Numero Avviso è ottenibile concatenando il valore dell'auxDigit (1 carattere) con il valore dell'applicationCode (dato sempre assegnato da PagoPA, generalmente assume valore 01 o 02 o 03 etc..., quindi 2 caratteri) e con il valore dello IUV (15 caratteri), dando luogo ad un valore di lunghezza 18 caratteri.

Per procedere alla generazione dello IUV in caso di auxDigit pari a 0 e, ad esempio, applicationCode pari a 01, è necessario procedere come di seguito riportato:

String iuv = IuvCodeGeneration.generate(0, null, 01);

Nella versione attuale il Toolkit non gestisce ulteriori valori dell'auxDigit rispetto a quanto riportato.

Pagamento Multe

Di seguito viene riportato il caso di un pagamento di una multa. Il caso d'uso inizia con l'infrazione compiuta dal cittadino e conclude con il pagamento della stessa mediante Modello 3.

Il cittadino supera il limite di velocità e viene effettuata una rilevazione tramite autovelox. La rilevazione viene acquisita all'EC che predispone il verbale di notifica e carica il pagamento atteso nell'archivio delle posizioni debitorie.

Di seguito la costruzione dell'oggetto Payer:

Payer payer = DebtPositionGeneration.generatePayer("RSSMRA80A01F205X", StTipoIdentificativoUnivocoPersFG.F, "ROSSI MARIO", "via Roma", "123", "Firenze", "FI", "IT", 50127, "mario.rossi@gmail.it", "3381234567"));

Costruzione dell'oggetto PaymentDetail:

DPPaymentDetail paymentDetail = DebtPositionGeneration.generatePaymentDetail("01234567890", 3, 01, null, "01202000000003130", "abcd00001", BigDecimal.valueOf(11.11), "Pagamento multa", new GregorianCalendar(2020, Calendar.OCTOBER, 03).getTime(), "9/multe", "00998877665544332211", 0, "IT58C0306914512000000046601", "BCITITMMXXX"));

Nella SinglePaymentDetailList, la lista dei singoli versamenti che devono essere associati alla posizione debitoria, viene inserito un singolo importo:

DPSinglePaymentDetail singlePaymentDetail = DebtPositionGeneration.generateSinglePaymentDetail(BigDecimal.valueOf(11.11), 1, "Pagamento multa", null, null, null, null, null); List<DPSinglePaymentDetail> singlePaymentDetailList = new LinkedList<DPSinglePaymentDetail>(); singlePaymentDetailList.add(singlePaymentDetail);

Successivamente alla generazione delle 3 componenti del Pagamento Atteso, può essere effettuata la creazione dell'oggetto DebitPosition, il Pagamento Atteso vero e proprio:

DebtPosition debtPosition = DebtPositionGeneration.generate(payer, paymentDetail, singlePaymentsDetailList); List<DebtPosition> debtPositionList = new LinkedList<DebtPosition>(); debtPositionList.add(debtPosition);

A questo punto l'oggetto DebtPosition può essere registrato nella Base Dati dell'Ente Creditore.

Con l'oggetto DebtPosition appena creato l'EC costruisce il documento "Avviso di Pagamento" (PaymentNotice); viene creato l'oggetto CreditorInstitution come riportato di seguito:

CreditorInstitution creditorInstitution = PaymentNoticeGeneration.generateCreditorInstitution(logoByteArray, "Nome Ente Creditore", "Ufficio Tributi", "info Ente Creditore", "01234567890", "98765", null, null, null, "www.enteCreditore.it");

Quindi, a partire dagli oggetti creati, può essere utilizzato il modulo per la Generazione dell'Avviso:

byte[] printNoticeDebtPosition = PaymentNoticeGeneration.generate(debtPositionList, creditorInstitution, isModello1or2);

E' sufficiente convertire l'output così ottenuto in un file pdf per entrare in possesso dell'Avviso di Pagamento desiderato.

All'EC non resta altro che notificare, attraverso i diversi canali di comunicazione (posta ordinaria, pec, email, etc), il verbale corredato dell'avviso di pagamento.

Il cittadino tramite l'avviso si reca presso un PSP ed attiva il pagamento.

Il Nodo dei Pagamenti SPC verifica lo stato del pagamento nell'APA dell'EC, verificandone la pagabilità tramite il servizio web esposto dall'EC paaVerificaRPT.

Se la pendenza risulta pagabile, il PSP ne richiede, tramite il servizio web paaAttivaRPT, la RPT contenente tutti i dati del pagamento e procede alla riscossione del debito verso il cittadino. Maggiori dettagli sul workflow del pagamento Modello 3 nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC

L'EC può generare la RPT con una logica simile alla procedente utilizzata per la generazione della Posizione Debitoria.

Si parte dalla definizione del Beneficiario del pagamento, il cui relativo oggetto è ottenibile come di seguito riportato:

RptEnteBeneficiario enteBeneficiario = RptGeneration.generateEnteBeneficiario(identificativoUnivocoG, "Ente Beneficiario", "codiceUnitàOperativa", "denominaioneUnitàOperativa", indirizzo);

Le componenti IdentificativoUnivocoG e Indirizzo, necessarie per la costruzione dell'oggetto Ente Beneficiario, sono ottenibili come di seguito riportato:

IdentificativoUnivocoG identificativoUnivocoG = RptGeneration.generateIdentificativoUnivocoG(StTipoIdentificativoUnivocoPersG.G, "09876543210");
Indirizzo indirizzo = RptGeneration.generateIndirizzo("Via Torino", "12", "20100", "Milano", "MI", "IT");

Infine si può procedere con la creazione dell'oggetto RPT finale di tipo RptContainer:

RptContainer rptContainer = RptGeneration.generate("abcd00001", debtPosition, enteBeneficiario, null);

Il metodo del Toolkit restituisce l'oggetto RptContainer nel quale è possibile trovare la RPT in formato XML da inviare al Nodo dei Pagamenti SPC tramite il servizio nodoInviaRPT, come riportato nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC.

Infine il Nodo dei Pagamenti SPC invia all'EC la Ricevuta Telematica tramite il servizio paaInviaRT, come riportato nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC.

Pagamento Tari

Di seguito viene riportato il caso un pagamento di un tributo TARU. Il caso d'uso inizia con l'EC che effettua i calcoli del dovuto caricando la posizione debitoria e termina con il pagamento del tributo con il Modello 1.

NB: la presente sezione potrebbe essere suscettibile di cambiamenti.

L'EC effettua i calcoli per l'emissione della TARI e predispone i dati per il caricamento della posizione debitoria:

Di seguito la costruzione dell'oggetto Payer:

Payer payer = DebtPositionGeneration.generatePayer("RSSMRA80A01F205X", StTipoIdentificativoUnivocoPersFG.F, "ROSSI MARIO", "via Roma", "123", "Firenze", "FI", "IT", 50127, "mario.rossi@gmail.it", "3381234567"));

Costruzione dell'oggetto PaymentDetail:

DPPaymentDetail paymentDetail = DebtPositionGeneration.generatePaymentDetail("01234567890", 3, 01, null, "01202000000003130", "abcd00001", BigDecimal.valueOf(11.11), "Pagamento multa", new GregorianCalendar(2020, Calendar.OCTOBER, 03).getTime(), "9/multe", "00998877665544332211", 0, "IT58C0306914512000000046601", "BCITITMMXXX"));

Nella SinglePaymentDetailList, la lista dei singoli versamenti che devono essere associati alla posizione debitoria, viene inserito un solo importo singolo:

DPSinglePaymentDetail singlePaymentDetail = DebtPositionGeneration.generateSinglePaymentDetail(BigDecimal.valueOf(120.11), 1, "Pagamento TARI", null, null, null, null, null); List<DPSinglePaymentDetail> singlePaymentDetailList = new LinkedList<DPSinglePaymentDetail>(); singlePaymentDetailList.add(singlePaymentDetail);

Una volta generate le 3 componenti del Pagamento Atteso, può essere effettuata la creazione dell'oggetto DebitPosition, il Pagamento Atteso vero e proprio:

DebtPosition debtPosition = DebtPositionGeneration.generate(payer, paymentDetail, singlePaymentsDetailList); List<DebtPosition> debtPositionList = new LinkedList<DebtPosition>(); debtPositionList.add(debtPosition);

A questo punto l'oggetto DebtPosition può essere registrato nella Base Dati dell'Ente Creditore.

Con l'oggetto DebtPosition appena creato l'EC costruisce il documento "Avviso di Pagamento" (PaymentNotice); viene creato l'oggetto CreditorInstitution come riportato di seguito:

CreditorInstitution creditorInstitution = PaymentNoticeGeneration.generateCreditorInstitution(logoByteArray, "Nome Ente Creditore", "Ufficio Tributi", "info Ente Creditore", "01234567890", "98765", null, null, null, "www.enteCreditore.it");

Quindi può essere utilizzato il modulo per la Generazione dell'Avviso, a partire dagli oggetti creati:

byte[] printNoticeDebtPosition = PaymentNoticeGeneration.generate(debtPositionList, creditorInstitution, isModello1or2);

E' sufficiente convertire l'output così ottenuto in un file pdf per entrare in possesso dell'Avviso di Pagamento desiderato.

All'EC non resta altro che inoltrare, attraverso i diversi canali di comunicazione (posta ordinaria, pec, email, etc), l'avviso di pagamento appena creato.

Il cittadino tramite l'avviso si collega al sito dell'EC ed inserisce il numero avviso ricevuto, oppure ricerca nella sua area personale le pendenze in carico. Scelto il pagamento da effettuare il cittadino attiva il pagamento.

L'EC può generare la RPT con una logica simile alla procedente utilizzata per la generazione della Posizione Debitoria.

Si parte dalla definizione del Beneficiario del pagamento, il cui relativo oggetto è ottenibile come di seguito riportato:

RptEnteBeneficiario enteBeneficiario = RptGeneration.generateEnteBeneficiario(identificativoUnivocoG, "Ente Beneficiario", "codiceUnitàOperativa", "denominaioneUnitàOperativa", indirizzo);

Le componenti IdentificativoUnivocoG e Indirizzo, necessarie per la costruzione dell'oggetto Ente Beneficiario, sono ottenibili come di seguito riportato:

IdentificativoUnivocoG identificativoUnivocoG = RptGeneration.generateIdentificativoUnivocoG(StTipoIdentificativoUnivocoPersG.G, "09876543210");
Indirizzo indirizzo = RptGeneration.generateIndirizzo("Via Torino", "12", "20100", "Milano", "MI", "IT");

Infine si può procedere con la creazione dell'oggetto RPT finale di tipo RptContainer:

RptContainer rptContainer = RptGeneration.generate("abcd00001", debtPosition, enteBeneficiario, null);

Il metodo del Toolkit restituisce l'oggetto RptContainer nel quale è possibile trovare la RPT in formato XML da inviare al Nodo dei Pagamenti SPC tramite il servizio nodoInviaCarrelloRPT, come riportato nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC.

Il NodoSPC risponde alla richiesta fornendo una URL di redirect al WISP 2.0, dove il cittadino potrà scegliere tra le modalità di pagamento messe a disposizione dalla piattaforma pagoPA e concludere con il pagamento.

Infine il Nodo dei Pagamenti SPC invia all'EC la Ricevuta Telematica tramite il servizio paaInviaRT, come riportato nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC.

Maggiori dettagli sul workflow del pagamento Modello 1 nelle SANP Specifiche Attuative del Nodo dei Pagamenti-SPC

Utilizzo GUI

Per facilitare l'integrazione con la piattaforma pagoPa è disponibile una GUI utilizzabile per eseguire le seguenti operazioni:

La GUI del Toolkit può essere eseguita effettuando l'estrazione del pacchetto ToolkitPagoPA-x.y.zip e successivamente effettuando doppio click sul file ToolkitPagoPA-x.y.jar.

Con l'esecuzione del file verrà visualizzata la seguente GUI:

Cliccando sul pulsante Scarica template viene estratto dal Toolkit e salvato in locale, nella directory indicata dall'utente, un file template in formato CSV. Tale file deve essere utilizzato per comunicare alla GUI tutti i dati di un pagamento atteso, in una modalità che simula l'operazione di caricamento vero e proprio delle posizioni debitorie su piattaforme più strutturate ed evolute rispetto al Toolkit. Una volta compilato opportunamente, il file template è utilizzato come input per le funzionalità descritte in seguito.

La compilazione del file CSV viene guidata da un file Glossario, estratto dal toolkit insieme al file template, che riporta il significato di ogni campo, facilitando il caricamento delle posizioni.

Il carattere separatore del file CSV è il ; (punto e virgola); è obbligatorio indicare l'assenza di valore di un campo inserendo i caratteri "" ( doppio apice ripetuto 2 volte), seguiti ovviamente dal carattere separatore. In sostanza la corretta compilazione di una riga del template prevede sempre la valorizzazione di tutti i campi (attualmente 49).

Inserite le informazioni nel file CSV si può procedere al caricamento delle informazioni ed alla produzione dei file di output.

In input alla GUI vengono richieste le seguenti informazioni, come da immagine:

E' necessario quindi:

  1. scegliere il file CSV da caricare, cliccando il pulsante Scegli File associato;
  2. scegliere una cartella di destinazione dei file che verranno creati, utilizzando il pulsante Scegli cartella associato;
  3. scegliere il logo dell'Ente di appartenenza, necessario per la creazione dei file di avvisatura, nel formato consigliato (30x30 mm), tramite il pulsante Scegli File associato.

Dopo aver inserito tutti i parametri di input, cliccando sul pulsante Conferma il Toolkit avvia l'elaborazione dei dati inseriti nel file CSV.

Al termine dell'elaborazione, accedendo alla cartella precedentemente indicata come destinazione degli output, sono presenti i file generati:

Se l'operazione di caricamento termina con esito positivo, la cartella di destinazione contiene: