Tabella dei contenuti
Rendicontazione e Cashflow
Ogni PSP aderente alla piattaforma in data D+2 rendiconta tramite il flusso di rendicontazione il dettaglio dei riversamenti effettuati nella giornata D+1 verso i conti di accredito dei pagamenti avvenuti nella giornata operativa D, come definito nelle Linee Guida della piattaforma pagoPA, nello specifico nelle SACI.
I PSP inviano ogni singolo flusso di rendicontazione alla piattaforma pagoPA tramite la primitiva nodoInviaFlussoRendicontazione; per la ricezione dei flussi di rendicontazione da parte degli EC le primitive da usare sono la nodoChiediElencoFlussiRendicontazione, per avere l'elenco dei flussi disponibili, e la nodoChiediFlussoRendicontazione per scaricare uno specifico flusso.
Per semplicità di “narrativa” negli schemi successivi ci si riferisce sempre:
- lato PSP → all’ invio di un singolo flusso
- lato EC → al recupero di molteplici flussi.
Questa scelta è data dalla natura della funzionalità lato EC che prevede:
- Recupero di “lista di flussi”
- Recupero del singolo flusso (menzionato precedentemente in lista)
Per i PSP esiste un unica modalità di invio di flussi rendicontazione alla piattaforma pagoPA:
- SOAP (Web Service)
Esistono, invece, 2 configurazioni possibili (mutuamente esclusive) per l’EC relativamente alla ricezione dei flussi di rendicontazione:
- SOAP (Web Service)
- SFTP
.png)
%20(1).png)
Per quanto riguarda la nodoChiediElencoFlussiRendicontazione la piattaforma risponderà in maniera indipendente dalla configurazione dell'EC (SOAP o SFTP), in entrambi i casi infatti la piattaforma risponderà con un elenco di FdR. L’utilizzo della primitiva in caso di configurazione SFTP è opzionale e un possibile motivo per l’utilizzo riguarda finalità statistiche.
Per quanto riguarda la nodoChiediFlussoRendicontazione la piattaforma risponderà in maniera differente in base alla configurazione dell’EC:
- ricezione via web service SOAP → file XML: flusso di rendicontazione in base64 binary
- ricezione via server SFTP → a differenza della primitiva standard, non viene restituito in output alcun file XML
In caso di configurazione SFTP la chiamata in questione è opzionale, infatti, il deposito del file non avviene al momento della richiesta dell' EC con primitiva, ma avviene non appena il flusso è disponibile al Nodo.
Di seguito un esempio di xml del Flusso di Rendicontazione contenuto nel tag xmlRendicontazione nel formato base64.
1<FlussoRiversamento xmlns="http://www.digitpa.gov.it/schemas/2011/Pagamenti/">
2 <versioneOggetto>1.0</versioneOggetto>
3 <identificativoFlusso>2021-11-21ABI00000-AABB648200001295</identificativoFlusso>
4 <dataOraFlusso>2021-11-22T00:37:32</dataOraFlusso>
5 <identificativoUnivocoRegolamento>Bonifico SEPA-00000-AABB0</identificativoUnivocoRegolamento>
6 <dataRegolamento>2021-11-21</dataRegolamento>
7 <istitutoMittente>
8 <identificativoUnivocoMittente>
9 <tipoIdentificativoUnivoco>B</tipoIdentificativoUnivoco>
10 <codiceIdentificativoUnivoco>ABI00000</codiceIdentificativoUnivoco>
11 </identificativoUnivocoMittente>
12 <denominazioneMittente>BANCO DI XXXXXXXX SPA</denominazioneMittente>
13 </istitutoMittente>
14 <istitutoRicevente>
15 <identificativoUnivocoRicevente>
16 <tipoIdentificativoUnivoco>G</tipoIdentificativoUnivoco>
17 <codiceIdentificativoUnivoco>77777777777</codiceIdentificativoUnivoco>
18 </identificativoUnivocoRicevente>
19 <denominazioneRicevente>XXXXXXXXXXX</denominazioneRicevente>
20 </istitutoRicevente>
21 <numeroTotalePagamenti>1</numeroTotalePagamenti>
22 <importoTotalePagamenti>1234.56</importoTotalePagamenti>
23 <datiSingoliPagamenti>
24 <identificativoUnivocoVersamento>12210209926737900</identificativoUnivocoVersamento>
25 <identificativoUnivocoRiscossione>2130101502302932577</identificativoUnivocoRiscossione>
26 <indiceDatiSingoloPagamento>1</indiceDatiSingoloPagamento>
27 <singoloImportoPagato>1234.56</singoloImportoPagato>
28 <codiceEsitoSingoloPagamento>0</codiceEsitoSingoloPagamento>
29 <dataEsitoSingoloPagamento>2021-11-21</dataEsitoSingoloPagamento>
30 </datiSingoliPagamenti>
31</FlussoRiversamento>
32Un PSP ha la possibilità di mandare più flussi allo stesso EC tramite la primitiva nodoInviaFlussoRendicontazione con lo stesso identificativoFlusso ma con dataOraFlusso differente. Questa opzione permette al PSP di sovrascrivere un flusso già inviato, in caso un flusso già inviato necessitasse di correzioni.
Si ricorda, inoltre, l'identificativoFlusso deve essere univoco nell’ambito dell’anno di riferimento delle operazioni di pagamento cui si riferisce il flusso, di conseguenza lo stesso identificativoFlusso può essere usato più di una volta nel corso dello stesso anno solo nel caso di invio di un flusso di sovrascrittura.
Esempio:
- Flusso errato identificativoFlusso = abc, dataOraFlusso = 2019-01-01T10🕛️00
- Flusso corretto identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14🕛️00
Un PSP una volta inviato un flusso con un determinato identificativoFlusso, per sovrascriverlo deve inviare un flusso con lo stesso identificativoFlusso ma con dataOraFlusso superiore a quella inviata in precedenza.
Il flusso di sovrascrittura è ritenuto valido se inviato entro, e non oltre, le ore 24 della quarta giornata lavorativa successiva alla ricezione dell’ordine di pagamento (D+4).
Nei seguenti due esempi sono mostrati i comportamenti del Nodo dei pagamenti in caso di due invii successivi:
- Esempio 1
- Invio 1: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T10🕛️00
- Invio 2: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14🕛️00
Al secondo invio, il nodo accetterà il flusso di rendicontazione.
- Esempio 2
- Invio 1: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T10🕛️00,
- Invio 2: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T07🕛️00
Al secondo invio il Nodo rifiuterà il flusso di rendicontazione (lo stesso accadrebbe anche se la seconda dataTora fosse identica alla prima).
Quando l’EC richiede l'elenco dei flussi (nodoChiediElencoFlussiRendicontazione) il Nodo dei pagamenti deve rispondere, per un determinato identificativoFlusso, con il flusso più recente a disposizione, in riferimento al precedente esempio 1 e supponendo che la richiesta avvenga dopo la ricezione del secondo flusso da parte del nodo:
- identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14🕛️00
Ad ogni richiesta vengono restituiti gli elenchi dei flussi secondo la seguente logica sui parametri di input opzionali eventualmente inseriti nella request:
- idDominio
- se specificato → la piattaforma restituisce l'elenco dell’EC specificato;
- se non specificato → la piattaforma restituisce gli elenchi di tutti gli EC dell’Intermediario o Partner Tecnologico tramite cui è transitata la richiesta;
- identificativoPSP
- se specificato → la piattaforma restituisce l'elenco del PSP specificato;
- se non specificato → la piattaforma restituisce gli elenchi di tutti i PSP.
Attualmente il Nodo non tiene traccia dei flussi già scaricati dall’EC, per questo motivo vengono sempre restituiti tutti i flussi disponibili sulla piattaforma, rimane compito dell’EC comprendere quali flussi sono da richiedere e quali sono già stati elaborati, tenendo a mente che un PSP può sovrascrivere un flusso secondo le logiche sopra esposte.
Per una corretta gestione l'EC deve verificare ed eventualmente gestire il contenuto associato ad ogni singolo identificativoFlusso inviato fino alla quarta giornata lavorativa (D+4) successiva alla ricezione dell’ordine di pagamento.
Non esistendo lato EC possibilità di filtrare, né temporalmente, né quantitativamente gli elementi restituiti, è stata definita una proprietà della piattaforma che permette di limitare l'intervallo temporale su cui basarsi per rispondere alla chiamata, la proprietà è unica per tutta la piattaforma e attualmente è impostata a 30 giorni.
L’EC, quindi, richiede il singolo flusso (nodoChiediFlussoRendicontazione) fornendo in input esclusivamente identificativoFlusso e non dataOraFlusso (in riferimento alla richiesta di esempio qui sopra identificativoFlusso = abc)
Il Nodo deve rispondere coerentemente con quanto dichiarato nella primitiva precedente (nodoChiediElencoFlussiRendicontazione) e fornire quindi il flusso più recente per quell'identificativoFlusso, in riferimento all'esempio precedente:
Il Nodo deve rispondere coerentemente con quanto dichiarato nella primitiva precedente (nodoChiediElencoFlussiRendicontazione) e fornire quindi il flusso più recente per quell'identificativoFlusso, in riferimento all'esempio precedente:
- identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14🕛️00
PagoPA metterà a disposizione degli EC/PSP delle nuove primitive per la gestione di download/upload dei FdR.
Ogni PSP aderente alla piattaforma, in data D+2, rendiconta tramite il flusso di rendicontazione il dettaglio dei riversamenti effettuati nella giornata D+1 verso i conti di accredito dei pagamenti avvenuti nella giornata operativa D, come definito nelle Linee Guida della piattaforma pagoPA, in particolare nelle SACI.
PagoPA metterà a disposizione degli EC/PSP delle nuove primitive REST per la gestione di download/upload dei FdR.
Gli EC ed i PSP potranno adeguare le chiamate alle primitive messe a disposizione dalla piattaforma pagoPA per poter gestire in maniera efficiente gli FdR.
Per poter usufruire delle nuove API sarà necessario effettuare una sottoscrizione al prodotto che mette a disposizione le primitive di seguito elencate. Per maggiori informazioni su come richiedere una sottoscrizione ad un nuovo prodotto si può far riferimento ai manuali per la creazione di nuove API Key per EC e PSP.
Vengono messi a disposizione due nuovi prodotti:
- "FDR - Flussi di rendicontazione [ORG]" - API per gli Enti Creditori
- "FDR - Flussi di rendicontazione [PSP]" - API per i PSP
Si riporta di seguito il disegno del nuovo processo:
Il processo prevede l'introduzione di diversi step, descritti nei paragrafi seguenti.
Gli esempi delle chiamate sono consultabili sul developer portal.
Azioni disponibili per l'invio e la gestione dei flussi di rendicontazione
Lato PSP :
- Avvio del caricamento flusso:
Il PSP avvia il processo notificando al sistema l’intenzione di inviare un nuovo flusso di rendicontazione, il cui nome deve essere univoco nell’anno di riferimento delle operazioni di pagamento. In questo step, imposta tutte le informazioni caratteristiche del flusso, quali il totale rendicontato dal flusso, il numero di pagamenti inclusi nel flusso, l’ente ricevente e così via. Questa operazione è consentita solo se non esistono altri flussi con lo stesso nome già creati e in attesa di pubblicazione. - Invio dei pacchetti:
Il PSP provvede ad inviare al sistema i riferimenti dei pagamenti da includere nel flusso di rendicontazione. Il flusso può essere popolato suddividendo l’inserimento in più pacchetti di dimensioni entro un tetto massimo di 1000 pagamenti, inviati e gestiti autonomamente. Questa operazione può essere ripetuta fino al completamento del flusso. Nel caso in cui l’inserimento di un determinato pacchetto dovesse andare in errore, tutti i pagamenti inclusi in esso non vengono inseriti nel flusso di rendicontazione ed è pertanto possibile inviarlo nuovamente senza ottenere conflitti. Questa operazione è permessa solo se il flusso non è stato già pubblicato. Per garantire un utilizzo uniforme del traffico, a ciascun PSP viene applicato un limite di 10 richieste al secondo e 300 richieste al minuto. - Eliminazione di un pacchetto:
Il PSP, nel caso in cui un singolo pagamento o un pacchetto precedentemente inviato deve essere rimosso dal flusso di rendicontazione, può decidere di eliminarlo definitivamente. Nel caso in cui la cancellazione di un determinato pacchetto di pagamenti dovesse andare in errore, tutti i pagamenti inclusi in esso non vengono rimossi dal flusso di rendicontazione ed è pertanto possibile eseguire nuovamente l’operazione senza ottenere conflitti. Questa operazione è permessa solo se il flusso non è stato già pubblicato. Per garantire un utilizzo uniforme del traffico, a ciascun PSP viene applicato un limite di 10 richieste al secondo e 300 richieste al minuto. - Pubblicazione del flusso:
l PSP, dopo aver inviato tutti i pacchetti di pagamenti, può pubblicare il flusso di rendicontazione al fine di renderlo disponibile agli Enti Creditori (EC). Questa operazione è permessa solo se il flusso non è stato già pubblicato. - Cancellazione dell'intero flusso:
Il PSP, in alternativa alla pubblicazione, può decidere di eliminare un intero flusso e tutti i pacchetti di pagamenti ad esso associati. Nel caso in cui la cancellazione dovesse andare in errore, tutti i pagamenti inclusi in esso non vengono rimossi dal flusso di rendicontazione ed è pertanto possibile eseguire nuovamente l’operazione senza ottenere conflitti. Questa operazione è permessa solo se il flusso non è stato già pubblicato.
Lato Ente Creditore:
- Richiesta dell'elenco dei flussi disponibili:
L’EC può richiedere l’elenco dei flussi di rendicontazione ad essa associati. E’ possibile recuperare unicamente i flussi di rendicontazione degli ultimi 30 giorni. - Download di un flusso specifico:
Dopo aver ottenuto l’elenco, l’EC può richiedere il download di un singolo flusso di rendicontazione. Se il flusso richiesto è molto grande, deve essere scaricato in forma paginata, recuperando i pagamenti suddivisi per blocchi. E’ possibile recuperare unicamente i flussi di rendicontazione degli ultimi 30 giorni.
Revisioni dei Flussi di Rendicontazione
Un PSP ha la possibilità di sottomettere lo stesso flusso di rendicontazione utilizzando lo stesso identificativo. Questa funzionalità è utile nel caso in cui si voglia inviare una versione revisionata e corretta di un certo flusso di rendicontazione precedentemente pubblicato.
Nel caso in cui il flusso di rendicontazione non sia ancora stato pubblicato, è invece necessario prima cancellare il flusso in stato di bozza, quindi ripetere l’intero processo: creazione, aggiunta dei pagamenti e pubblicazione. Questo consente di evitare la proliferazione di versioni errate del flusso di rendicontazione.
Tutte le revisioni pubblicate da un PSP sono consultabili dall'EC destinatario, qualora ne avesse la necessità. L’API dedicata alla consultazione dei flussi di rendicontazione consente all’EC di ottenere, per ciascun flusso, le informazioni principali relative all’ultima revisione disponibile. Da lì, è possibile recuperare direttamente l’ultima versione pubblicata oppure ricercare tra le revisioni precedenti, specificando il numero di revisione. Poiché il sistema non registra quali flussi siano già stati scaricati dall’EC, spetta a quest’ultimo gestire autonomamente lo stato di elaborazione, distinguendo tra flussi già acquisiti e flussi ancora da recuperare. È importante considerare che un PSP potrebbe generare nuove revisioni di un determinato flusso, qualora necessario. Per una corretta gestione, l’EC deve quindi verificare e monitorare la revisione ed il contenuto del flusso ricevuto, tenendo conto che eventuali nuove versioni possono avvenire fino alle ore 00:00 della quarta giornata lavorativa (D+4) successiva alla ricezione dell’ordine di pagamento.
Un PSP può quindi inviare più volte un flusso con lo stesso identificativo (campo fdr della richiesta di creazione flusso), ma nel rispetto di regole precise. Il sistema accetta una nuova revisione dello stesso flusso di rendicontazione solo se la data ad esso associata (campo fdrDate della richiesta di creazione flusso) è successiva a quella dell’ultima versione pubblicata del flusso. La nuova revisione del flusso di rendicontazione è ritenuta valida se pubblicata entro e non oltre le ore 00:00 della quarta giornata lavorativa (D+4) successiva alla ricezione dell’ordine di pagamento.
I PSP, gli EC, i Partner Tecnologici e gli Intermediari possono operare sui flussi di rendicontazione esclusivamente per i soggetti sui quali risultano abilitati o per i quali possiedono una delega valida.
Dicci cosa ne pensi
Per chiarimenti sulle specifiche d’implementazione, come SACI e SANP, puoi aprire una segnalazione su GitHub