Table of contents
Reporting and cashflow
Every PSP registered with the platform uses the reporting flow to report on D+2 the details regarding the repayments made on D+1 through the accounts where the payment was credited that took place on credit accounts on business day D, as defined in the guidelines of the pagoPA platform, specifically in the SACI (Implementing specifications of the payment identifier codes).
The PSP send each individual reporting flow to the pagoPA platform via the primitive nodoInviaFlussoRendicontazione; to receive the reporting flows from the creditor, the primitives to use are the nodoChiediElencoFlussiRendicontazione, to have the list of the available flows, and the nodoChiediFlussoRendicontazione to download a specific flow.
For the sake of simplification, the following applies for the following diagrams:
- PSP side → for sending a single flow
- Creditor side → for the recovery of multiple flows.
This selection results from the nature of the functionality on the creditor’s side that requires:
- Recovery of the “list of flows”
- Recovery of the single flow (previously mentioned in the list)
For the PSPs, there is a single method for sending the reporting flows to the pagoPA platform:
- SOAP (Web Service)
There are instead 2 possible configurations (mutually exclusive) for the creditor related to the receipt of the reporting flows:
- SOAP (Web Service)
- SFTP (Secure File Transfer Protocol)
.png)
.png)
As concerns the nodoChiediElencoFlussiRendicontazione, the platform responds independently of the creditor’s configuration (SOAP or SFTP), in both cases in fact the platform responds with a reporting flow list. The use of the primitive in the case of an SFTP configuration is optional and a possible reason for its use is for statistical purposes.
As concerns the nodoChiediFlussoRendicontazione, the platform responds differently based on the creditor's configuration:
- reception via web service SOAP → XML file: reporting flow in base64 binary
- reception via server SFTP → unlike the standard primitive, no XML file is returned as output
In the case of SFTP configuration, the call in question is optional, in fact the file is not deposited at the moment of the creditor's request with the primitive, but takes place as soon as the flow is available to the node.
An example of an xml file of the reporting flow contained in the xmlRendicontazione tag in base64 format.
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>Bank transfer 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>
32A PSP has the possibility of sending multiple flows to the same creditor via the primitive nodoInviaFlussoRendicontazione with the same identificativoFlusso but with a different dataOraFlusso. This option allows the PSP to overwrite a flow that was already sent if the flow that was already sent needs corrections.
Remember also that the identificativoFlusso must be univocal during the year of reference of the payment transactions to which the flow refers, and as a result the same identificativoFlusso can be used more than once during the same year only if sending an overwriting flow.
Example:
- incorrect identificativoFlusso flow = abc, dataOraFlusso = 2019-01-01T10🕛️00
- correct identificativoFlusso flow = abc, dataOraFlusso = 2019-01-01T14🕛️00
Once a PSP has sent a flow with a certain identificativoFlusso, to overwrite it they must sent a flow with the same identificativoFlusso but with a dataOraFlusso that is higher than the one previously sent.
The overwriting flow is considered valid if sent by and no later than 24 hours from the fourth business day after receiving the payment order(D+4).
The following two examples show the behaviors of the payment node if two flows are transmitted in succession:
- Example 1
- Transmission 1: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T10🕛️00
- Transmission 2: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14🕛️00
The node accepts the reporting flow of the second transmission.
- Example 2
- Transmission 1: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T10🕛️00,
- Transmission 2: identificativoFlusso = abc, dataOraFlusso = 2019-01-01T07🕛️00
The node will reject the reporting flow of the second transmission (the same would occur also if the second date/time were identical to the first one).
When the creditor requests the list of flows (nodoChiediElencoFlussiRendicontazione) the payment node must respond, for a certain identificativoFlusso, with the most recent flow available, in reference to the previous example 1, and assuming that the request takes place after receiving the second flow from the node:
- identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14🕛️00
The list of flows is returned to each request, according to the following logic based on optional input parameters that can be entered in the request:
- idDominio
- if specified → the platform returns the list of the specified creditor;
- if not specified → the platform returns the list of all creditors of the technological intermediary or partner through which the request passed;
- identificativoPSP
- if specified → the platform returns the list of the specified PSP;
- if not specified → the platform returns the lists of all PSPs.
The node currently does not keep track of the flows already downloaded by the creditor, and for this reason all the flows available on the platform are returned. The creditor is responsible for understanding which flows must be requested and which have already been processed, keeping in mind that a PSP can overwrite a flow according to the logic specified above.
For correct management, the creditor must check and, if necessary, manage the content associated with each individual identificativoFlusso that was sent up to the fourth working day (D+4) following the receipt of the payment order.
As it is not possible for the creditor to filter the returned elements by time or quantity, a platform property has been defined that permits limiting the time interval on which the response to the call is based, the property is the same for the entire platform and is currently set to 30 days.
The creditor, therefore, requests the single flow (nodoChiediFlussoRendicontazione) providing only the identificativoFlusso as input and not the dataOraFlusso (in reference to the request example shown above identificativoFlusso = abc)
The node must respond in compliance with what is declared in the previous primitive (nodoChiediElencoFlussiRendicontazione) and therefore provide the most recent flow for that identificativoFlusso, in reference to the previous example:
The node must respond in compliance with what is declared in the previous primitive (nodoChiediElencoFlussiRendicontazione) and therefore provide the most recent flow for that identificativoFlusso, in reference to the previous example:
- identificativoFlusso = abc, dataOraFlusso = 2019-01-01T14🕛️00
PagoPA will provide the creditors/PSPs with new primitives for managing the download/upload of the reporting flows.
The purpose of introducing the new services is to optimize the current logic flow by optimally managing all the management phases of reporting flows, even large ones.
The creditors and PSPs can adjust the calls to the primitives made available by the pagoPA platform to be able to manage the reporting flows in an efficient manner.
To be able to use the new APIs, it will be necessary to subscribe to the new product that makes the primitives listed below available. For more information on how to request a subscription to a new product, refer to the guide provided by the following link Connectivity.
Two new products are made available:
- "FDR - Reporting Flow [ORG]" - API for the creditors
- "FDR - Reporting Flow [PSP]" - API for the PSPs
The new processes is illustrated below:
.png)
The new process involves the introduction of three new functions, which are described in the following paragraphs.
Examples of the calls can be referenced in the section Primitives - New reporting flow primitives.
The new method for transmitting the flows introduced the possibility of splitting up a large sized flow into many small packages.
The PSPs who want to upload a reporting flow perform an initial call with the signature:
POST ``/psps/{pspId}/fdrs/{fdr}
At the end of the call, the payment node is ready to receive all the packages that will make up the entire flow.
The addition of packages takes place via the client call with the signature:
PUT ``/psps/{pspId}/fdrs/{fdr}/payments/add
The call can be repeated until the last package making up the reporting flow is transmitted.
The call with the signature can be used:
PUT ``/psps/{pspId}/fdrs/{fdr}
To cancel an incorrectly loaded package.
When all of the packages have been loaded, the flow can be published via the call with signature:
POST ``/psps/{pspId}/fdrs/{fdr}/publish
Or the inserted packages can be eliminated via the call with signature:
DELETE/psps/{pspId}/fdrs/{fdr}
The creditor who wants to download the list of reporting flows that have not yet been downloaded can do so with the signature:
GET ``/organizations/{organizationId}/fdrs
The primitive returns the flows according to the logic described in paragraph Flow list.
The creditor who wants to request a flow contained in the flow list can use the call with signature:
GET/organizations/{organizationId}/fdrs/{fdr}/revisions/{revision}/psps/{pspId}
If the size of the requested flow is large, it can be downloaded with the signature:
GET/organizations/{organizationId}/fdrs/{fdr}/revisions/{revision}/psps/{pspId}/payments
which recovers all the paged payments.
Tell us what you think
For clarifications on implementation specifications, such as SACI and SANP, you can open an issue on GitHub