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
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.
Un 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:00
Flusso corretto identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14:00: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:00
Invio 2: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14:00:00
Al secondo invio, il nodo accetterà il flusso di rendicontazione.
Esempio 2
Invio 1: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T10:00:00,
Invio 2: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T07:00: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: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:
identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14:00:00
PagoPA metterà a disposizione degli EC/PSP delle nuove primitive per la gestione di download/upload dei FdR.
L'introduzione dei nuovi servizi ha l’obiettivo di ottimizzare l’attuale flusso logico, gestendo in maniera ottimale tutte le fasi di gestione dei FdR, anche di dimensioni elevate.
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 nuovo 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 alla guida riportata al link Connettività.
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 nuovo processo prevede l'introduzione di tre nuove funzioni, descritte nei paragrafi seguenti.
Gli esempi delle chiamate sono consultabili nella sezione Primitive - Nuove primitive FdR.
La nuova modalità di invio dei flussi introduce la possibilità di spezzettare un flusso di grandi dimensioni, in tanti piccoli pacchetti.
I PSP, che intendono caricare un flusso di rendicontazione, effettuano una prima chiamata con la signature:
POST /psps/{pspId}/fdrs/{fdr}
Al termine della chiamata il nodo dei pagamenti è pronto a ricevere tutti i pacchetti che andranno a comporre l'intero flusso.
L'aggiunta dei pacchetti avviene tramite la chiamata client con la signature:
PUT /psps/{pspId}/fdrs/{fdr}/payments/add
La chiamata può essere ripetuta tante volte fino all'invio dell'ultimo pacchetto che compone il flusso di Rendicontazione.
Può essere utilizzata la chiamata con la signature:
PUT /psps/{pspId}/fdrs/{fdr}
Per cancellare un pacchetto erroneamente caricato.
Quando tutti i pacchetti sono stati caricati, può essere publicato il flusso tramite la chiamata con signature:
POST /psps/{pspId}/fdrs/{fdr}/publish
Oppure si può decidere di eliminare i pacchetti inseriti tramite la chiamata con signature:
DELETE/psps/{pspId}/fdrs/{fdr}
L'EC che intende scaricarsi l'elenco dei flussi di rendicontazione non ancora scaricati, può effettuarlo tramite signature:
GET /organizations/{organizationId}/fdrs
La primitiva restituisce i flussi secondo le logiche descritte nel paragrafo Elenco Flussi.
L’EC, che intende richiedere un flusso contenuto nell'elenco dei flussi, può utilizzare la chiamata con signature:
GET/organizations/{organizationId}/fdrs/{fdr}/revisions/{revision}/psps/{pspId}
Se il flusso richiesto è di grandi dimensioni può essere scaricato tramite la signature:
GET/organizations/{organizationId}/fdrs/{fdr}/revisions/{revision}/psps/{pspId}/payments
che recupera tutti i pagamenti paginati.
