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 successivo (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 pagamenti (multe, licenze, etc).

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 codice identificativo univoco (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

Per fare tale scelta è necessario consultare le Specifiche attuative dei codici identificativi di versamento, riversamento e rendicontazione (SACI) e adottare il tipo di algoritmo più 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 PSP (Prestatori di Servizi di Pagamento) 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 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, che descriveremo di seguito, 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 pagoPA.

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 (quindi previsto), 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'istallazione di una caldaia, etc).

Di seguito verrà riportato il workflow, che l'EC deve implementare per mettere a disposizione del cittadino il pagamento online della pendenza tramite 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, 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 pagatore può visualizzare e stampare la Ricevuta Telematica.

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

Infatti il cittadino, attraverso i canali telematici (app/ home banking) o recandosi presso un qualsiasi punto fisico del PSP (tabaccaio, banche, ATM, et), attiva il pagamento tramite il Numero Avviso che gli è stato precedentemente comunicato dall'EC tramite l'Avviso di Pagamento.

Quando il pagatore 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 Esito 9 (pagamento in assenza di RT) in fase di rendicontazione, che necessita di una gestione straordinaria rispetto alla gestione ordinaria dei pagamenti 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 sono 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 Linee Guida 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, dal quale è 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 Linee Guida 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, dal quale è 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, a mezzo postalizzazione, email e/o PEC.

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.

Come prima cosa è necessario scaricare il software dal repository GitHub; il codice può essere visualizzato al link:

https://github.com/pagopa/pagopa-toolkit-os-codebase

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

mvn install -X -U

Verrà visualizzato il messaggio:

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

Nei prossimi capitoli viene illustrato l'utilizzo delle funzionalità messe a disposizione del 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 prima 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 le 3 componenti 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, 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 relativo 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);

Da notare 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 o, più spesso, 17 caratteri), dipendente dai parametri di input necessari per la sua generazione, come di seguito indicato; invece il Numero Avviso ha sempre una lunghezza fissa di 18 caratteri, indipendentemente dalla lunghezza dello IUV al quale è 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.

Inoltre, il Toolkit ha la capacità di gestire autonomamente la generazione dello IUV senza che il suo utilizzatore debba occuparsene direttamente: 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 è già 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, il che consente la generazione di IUV a 17 cifre anche tramite l'utilizzo del segregationCode (dato sempre assegnato da pagoPA, generalmente assume valore 01 o 02 o 03 ecc..., quindi 2 caratteri). In questo caso il conseguente Numero Avviso è ottenibile semplicemente concatenando, in successione, 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, sempre gestito dal Toolkit, è il valore di auxDigit pari a 0, il che consente la generazione di IUV a 15 cifre; in questo caso il conseguente Numero Avviso è ottenibile concatenando, in successione, il valore dell'auxDigit (1 carattere) con il valore dell'applicationCode (dato sempre assegnato da pagoPA, generalmente assume valore 01 o 02 o 03 ecc..., quindi 2 caratteri) e con il valore dello IUV (15 caratteri), dando luogo ad un valore di lunghezza 18 caratteri.

Per procedere ala 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);

Attualmente il Toolkit non gestisce ulteriori valori dell'auxDigit rispetto a quanto riportato.

Pagamento Multe

Di seguito riportiamo un caso d'uso 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 come segue:

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(11.11), 1, "Pagamento multa", 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 notificare, attraverso i diversi canali di comunicazione (posta ordinaria, Pec, email, ecc...), 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 Linee Guida Specifiche Attuative del Nodo dei Pagamenti-SPC (SANP)

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 Linee Guida Specifiche Attuative del Nodo dei Pagamenti-SPC (SANP).

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

Pagamento Tari

Di seguito riportiamo un caso d'uso di un pagamento di una Tari. 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, ecc...), 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 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 Linee Guida Specifiche Attuative del Nodo dei Pagamenti-SPC (SANP).

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 da 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 Linee Guida Specifiche Attuative del Nodo dei Pagamenti-SPC (SANP).

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