Table of contents
Integration via synchronous API
Centralized Notice Archive
If the creditors and/or their technological intermediaries and/or technological partners make use of the integration via synchronous API, they are required to assign all debt position data to the Centralized Notice Archive (“ACA”), required for ensuring the measures of operational continuity that must be adopted by operators of payment systems and by critical suppliers of infrastructures or technical services in compliance with the obligations pursuant to art. 146 T.U.B. (Consolidated Banking Law) of monitoring performed by Banca d'Italia.
It remains understood that, for processing personal data connected to the Centralized Notice Archive, PagoPa S.p.A. operates as the autonomous data controller, as the cited law requires that it performs the monitoring obligations specified therein which therefore makes the latter responsible for implementing the above-mentioned purpose of operational continuity and determining the essential means of processing.
Each creditor, at the moment of creating a new debt position, must register it in the ACA using one of the following methods:
- API for creating and updating the Debt Position Management (“GPD”) service;
- API paCreatePosition.
Conditions for exclusion from assignment of positions to ACA
It is possible to define the exclusions from the assignment of positions to ACA via the pagoPA backoffice.
The reason to be attributed to all the cases of exclusion is exclusively the generation of the debt position upon direct request of the debtor and at the moment of payment (which includes, for example, but is not limited to the so-called on the fly payments at the frontend of the creditor). Alternatively, there is the case of payment notices generated by the portal of the creditor upon request of the debtor, but that can be printed and/or paid at a later time with respect to the creation of the debt position and the relative payment notice.
Assignment via the paCreatePosition
The paCreatePosition, thanks to the idempotency property makes it possible to both insert and update the position.
For the procedure for enabling the use of paCreatePosition it is necessary to refer to the chapter Connectivity.
Registration phase
The request to create a new position reaches the ACA via paCreatePosition, providing the following data as input:
- paFiscalCode: fiscal code of the creditor who created the debt position;
- entityType: type of debtor (F=physical person, G=legal person);
- entityFiscalCode: fiscal code of the debtor;
- entityFullName: first and last name of the debtor;
- nav: number of the notice;
- iuv: univocal payment identifier;
- amount: amount (it is not possible to register a position with an amount equal to zero);
- description: reason;
- expirationDate: expiration date of the debt position;
- Iban: Repayment IBAN (optional);
- postalIban: Repayment postal IBAN (optional);
- switchToExpired: flag for indicating whether or not the dueDate is binding;
- payStandIn: flag for indicating whether or not the position can be paid in Stand In mode.
ACA performs a semantic check and supplements the information for the position:
- it is checked if all mandatory fields are present;
- it is checked if the creditor exists on the pagoPA platform;
- recovery of the name of the creditor;
- If the Iban and postalIban fields were not sent, the system recovers the IBAN that will be used during the credit phase by searching for the one configured by the creditor via the pagoPa backoffice or, if this configuration is not present, the one with the most recent change is used.
Multi-beneficiary positions
Also the multi-beneficiary debt positions must be sent to the ACA, with the considerations described below.
The fiscal code of the institution that created the debt position must be entered in the fiscalCodePA field.
The data structure confirms that there is a single total amount communicated by the creditor, which represents the sum of the amounts present in the various transfers of the original debt position. This implies that the Stand In functionality, only and exclusively in the case of assignment to the ACA via the paCreatePosition, cannot manage the division of the amounts into a multi-beneficiary debt position, as the information necessary for the management of this payment structure is not provided.
Update phase
It is mandatory to update the debt position by calling the above-mentioned paCreatePosition API in the following cases:
- update of the amount;
- update of the status, to communicate the closure or cancellation of the position, setting the value of the amount value to zero;
- update of the expiration date.
The call must be made at the same time as the change made in the creditor archive.
Each time a debt position is updated, the platform also automatically updates the information for the IBAN of credit, recovering it from the pagoPA backoffice.
Cancellation phase
If a position is canceled or replaced with a new one, it is mandatory to cancel the debt position, calling the above-mentioned API paCreatePosition.
The call must be made at the same time as the change made in the creditor archive.
The cancellation can only be made by setting the value of the amount field to zero.
Closing phase
If the debtor pays the debt position using channels different than the pagoPA platform, it is necessary to call the above-mentioned API paCreatePosition to close it.
The position can only be closed by setting the value of the amount field to zero.
Debt position creation request phase
In the case of “Spontaneous payment via a PSP” the paDemandPaymentNotice is used to request the creditor to create the debt position based on the data sent for the specific service, the creditor sends in response the information necessary to start the payment process, in particular:
- number of the notice;
- the fiscal code of the creditor to use during the activation phase;
- the amount.
During this phase the status of the debt position must still be open.
The creditors provide the data for the specific service via the service catalog.
Verification phase
The paVerifyPaymentNotice is used to request the creditor to verify the payment option identified by the notice number, who sends the payment information related to the notice number, in particular:
- amount;
- fiscal code of the beneficiary creditor;
- the allCCP parameter, which indicates whether or not the payment option can be associated to all postal current accounts
- allCCP = true: the option can be associated with all postal current accounts;
- allCCP = false: the option cannot be associated with all postal current accounts.
During this phase the status of the debt position must still be open.
The Node performs a semantic check of the response:
- the paymentList must be present;
- the officeName tag is optional, all remaining tags are mandatory.
Activation phase
The request to activate the payment reaches the creditor via paGetPayment, the creditor sends the amount of the payment and the data necessary for the repayment of the amount, and in particular for each payment:
- partial amount;
- fiscal code of the beneficiary creditor;
- IBAN to use for the repayment.
During this phase the status of the debt position must still be open, the Node will inhibit other payment attempts for the same notice number.
The Node performs a semantic check of the response:
- it checks the correspondence between the value of the paymentAmount and the total of all the amounts present in the transfers;
- there must be at least one transfer occurrence;
- semantic check of the IBANs in every transfer;
- the existence of the association between fiscalCodePA and IBAN in the Node is checked;
- if there is a secondary creditor, it is checked that it is enabled on the Node.
By means of the primitive paSendRT, the receipt is sent to the n creditors involved with the payment only if the payment was made, the receipt is an object generated by the pagoPA platform.
In this phase, after receiving the receipt, the debt position must be put in the “closed” state.
If the paSendRT has a timeout/error response or if the creditor cannot be reached, a retry procedure is started to obtain a valid response from the recipient according to the logic of the following table.
| Number of attempts | Interval between each attempt |
|---|---|
| 48 | 1 hour |
Receipt recovery
The service is offered to all creditors who, in particular cases, need to recover a receipt that is not available in their system due to specific technical and/or processes errors.
As will be widely explained in the following sections the services is not thought to be used during all phases of the payment process, but only in specific cases and in particular after receiving the reporting flows. Throttling policies have been implemented to protect the nature of the service that limit the number of calls the same creditor can make during a period of time.
If a receipt is not available while processing the flow, the exception can be managed by attempting to recover it by invoking the getOrganizationReceipt service.
The following diagram shows instead a use case that is not permitted
It is absolutely prohibited to insert the invocation of the service getOrganizationReceipt within a loop in an indiscriminate manner without there being an error event that justifies its use.
The procedure for registering with the service is described in Registration with services with a subscription key.
After obtaining the subscription key, it is possible to start using the service by invoking the getOrganizationReceipt API.
The details of the signature of the service are provided below:
GET /organizations/{organizationfiscalcode}/receipts/{iur}/paymentoptions/{iuv}
As can be seen, the service performs a search for the receipt using three input parameters as a filter, setting the following path parameters as follows:
- organizationalfiscalcode: creditor fiscal code;
- iur: univocal collection identifier, included in the reporting flow received from the pagoPA node by invoking the primitive nodoChiediFlussoRendicontazione;
- iuv: univocal payment identifier, also this is included in the reporting flow.
The service is not designed for massive use, and to protect this characteristic throttling policies have been activated that permit a maximum of 10 calls during a period of 60 minutes for each subscriber to the service.
For all details concerning the correct use of the service, it is possible to refer to the primitive specifications in getOrganizationReceipt.
Tell us what you think
For clarifications on implementation specifications, such as SACI and SANP, you can open an issue on GitHub