8. Modello dei dati¶
8.1. Pagamenti¶
In questo paragrafo sono descritti i seguenti documenti XML scambiati tra gli attori del sistema nell’ambito dei processi di pagamento:
- Richiesta di Pagamento Telematico (RPT);
- Ricevuta Telematica (RT);
- Flusso di rendicontazione (FR);
- Richiesta di Revoca (RR);
- Esito Revoca (ER).
Ogni elemento è caratterizzato da un campo versioneOggetto che ne indica la versione di riferimento, ogni versione è composta dalla tripletta numerica Major.Minor.Patch, che viene incrementata a seguito dei seguenti eventi:
- un avanzamento di Major revision è causato da modifiche alla struttura dell’oggetto tali che impediscono la retro-compatibilità con le versioni precedenti dello stesso oggetto;
- un avanzamento di Minor revision è ancora causato da modifiche all’oggetto ma tali che comunque garantiscono la retro-compatibilità con le versioni precedenti;
- un avanzamento di Patch revision è invece causato dalla necessità di apportare correzioni o precisazioni di scarso impatto.
Il seguente class diagram mostra le relazioni che si instaurano tra gli elementi durante un tentativo di pagamento andato a buon fine.
Figura 1: Diagramma delle classi del pagamento
In particolare:
- come specificato all’interno dell’Allegato A delle linee guida, ogni Posizione Debitoria di un EC è identificata all’interno di pagoPA da un codice identificativo denominato identificativoUnivocoVersamento (IUV). Tale codice è univocamente generato da un EC;
- per chiudere una Posizione Debitoria, l’Utilizzatore finale esegue una operazione di pagamento attraverso pagoPA con un PSP da lui stesso determinato. Ogni operazione (o tentativo) di pagamento, quindi, presuppone necessariamente l’esistenza di una Posizione Debitoria;
- l’operazione di pagamento è univocamente identificata da un codice denominato codiceContestoPagamento (CCP) generato dal soggetto che innesca il pagamento;
- IUV e CCP congiuntamente consentono di associare ogni RPT alla corrispondente RT.
- ad ogni operazione di pagamento, corrisponde uno solo degli oggetti RPT, RT e Flusso di Rendicontazione. Nella eventualità che sia richiesta la revoca di un’operazione già conclusa si genera un’unica coppia di oggetti RR/ER;
- ad un Flusso di Rendicontazione di uno specifico conto di accredito di un determinato EC corrispondono tutte le operazioni di pagamento andate a buon fine disposte nella singola giornata operativa;
- ad ogni RPT corrisponde una ed una sola RT;
- ad una RR corrisponde una ed una sola RT;
- ad un ER corrisponde una ed una sola RR.
8.1.1. Richiesta di Pagamento Telematica (RPT)¶
La RPT descrive una richiesta di pagamento di una Posizione Debitoria.
Figura 2: Diagramma delle classi della RPT
In particolare, una RPT è composta dai seguenti elementi:
- dominio: identifica il mittente della richiesta tramite i dati di configurazione;
- soggettoVersante: identifica la persona, fisica o giuridica, che effettua il pagamento;
- soggettoPagatore: identifica la persona fisica o giuridica associato alla Posizione Debitoria;
- enteBeneficiario: identifica l’EC beneficiario del pagamento;
- datiVersamento: descrive i dettagli necessari del (dei) versamento (i) utili al PSP per completare l’operazione di pagamento verso l’EC.
La trasmissione della RPT è infine identificata dai seguenti parametri generati dall’EC:
- data di generazione della RPT (dataOraMessaggioRichiesta).
- codice IdentificativoMessaggioRichiesta, univoco nell’ambito della stessa data di generazione della RPT.
Nel seguito si descrivono nel dettaglio gli elementi della RPT all’interno dello schema XSD a meno che non siano palesemente auto-esplicativi; inoltre sono specificati i parametri associati agli attributi che vengono utilizzati per filtrare i PSP in grado di erogare il servizio di pagamento richiesto durante il processo di selezione degli stessi da parte dell’Utilizzatore finale.
Figura 3: Diagramma delle classi del versamento
Un versamento è caratterizzato dai seguenti attributi principali:
- dataEsecuzionePagamento: indica la data in cui l’EC richiede che venga effettuato il versamento;
- ImportoTotaleDaVersare: specifica l’importo totale del versamento, anche nel caso che includa l’acquisto di eventuali marche da bollo; la valorizzazione di tale parametro istruisce il NodoSPC a filtrare i servizi di pagamento dei PSP sulla base del massimo importo pagabile contenuto nel Catalogo Dati Informativi;
- Tipo Versamento: descrive il tipo di versamento. I possibili valori ammessi sono:
- BBT, Bonifico Bancario di Tesoreria; pagamento con bonifico anche utilizzato per indicare l’innesco di un pagamento online presso l’EC
- BP, Bonifico Postale.
- AD, Addebito Diretto.
- CP, Carta di Pagamento.
- PO, pagamento presso PSP. utilizzato per innescare un pagamento presso uno dei canali del PSP.
- OBEP, Online Banking E-Payment; utilizzato per descrivere un pagamento tramite canale MyBank.
- OTH, Others; Altre forme di versamento.
- identificativoUnivocoVersamento: riferimento univoco assegnato al versamento da parte dell’EC (vedi allegato A alle Linee guida); identifica la Posizione Debitoria;
- CodiceContestoPagamento: codice univoco necessario a definire il contesto nel quale viene effettuato il versamento; identifica il tentativo di pagamento;
- ibanAddebito e bicAddebito: parametri opzionali che definiscono rispettivamente l’International Bank Account Number (ISO 13616) e il Bank Identifier Code (ISO 9362) del conto da addebitare;
- firma ricevuta: campo mantenuto per retro-compatibilità, sempre valorizzato a 0.
Un unico pagamento disposto dall’Utilizzatore finale può comportare per il PSP, per richiesta dell’EC, la necessità di operare molteplici accrediti (massimo cinque) su diversi conti dell’EC come specificato nella struttura datiSingoloVersamento che contiene i dati di dettaglio necessari per tali operazioni:
- importoSingoloVersamento: importo del singolo accredito (NB la somma dei singoli importi deve corrispondere al dato ImportoTotaleDaVersare);
- ibanAccredito e bicAccredito: entrambi i campi identificano univocamente il conto corrente specificato dall’EC da accreditare dell’importo del singolo versamento, che deve essere configurato sul NodoSPC;
- ibanAppoggio e bicAppoggio: entrambi i campi identificano univocamente il conto corrente alternativo al conto di accredito che il PSP può utilizzare per gestire l’operazione di pagamento. La scelta di utilizzare il conto alternativo a quello di accredito è demandata al PSP in base alle proprie necessità operative, purché preventivamente dichiarate nella propria configurazione e purché la scelta rimanga coerente per tutti i singoli versamenti. In un caso d’uso notevole nella prassi tali campi sono valorizzati con il conto corrente postale, in alternativa a un conto bancario specificato come conto di accredito. Nello XSD il dato è facoltativo per gestire il caso in cui l’EC effettivamente non disponga di un conto corrente alternativo; viceversa, se presente, il conto corrente deve essere configurato sul NodoSPC;
- causaleVersamento: rappresenta la descrizione estesa della causale del versamento che deve essere conforme a quanto indicato nella Sezione I dell’Allegato A alle Linee guida;
- datiSpecificiRiscossione: rappresenta l’indicazione dell’imputazione della specifica entrata per esporre la natura contabile del pagamento, specificando il tipo e codice contabilità.
8.1.2. Richiesta di acquisto Marca da Bollo Digitale¶
L’EC può consentire all’Utilizzatore finale, con un unico versamento, il contestuale acquisto di uno o più Marche da bollo digitali, con le modalità previste dall’Agenzia per le Entrate. A tal fine è necessario che almeno un singolo versamento contenga i seguenti campi:
- tipoBollo: contiene uno dei tipi di Marca da Bollo Digitale per i quali l’Agenzia per le Entrate consente l’acquisto tramite pagoPA. A ogni tipo di bollo è associato un costo che deve essere coerente con il valore del campo importoSingoloVersamento;
- hashDocumento: contiene l’impronta informatica (digest) del documento digitale a cui è associata la Marca da Bollo Digitale. L’algoritmo di hash da utilizzare per produrre l’impronta è lo SHA-256. La stringa di 256 bit (32 ottetti) risultato di tale algoritmo deve essere convertita in base64;
- provinciaResidenza: sigla automobilistica della provincia di residenza del soggetto pagatore.
La valorizzazione della presente struttura dati istruisce il NodoSPC a rendere disponibili all’Utilizzatore finale, durante il processo di selezione dei PSP, quelli convenzionati con l’Agenzia delle Entrate per l’acquisto della Marca da Bollo Digitale (sistema @e.bollo).
8.1.3. Ricevuta Telematica (RT)¶
La RT restituisce all’EC il documento che conclude il flusso innescato da una richiesta di pagamento (RPT) ed attesta, qualora l’esito sia positivo, l’esecuzione del versamento e la chiusura della Posizione Debitoria.
Figura 4: Diagramma delle classi della RT
Questi sono i principali elementi:
- dominio: identifica il mittente della richiesta tramite i dati di configurazione;
- soggettoVersante: identifica la persona fisica o giuridica che effettua le operazioni di versamento;
- soggettoPagatore: identifica la persona fisica o giuridica a cui è intestata la posizione debitoria;
- istitutoAttestante: descrive il Prestatore di Servizi di Pagamento utilizzato per le operazioni
- enteBeneficiario: identifica l’EC destinatario del pagamento l’EC che richiesto l’acquisto della Marca da Bollo Digitale;
- datiPagamento: descrive il dettaglio del pagamento effettuato (con esito).
La trasmissione della RT è infine identificata dai seguenti parametri generati dal PSP:
- dataOraMessaggioRicevuta: indica la data e l’ora del pagamento, liberatoria per l’Utilizzatore finale. Corrisponde con la data e ora del pagamento indicata dal PSP nell’attestazione.
- riferimentoMessaggioRichiesta: nella generazione di una RT il PSP deve settare tale campo in modo che sia identico al campo identificativoMessaggioRichiesta della univoca RPT di riferimento.
8.1.4. Richiesta di revoca (RR)¶
La RR contiene tutte le informazioni necessarie per gestire sia la revoca che lo storno di un pagamento, definiti in sezione II.
Figura 5: Diagramma delle classi della Richiesta di Revoca
In particolare, la RR è composta dai seguenti elementi:
- dominio: identifica il mittente della richiesta tramite i dati di configurazione;
- soggettoVersante: identifica la persona fisica o giuridica che ha effettuato le operazioni di versamento;
- soggettoPagatore: identifica la persona fisica o giuridica a cui è riferita la Posizione Debitoria di cui è richiesto il rollback;
- istitutoAttestante: descrive il Prestatore di Servizi di Pagamento che ha emesso a RT e che ne richiede la revoca;
- datiRevoca: descrive il dettaglio dell’operazione di revoca.
8.1.5. Esito Della Revoca (ER)¶
La ER descrive l’esito di una RR di un pagamento effettuato.
Figura 6: Diagramma delle classi dell’Esito della Revoca
In particolare la ER è composta dai seguenti elementi:
- dominio: identifica il mittente della richiesta tramite i dati di configurazione;
- soggettoVersante: identifica la persona fisica o giuridica che ha effettuato le operazioni di versamento;
- soggettoPagatore: identifica la persona fisica o giuridica a cui è riferita la Posizione Debitoria di cui è richiesto il rollback;
- istitutoAttestante: descrive il Prestatore di Servizi di Pagamento che ha emesso a RT e che ne richiede la revoca;
- datiRevoca: descrive il dettaglio dell’operazione di revoca.
- riferimento: insieme dei campi che identificano la RR effettuata.
8.1.6. Flusso di rendicontazione (FR)¶
Il FR referenzia i singoli pagamenti accreditati tramite bonifico cumulativo di un conto corrente dell’EC, conformemente a quanto stabilito nell’Allegato A delle Linee Guida.
Le informazioni che devono essere messe a disposizione dell’EC sono organizzate in flussi omogenei di dati e devono essere rese disponibili ai soggetti interessati a cura del PSP che ha effettuato l’operazione di accredito. Il FR deve essere reso disponibile all’EC nella giornata successiva a quella durante la quale è stato disposto il bonifico (D+2).
Figura 7: Diagramma delle classi del Flusso di Rendicontazione
In particolare, il FR è identificato dai seguenti parametri:
- identificativoFlusso: riferimento al componente <idFlusso> della causale del SEPA Credit Transfer di Riversamento (dato “Unstructured Remittance Information” – attributo AT-05)
- identificativoUnivocoRegolamento: identificativo assegnato dal PSP all’operazione di trasferimento fondi, che può alternativamente essere così
valorizzato:
- Transaction Reference Number (TRN, attributo AT-43 Originator Bank’s Reference), qualora il PSP, al momento della generazione del flusso di riversamento, disponga di tale dato;
- EndToEndId (attributo AT-41 Originator’s Reference): identificativo univoco assegnato dal PSP, nel caso in cui al momento della generazione del flusso di riversamento non sia disponibile il TRN;
- istitutoMittente: struttura che identifica il PSP mittente che genera il FR;
- istitutoRicevente: identifica l’EC destinatario del flusso;
- datiSingoloPagamento: struttura che riporta la distinta dei versamenti cumulati all’interno del flusso SCT; ciascun versamento viene messo in
relazione con i seguenti elementi:
- la Posizione Debitoria, attraverso l’identificativoUnivocoVersamento (IUV);
- le RT prodotte dal PSP, attraverso l’identificativoUnivocoRiscossione (IUR) ed eventualmente l’indiceDatiSingoloPagamento che specifica l’indice (numero d’ordine) nella lista di versamenti all’interno della RT.
8.2. Messaggi di errore¶
In caso di errori verificatisi nel colloquio tra i vari soggetti aderenti (EC e PSP) ed il NodoSPC, i relativi messaggi di errore vengono descritti utilizzando la struttura faultBean mostrata nel seguente diagramma.
Figura 8: Oggetto faultBean
La struttura contiene i seguenti parametri:
- id: identificativo del soggetto che emette l’errore, valorizzato con idDominio (nel caso di EC), identificativoPSP (nel caso di PSP) e da una costante “NodoDeiPagamentiSPC” nel caso di errore identificato da parte del NodoSPC;
- faultCode: codice dell’errore, composto secondo il seguente formato:
<erogatore>_<codice errore>
Dove <erogatore> rappresenta il soggetto che ha emesso l’errore e può assumere i seguenti valori:
PPT: errore emesso da NodoSPC;
PAA: errore emesso da EC;
CANALE: errore emesso da PSP.
- faultString: specifica del codice dell’errore. Ogni soggetto emittente valorizza tale parametro sulla base delle indicazioni fornite nella tabella dei Codici di errore di seguito riportata.
- description: descrizione aggiuntiva dell’errore impostata dal soggetto che emette l’errore. Nella emissione di un faultCode PAA_SEMANTICA (EC) o CANALE_SEMANTICA (PSP), i soggetti erogatori (EC o PSP) dovranno indicare nel presente dato lo specifico errore legato all’elaborazione dell’oggetto ricevuto. Nel caso in cui il NodoSPC trasmetta verso un soggetto un errore di Controparte con faultCode valorizzato, a seconda del caso, a PPT_ERRORE_EMESSO_DA_PAA o PPT_CANALE_ERRORE, il campo è valorizzato con l’errore emesso dalla Controparte.
- serial: posizione dell’elemento nella lista a cui fa riferimento. Utile quando si fornisce un parametro in forma di vettore (ad esempio, nella primitiva nodoInviaCarrelloRPT). Nel caso in cui l’errore sia generato dall’EC o dal PSP, il dato riporta il valore del dato faultBean.serial impostato dall’EC o dal PSP;
- originalFaultCode: codice dell’errore generato dalla Controparte. Non è presente se il soggetto che emette l’errore è il NodoSPC;
- originalFaultString: specifica dell’errore generato dalla Controparte. Non è presente se il soggetto che emette l’errore è il NodoSPC;
- originalDescription: descrizione aggiuntiva dell’errore generato dalla Controparte. Non è presente se il soggetto che emette l’errore è il NodoSPC.
La tabella sottostante riporta l’elenco dei codici di errore (faultCode) che i soggetti dovranno utilizzare al verificarsi delle condizioni di errore (faultString).
faultCode | faultString |
---|---|
CANALE_AVVISO_DUPLICATO | Messaggio di warning per Avviso duplicato |
CANALE_BUSTA_ERRATA | Messaggio dismesso |
CANALE_ER_DUPLICATA | ER duplicata |
CANALE_FIRMA_SCONOSCIUTA | Messaggio dismesso |
CANALE_INDISPONIBILE | Servizio non disponibile |
CANALE_RICHIEDENTE_ERRATO | Identificativo richiedente non valido |
CANALE_RPT_DUPLICATA | RPT duplicata. |
CANALE_RPT_RIFIUTATA | RPT rifiutata |
CANALE_RPT_SCONOSCIUTA | RPT sconosciuta |
CANALE_RT_NON_DISPONIBILE | RT non disponibile |
CANALE_RT_SCONOSCIUTA | RT sconosciuta |
CANALE_SEMANTICA | Errore semantico |
CANALE_SINTASSI_EXTRAXSD | Errore di sintassi extra XSD |
CANALE_SINTASSI_XSD | Errore di sintassi XSD |
CANALE_SYSTEM_ERROR | Errore generico |
PAA_ATTIVA_RPT_IMPORTO_NON_VALIDO | L’importo del pagamento in attesa non è congruente con il dato indicato dal PSP |
PAA_ER_DUPLICATA | Esito Revoca duplicato |
PAA_ERRORE_FORMATO_BUSTA_FIRMATA | Formato busta di firma errato o non corrispondente al tipoFirma |
PAA_FIRMA_ERRATA | Errore di firma |
PAA_FIRMA_INDISPONIBILE | Impossibile firmare |
PAA_ID_DOMINIO_ERRATO | La PAA non corrisponde al Dominio indicato |
PAA_ID_INTERMEDIARIO_ERRATO | Identificativo intermediario non corrispondente |
PAA_PAGAMENTO_ANNULLATO | Pagamento in attesa risulta annullato all’Ente Creditore |
PAA_PAGAMENTO_DUPLICATO | Pagamento in attesa risulta concluso all’Ente Creditore |
PAA_PAGAMENTO_IN_CORSO | Pagamento in attesa risulta in corso all’Ente Creditore |
PAA_PAGAMENTO_SCADUTO | Pagamento in attesa risulta scaduto all’Ente Creditore |
PAA_PAGAMENTO_SCONOSCIUTO | Pagamento in attesa risulta sconosciuto all’Ente Creditore |
PAA_RPT_SCONOSCIUTA | La RPT risulta sconosciuta |
PAA_RT_DUPLICATA | La RT è già stata accettata |
PAA_RT_SCONOSCIUTA | RT sconosciuta |
PAA_SEMANTICA | Errore semantico |
PAA_SINTASSI_EXTRAXSD | Errore di sintassi extra XSD |
PAA_SINTASSI_XSD | Errore di sintassi XSD |
PAA_STAZIONE_INT_ERRATA | Stazione intermediario non corrispondente |
PAA_SYSTEM_ERROR | Errore generico |
PAA_TIPOFIRMA_SCONOSCIUTO | Il campo tipoFirma non corrisponde ad alcun valore previsto |
PPT_AUTENTICAZIONE | Errore di autenticazione |
PPT_AUTORIZZAZIONE | Il richiedente non ha i diritti per l’operazione |
PPT_CANALE_DISABILITATO | Canale conosciuto ma disabilitato da configurazione |
PPT_CANALE_ERR_PARAM_PAG_IMM | Parametri restituiti dal Canale per identificare il pagamento non corretti |
PPT_CANALE_ERRORE | Errore restituito dal Canale |
PPT_CANALE_ERRORE_RESPONSE | La response ricevuta dal Canale è vuota o non corretta sintatticamente o semanticamente |
PPT_CANALE_INDISPONIBILE | Nessun Canale utilizzabile e abilitato |
PPT_CANALE_IRRAGGIUNGIBILE | Errore di connessione verso il Canale |
PPT_CANALE_NONRISOLVIBILE | Il Canale non è specificato, e nessun Canale risulta utilizzabile secondo configurazione |
PPT_CANALE_SCONOSCIUTO | Canale sconosciuto |
PPT_CANALE_SERVIZIO_NONATTIVO | Il servizio applicativo del Canale non è attivo |
PPT_CANALE_TIMEOUT | Timeout risposta dal Canale |
PPT_CODIFICA_PSP_SCONOSCIUTA | Valore di codificaInfrastruttura PSP non censito |
PPT_DOMINIO_DISABILITATO | Dominio disabilitato |
PPT_DOMINIO_SCONOSCIUTO | IdentificativoDominio sconosciuto |
PPT_ERRORE_EMESSO_DA_PAA | Errore restituito dall’Ente Creditore |
PPT_ERRORE_FORMATO_BUSTA_FIRMATA | Formato busta di firma errato o non corrispondente al tipoFirma |
PPT_FIRMA_INDISPONIBILE | Impossibile firmare |
PPT_IBAN_NON_CENSITO | Il codice IBAN indicato dall’Ente Creditore non è presente nella lista degli IBAN comunicati al sistema pagoPA |
PPT_ID_CARRELLO_DUPLICATO | Identificativo Carrello RPT duplicato |
PPT_ID_FLUSSO_SCONOSCIUTO | Identificativo flusso sconosciuto |
PPT_ISCRIZIONE_NON_PRESENTE | Iscrizione non presente in archivio |
PPT_OPER_NON_REVOCABILE | Operazione non revocabile |
PPT_OPER_NON_STORNABILE | Operazione non stornabile |
PPT_PSP_DISABILITATO | PSP conosciuto ma disabilitato da configurazione |
PPT_PSP_SCONOSCIUTO | PSP sconosciuto |
PPT_RPT_DUPLICATA | RPT duplicata |
PPT_RPT_NON_INOLTRABILE | La RPT richiesta e fornita dalla PA non può essere inoltrata in quanto non corretta formalmente |
PPT_RPT_SCONOSCIUTA | RPT sconosciuta |
PPT_RT_DUPLICATA | La RT inviata dal PSP è già stata inviata (RT push) |
PPT_RT_NONDISPONIBILE | RT non ancora pronta |
PPT_RT_SCONOSCIUTA | RT sconosciuta |
PPT_SEMANTICA | Errore semantico |
PPT_SINTASSI_EXTRAXSD | Errore di sintassi extra XSD |
PPT_SINTASSI_XSD | Errore di sintassi XSD |
PPT_STAZIONE_INT_PA_DISABILITATA | Stazione disabilitata |
PPT_STAZIONE_INT_PA_IRRAGGIUNGIBILE | Errore di connessione verso la Stazione |
PPT_STAZIONE_INT_PA_SCONOSCIUTA | IdentificativoStazioneRichiedente sconosciuto |
PPT_STAZIONE_INT_PA_SERVIZIO_NONATTIVO | Il Servizio Applicativo della Stazione non è attivo |
PPT_SUPERAMENTOSOGLIA | Una qualche soglia fissata per PPT è temporaneamente superata e la richiesta è quindi rifiutata |
PPT_SYSTEM_ERROR | Errore generico |
PPT_TIPOFIRMA_SCONOSCIUTO | Il campo tipoFirma non corrisponde ad alcun valore previsto |
PPT_ULTERIORE_ISCRIZIONE | Ulteriore iscrizione precedentemente censita |
PPT_WISP_SESSIONE_SCONOSCIUTA | La tripletta idDominio+keyPA+keyWISP non corrisponde ad alcuna sessione memorizzata nella componente WISP |
PPT_WISP_TIMEOUT_RECUPERO_SCELTA | La tripletta idDominio+keyPA+keyWISP è relativa ad una scelta effettuata scaduta |
Tabella 1: Codici di errore
8.3. Avvisatura digitale¶
Paragrafo soggetto a proposta di modifica |
Questo paragrafo descrive gli elementi scambiati tra il NodoSPC e gli attori coinvolti per realizzare la funzione di Avvisatura Digitale.
In particolare, gli elementi principali che vengono scambiati sono:
- Avvisatura, rappresenta il dato attraverso il quale un EC notifica ad un Soggetto Pagatore un avviso di pagamento digitale. Può essere scambiato singolarmente o attraverso una lista.
- Esito Inoltro Avvisatura, rappresenta la notifica dell’avvenuta consegna dell’avviso precedentemente inviato.
- Iscrizione Servizio, rappresenta la richiesta di un utente finale di ricezione degli avvisi di pagamento tramite uno dei canali messi a disposizione dai PSP.
Il seguente Diagramma delle classi rappresenta la relazione tra i diversi oggetti scambiati ed altri oggetti già descritti nei paragrafi precedenti.
Figura 9: Diagramma delle classi dell’avvisatura
8.3.1. Avviso digitale¶
L’Avvisatura rappresenta il documento telematico con il quale un EC notifica ad un Soggetto Pagatore un Avviso di Pagamento.
Figura 10: Diagramma delle relazioni degli attributi dell’Avvisatura
Una Avvisatura è descritta dai seguenti parametri:
- codiceAvviso: è il numero dell’avviso di pagamento, composto come descritto nell’allegato A delle Linee Guida;
- tassonomiaAvviso: classificazione dell’avviso;
- dataScadenzaPagamento: rappresenta la data ultima entro la quale si richiede che venga pagato l’avviso di pagamento;
- dataScadenzaAvviso: Indica la data, successiva alla data di scadenza del pagamento, sino alla quale si ritiene valido l’avviso;
- importoAvviso: rappresenta l’importo da pagare, potrebbe subire delle variazioni;
- descrizionePagamento: testo libero che descrive la natura dell’avviso;
- urlAvviso: URL di una pagina web messa a disposizione dall’EC dove l’Utilizzatore finale può consultare l’avviso di pagamento;
- tipoPagamento : indica la natura del pagamento;
- tipoOperazione: indica il tipo di operazione connessa con l’avviso. Può assumere i seguenti valori:
‘C’ = Creazione di un nuovo avviso
‘U’= Modifica di un avviso esistente
‘D’= Cancellazione di un avviso esistente
Inoltre contiene informazioni in merito a:
- anagrafica beneficiario: descrive l’EC che ha emesso l’avviso di pagamento;
- identificativo dominio: contiene il codice fiscale del soggetto direttamente connesso che invia l’avviso Digitale;
- soggetto pagatore: identifica il soggetto destinatario dell’avviso;
- dati Singolo Pagamento: descrive i dettagli del pagamento da effettuare.
Il tipo ListaAvvisiDigitali è la struttura composta dall’insieme di più avvisi, purché di numero inferiore a 100.000 elementi.
8.3.2. Esito Inoltro Avvisatura¶
È un oggetto informatico, predisposto dal Nodo-SPC, che permette all’EC di conoscere l’esito del relativo inoltro massivo di Avvisi digitali.
Figura 11: Diagramma delle classi dell’esito inoltro avvisatura
Contiene al suo interno informazioni riguardo a:
- identificativoMessaggioRichiesta: riferimento all’avviso inviato
- identificativoDominio: il codice fiscale del soggetto direttamente connesso che ha inviato l’avviso Digitale di cui il NodoSPC sta fornendo l’Esito.
- EsitoAvvisatura: struttura che descrive l’esito dell’inoltro dell’avvisatura.
L’esito di un avvisatura è descritto dai seguenti parametri:
- tipoCanaleEsito: tipologia di canale usato per inviare l’avviso all’utente;
- IdentificativoCanale: identificativo del canale “mobile” a cui si riferisce l’esito dell’avvisatura;
- codiceEsito: esito dell’invio riferito al singolo canale;
- descrizioneEsito: testo libero che, in caso di esito negativo (codiceEsito<>0), descrive l’evento stesso.
8.3.3. Iscrizione al servizio¶
Definisce lo schema secondo il quale un PSP richiede al NodoSPC di ricevere le avvisature destinate ad un Soggetto Pagatore.
Figura 12: Diagramma delle classi dell’iscrizione al servizio
Contiene al suo interno informazioni riguardo a:
- IdentificativoUnivocoSoggetto: descrizione del Soggetto Pagatore del quale si vuole ricevere le avvisature.
È descritto dai seguenti parametri:
- azioneDiAggiornamento: Indica il tipo di aggiornamento richiesto, può assumere i seguenti valori:
- ‘A’= Attivazione
- ‘D’= disattivazione
8.4. Configurazione¶
In questo paragrafo vengono descritte tutte le informazioni necessarie al NodoSPC per configurare opportunamente gli attori ad esso connessi, ovvero EC e PSP.
Per la comunicazione di tali informazioni il NodoSPC mette a disposizione l’applicazione web Portale delle Adesioni. Per ulteriori dettagli consultare la Sezione IV.
8.4.1. Ente Creditore¶
L’oggetto Ente Creditore viene identificato nel sistema attraverso il proprio codice fiscale (campo idDominio) e caratterizzato dai seguenti attributi:
- Descrizione dell’erogazione dei servizi;
- Dettaglio di eventuali servizi disponibili per pagamento spontaneo disposto presso il PSP;
- Dettaglio dei conti correnti di accredito e di appoggio incasso utilizzati.
Il documento che raccoglie la porzione pubblica di tali informazioni che deve essere resa disponibile alle controparti è raccolta nel documento Tabella delle Controparti che il NodoSPC rende disponibile tramite primitive SOAP descritte fra le funzioni ausiliarie.
Figura 13: Diagramma delle classi per la configurazione di un EC
8.4.2. PSP¶
L’oggetto PSP viene identificato nel sistema (campo identificativoPSP) attraverso il codice BIC oppure da un codice formato dalla concatenazione della stringa “ABI” con il valore del codice ABI del PSP. (La scelta fra i due identificativi deve essere compiuta dal PSP al momento della prima configurazione ed è irreversibile). Ogni PSP è caratterizzato dalle seguenti proprietà:
- specifica sulla pubblicazione delle informazioni;
- dettaglio dei servizi di pagamento attivati (canali).
Figura 14: Diagramma delle classi per la configurazione di un PSP
Il documento che raccoglie la porzione pubblica di tali informazioni che deve essere resa disponibile alle controparti EC è raccolta nel documento InformativaPSP che il NodoSPC rende disponibile tramite primitive SOAP descritte fra le funzioni ausiliarie.
Inoltre, per la configurazione delle modalità di pagamento nel sistema pagoPA, il PSP produce il documento Catalogo Dati Informativi, come riportato nella sezione IV.
8.4.2.1. Pubblicazione¶
All’interno di questa struttura, il PSP specifica gli attributi comuni a tutti i servizi di pagamento che rende disponibili sul sistema:
- dataPubblicazione: data e ora relativa all’invio dell’ultimo aggiornamento delle informazioni;
- release:
- dataInizioValidita: data e ora di inizio validità delle informazioni;
- urlInformazioniPSP: indirizzo di una pagina web gestita dal PSP rivolta all’Utilizzatore finale per la divulgazione di informazioni specifiche relative ai servizi di pagamento resi disponibili;
- LogoPSP: logotipo del PSP;
- stornoPagamento: flag che indica la capacità tecnica di gestire il processo di storno di un pagamento.
- marcaBolloDigitale: flag che individua un PSP convenzionato con l’Agenzia delle Entrate come rivenditore della Marca da bollo digitale attraverso il sistema @e.bollo.
8.4.2.2. Canale¶
La struttura raccoglie tutte le informazioni relative a un servizio di pagamento messo a disposizione dal PSP sul sistema pagoPA:
- identificativoIntermediario: identificativo dell’Intermediario del PSP che fornisce lo specifico accesso (Canale) al PSP per l’erogazione del servizio. L’intermediario può coincidere con il PSP stesso;
- identificativoCanale: identificativo del canale attraverso il quale viene effettuata la transazione;
- TipoVersamento: codice che identifica il tipo di versamento utilizzato dal canale;
Tipo Versamento | Codice | Descrizione |
---|---|---|
Pagamento con Carta | CP | Il PSP è abilitato a gestire pagamenti con carta di credito o debito |
Pagamento mediante MyBank | OBEP | Il PSP è abilitato a gestire pagamenti MyBank on line |
Pagamento attivato presso il PSP | PO | Il PSP è abilitato a gestire pagamenti interfacciando l’Utilizzatore finale. |
Pagamento mediate Poste Italiane | BP | Canale che identifica un canale on line gestito da Poste Italiane |
Tabella 2: Tipi di versamento
- modelloPagamento: codice che identifica il modello di pagamento gestito dal canale; i calori utilizzabili sono elencati nella seguente tabella.
Modello di pagamento | Codice | Descrizione |
---|---|---|
Processo di pagamento con re indirizzamento on-line | 0 | Il PSP è abilitato a gestire pagamenti inizializzati dalla primitiva nodoInviaRPT |
Processo di pagamento con re indirizzamento on-line tramite carrello | 1 | Il PSP è abilitato a gestire pagamenti inizializzati dalla primitiva nodoInviaCarrelloRPT |
Processo di pagamento con autorizzazione gestita dal PSP | 2 | Il PSP è abilitato a gestire pagamenti con autorizzazione differita |
Processo di pagamento attivato presso il PSP | 4 | Il PSP è abilitato ad inizializzare un processo di pagamento |
Tabella 3: Modelli di pagamento
- priorità: campo boolean mantenuto per retro-compatibilità da valorizzare a ‘false’;
- canaleApp: indica se il canale in questione può essere inserito all’interno della categoria “Altri Metodi di Pagamento”;
- servizioAlleImprese: campo boolean che indica se il servizio erogato dal PSP è destinato ad un utilizzo solo da parte delle imprese.
Inoltre, un canale è definito dagli attributi di seguito descritti in paragrafi dedicati:
8.4.2.2.1. Servizio¶
La struttura descrive come verrà visualizzato all’Utilizzatore finale per selezionare il PSP sul sistema WISP:
- nomeServizio: nome commerciale del servizio / app
- logoServizio: logotipo del servizio / app. Con risoluzione 400x128px.
8.4.2.2.2. Informazioni dettaglio Servizio¶
- codiceLingua: identifica la lingua utilizzata per le informazioni di dettaglio della presente struttura. Le lingue supportate dal sistema pagoPA sono l’italiano e l’inglese oltre a quelle delle minoranze linguistiche tutelate (tedesco, francese e sloveno);
- descrizioneServizio: testo libero a disposizione del PSP per specificare il servizio;
- disponibilitàServizio: testo libero utilizzato dal PSP per specificare gli orari di erogazione tecnica del servizio;
- limitazioniServizio: informazioni in formato testo che riportano eventuali limitazioni poste dal PSP nell’erogazione del servizio, (esempio: Servizio dedicato ad una particolare categoria di professionisti o imprese);
- urlInformazioniCanale: URL di una pagina web contenente informazioni relative allo specifico servizio;
- tavoloOperativo: indica i riferimenti del presidio tecnico predisposto per cooperare con il Tavolo Operativo del NodoSPC.
8.4.2.2.3. Plugin¶
La struttura permette al PSP di definire un set di parametri personalizzato da utilizzare per interpretare i parametri della redirect di risposta alla pagina di erogazione del servizio WISP.
8.4.2.2.4. Costi¶
La struttura definisce la policy del calcolo delle commissioni che il sistema pagoPA deve applicare.
È possibile gestire le seguenti policy per il calcolo della commissione:
- Numero dei versamenti (tipoCostoTransazione = 0): tale policy calcola il costo della commissione in base al numero di versamenti da effettuare.
In questo caso:
- il numero delle occorrenze della struttura fasceCostoServizio dovrà essere pari a 1;
- l’elemento tipoCommissione dovrà essere 0 (in valore assoluto);
- l’elemento costoFisso dovrà essere 0.
- Totale versamento (tipoCostoTransazione = 1): tale policy calcola il costo della commissione in base al totale della transazione da effettuare. In questo caso è possibile specificare il costo della commissione in base alla fascia di prezzo.
8.4.2.2.5. Acquirer¶
L’Acquirer è un soggetto che ha instaurato un rapporto con un PSP aderente a pagoPA al fine di gestire le transazioni con le carte di pagamento, interagendo con il VPOS-AgID.
L’Acquirer viene configurato attraverso i seguenti parametri:
- TerminalID: Terminal Identification Number (TID);
- MerchantID: Merchant Identification Number (MID) che identifica il PSP relazionato con l’Aquirer;
- Bin: lista di Issuer Identification Number (IIN) che identifica le carte emesse dal PSP relazionato con l’Aquirer. Il pagamento con una carta il cui BIN è incluso in tale lista è autorizzato dall’Aquirer senza la necessità di accedere ai circuiti internazionali. Il NodoSPC gestirà questa tipologia di pagamenti inoltrando le relative RPT verso il canale ONUS del PSP. Il canale NOT_ON_US è utilizzato dal PSP per gestire i pagamenti con carte emesse da altri soggetti.
8.5. Giornale degli eventi¶
Il Giornale degli Eventi (GDE) ha l’obiettivo di consentire la tracciabilità di ogni operazione di pagamento (andata a buon fine o abortita) per il tramite del NodoSPC.
L’operazione di pagamento si sviluppa mediante la cooperazione applicativa tra sistemi diversi degli EC, del NodoSPC e dei PSP. È quindi necessario, per ricostruire il processo complessivo, che ognuno dei sistemi interessati dal pagamento telematico si doti di funzioni specifiche per registrare in modo standardizzato i passaggi principali del trattamento dell’operazione di pagamento. Gli eventi di ingresso e di uscita dal sistema, ovvero le attività che comportano l’attraversamento di una interfaccia, sono punti cardine da tracciare obbligatoriamente. Sul Giornale degli Eventi si devono altresì annotare i cambi di stato intermedi significativi per il sistema pagoPA.
Le tracce registrate dai singoli sistemi, in caso di richiesta di verifica, devono poter essere tempestivamente estratte, inviate al Tavolo Operativo presidiato dal NodoSPC in modo da essere confrontate con le analoghe informazioni prodotte da tutti i sistemi di collaborazione coinvolti nell’operazione in esame.
Ai fini del confronto sono state individuate tre aree di interesse da monitorare per poter tracciare un pagamento e risolvere eventuali anomalie:
- i messaggi scambiati tramite le interfacce esterne (SOAP/http/SFTP);
- gli oggetti scambiati durante un pagamento (RPT, RT, ecc.);
- le operazioni interne più significative (rappresentate nei capitoli successivi all’interno della presente sezione dalle operazioni associate e descritte per i diversi attori).
Nella tabella Tabella sottostante sono indicate le informazioni e le specifiche di rappresentazione dei dati che i soggetti appartenenti al Dominio sono tenuti a fornire per le verifiche di cui sopra. Questi dati sono altresì le informazioni “minime” da archiviare nel Giornale degli Eventi. Tali informazioni devono essere memorizzate presso le strutture che scambiano le informazioni (EC, PSP, Intermediari tecnologici, NodoSPC) e devono essere accessibili a richiesta, nei formati che saranno concordati.
Dato | Liv | Genere | Occ | Len | Contenuto |
---|---|---|---|---|---|
dataOraEvento | 1 | an | 1..1 | 19 | Indica la data e l’ora dell’evento secondo il formato ISO 8601, alla risoluzione del millisecondo e sempre riferito al GMT. Formato [YYYY]-[MM]-[DD]T[hh ]:[mm]:[ss.sss] |
io |
1 | an | 1..1 | 1..35 | Campo alfanumerico contenente il codice fiscale dell’EC che invia la richiesta di pagamento. |
coVersamento |
1 | an | 1..1 | 1..35 | Riferimento univoco assegnato al pagamento dall’ente beneficiario e presente nel messaggio che ha originato l’evento. |
ento |
1 | an | 1..1 | 1..35 | Codice univoco necessario a definire il contesto nel quale viene effettuato il versamento presente nel messaggio che ha originato l’evento. |
atoreServiziPagamento |
1 | an | 1..1 | 1..35 | identificativo del PSP univoco nel Dominio scelto dall’utilizzatore finale e/o dall’EC |
tipoVersamento | 1 | an | 0..1 | 1..35 | Forma tecnica di pagamento presente nel messaggio che ha originato l’evento. |
componente | 1 | an | 1..1 | 1..35 | Sistema o sottosistema che ha generato l’evento (es. FESP, WFESP) |
categoriaEvento | 1 | an | 1..1 | 1..35 | INTERNO/INTERFACCIA, indica se l’evento tracciato è relativo un’operazione di interfaccia con altri sistemi oppure se rappresenta un’operazione interna (es. cambio di stato) al proprio sistema |
tipoEvento | 1 | an | 1..1 | 1..35 | Identificativo del tipo di evento. Nel caso di interazioni SOAP è il nome del metodo SOAP. |
sottoTipoEvento | 1 | an | 1..1 | 1..35 | Nel caso di interazioni SOAP sincrone assume i valori req/rsp per indicare rispettivamente SOAP Request e SOAP Response. |
ore |
1 | an | 1..1 | 1..35 | Nel caso di eventi di tipo INTERFACCIA si deve utilizzare l’Identificativo del sistema del Soggetto richiedente nell’ambito del Dominio. (Es. identificativoStazion eIntermediarioPA nel caso della nodoInviaRPT) Nel caso di eventi di tipo INTERNO, si può utilizzare un nome di componente o sotto componente che genera l’evento. |
tore |
1 | an | 1..1 | 1..35 | Nel caso di eventi di tipo INTERFACCIA si deve utilizzare l’Identificativo del sistema del Soggetto rispondente nell’ambito del Dominio. (Es. “NodoDeiPagamentiSPC” nel caso della nodoInviaRPT) Nel caso di eventi di tipo INTERNO, si può utilizzare un nome di componente o sotto componente che processa l’evento. Per quest’ultima tipologia il valore può coincidere con l’identificativoFru itore, qualora non vi sia un componente che risponde all’evento stesso. |
oneIntermediarioPA |
1 | an | 0..1 | 1..35 | identificativo della Stazione dell’intermediario dell’EC nel sistema del NodoSPC, da cui è transitata la RPT/RT. |
canalePagamento | 1 | an | 0..1 | 1..35 | identificativo del Canale del PSP nel sistema del NodoSPC da cui è transitata/si vuole far transitare la RPT/RT. |
nterfaccia |
1 | an | 0..1 | 1..512 | parametri specifici utilizzati nell’interfaccia dal PSP o dall’ECnel modello di pagamento 1 o 3 |
Esito | 1 | an | 0..1 | 1..35 | Campo opzionale in base allo stato dell’operazione al momento della registrazione dell’evento. Obbligatorio nel caso di richieste SOAP. |
Tabella 4: Informazioni “minime” da archiviare nel “Giornale degli Eventi “
Il GDE dovrà contenere sia tutti gli eventi andati a buon fine, sia quelli abortiti fra cui quelli che hanno dato seguito ad un errore (evidenziando la categoria dell’errore ricevuto).
Qualora alcune delle informazioni richieste non fossero disponibili per una data operazione, i corrispondenti campi dovranno essere comunque valorizzati in uno dei due seguenti modi:
- N/A: nel caso il valore del campo non sia applicabile al sistema pagoPA per l’operazione tracciata (es. identificativoErogatore per un evento interno);
- UNKNOW, nel caso il campo sia applicabile, ma non sia stato possibile tracciare l’informazione richiesta.
Per quanto riguarda i PSP si precisa che deve essere sempre registrato, all’interno del Giornale degli Eventi, l’evento relativo alla generazione della RT (indipendentemente dall’esito del relativo pagamento) così valorizzando i seguenti campi del giornale:
- categoriaEvento a “INTERNO”;
- identificativoErogatore a “GENERAZIONE-RT”.