Come utilizzare l'Archivio Centralizzato Avvisi per creare, aggiornare o chiudere una posizione debitoria

L’Archivio Centralizzato Avvisi viene utilizzato dagli Enti Creditori e/o i loro Intermediari Tecnologici e/o Partner Tecnologici, i quali sono necessariamente obbligati a censire i dati personali sulle posizioni debitorie (tramite API Sincrone) per assicurare di rispettare le misure di servizio continuo richieste dalla Banca d'Italia.

Alcuni Enti Creditori sono esonerati dall’utilizzo dell’Archivio secondo quanto definito in SANP

L'obiettivo di questo tutorial è mostrare le API, con i set di dati necessari, che permettono ad un EC aderente al servizio, di creare, aggiornare o chiudere una posizione debitoria, utilizzabile in fase di stand-in, nei DB di PagoPA.

Il censimento della posizione servirà a garantire il continuo utilizzo dei servizi dell’Ente anche in caso di down, permettendo quindi ad un cittadino di effettuare il pagamento di una posizione debitoria anche in caso di disservizio da parte dell'EC. Inoltre permette anche al cittadino, tramite l’utilizzo del codice fiscale, il recupero di tutte le proprie posizioni debitorie.

Trattamento di dati personali

In relazione al trattamento dei dati personali, PagoPa S.p.A. funge da titolare autonomo del trattamento dei dati personali.

⚠ La legge obbliga PagoPa a sorvegliare questi dati, assicurando la continuità operativa del servizio e determinando i mezzi essenziali per il trattamento dei dati.

Creazione di una nuova posizione debitoria

Quando un Ente Creditore crea una nuova posizione debitoria, deve registrarla sull’Archivio Centralizzato Avvisi (ACA) utilizzando la funzione paCreatePosition, la quale grazie alla sua idempotenza permette sia di inserire che di aggiornare una posizione.

Per abilitare un EC all'utilizzo della paCreatePosition è necessario:

Generare un API-Key sul portale BackOffice PagoPA tramite l'Area Riservata PagoPA (per ulteriori informazioni relative al processo di adesione all’Area Riservata PagoPA fare riferimento al link: Area Riservata-Come Aderire)
Una volta generate le API-Key sono disponibili sul portale BackOffice PagoPA.
La chiave va inserita in tutte le chiamate alla piattaforma PagoPA nell'header HTTP Ocp-Apim-Subscription-Key .
La procedura si conclude con la verifica della raggiungibilità dei sistemi.

⚠ Le API-Key non hanno scadenza. Di norma si utilizza quella primaria, la secondaria può tornare utile nel caso sia necessario procedere alla rigenerazione della chiave primaria.

Qui di seguito è possibile trovare la body-request della precedente chiamata paCreatePosition (i campi sottolineati sono mandatori):

Elemento	Tipo	Descrizione
paFiscalCode	String	Codice fiscale dell’Ente Creditore che ha creato la posizione debitoria
entityType	Enum	Tipologia del debitore
entityFiscalCode	String	Codice fiscale del debitore
entityFullName	String	Nome e cognome del debitore
iuv	String	Identificativo univoco versamento
amount	AmountEuroCents	Importo (non è possibile censire una posizione con un importo uguale a zero): numero intero rappresentate l’importo e calcolato in centesimi di Euro. E.g., 1,52€ = 152
description	String	Causale
expirationDate	String	Data di scadenza della posizione debitoria (in formato ISO 8601 date-time. E.g., 2024-07-31T07:47:56.658Z)
iban	String	IBAN di riversamento
postalIban	String	IBAN postale di riversamento
switchToExpired	Boolean	Flag per indicare se la expirationDate è vincolante o meno
payStandIn	Boolean	Flag per indicare se la posizione è pagabile o meno in Stand In

Fasi di una Posizione Debitoria

Qui di seguito vengono censite e dettagliate le varie fasi del ciclo di vita di una Posizione Debitoria:

Fase di censimento
Fase di aggiornamento
Fase di annullamento
Fase di chiusura

Fase di censimento

La richiesta di creazione di una nuova posizione giunge all’ACA per mezzo della paCreatePosition, fornendo in input i seguenti dati:

fiscalCodePA: codice fiscale dell’Ente Creditore che ha creato la posizione debitoria;
entityUniqueIdentifierType: tipologia del debitore (F=persona fisica, G=persona giuridica);
entityUniqueIdentifierValue: codice fiscale del debitore;
fullName: Nome e Cognome del debitore;
IUV: identificativo univoco versamento;
amount: importo (non è possibile censire una posizione con un importo uguale a zero);
description: causale;
expirationDate: data di scadenza della posizione debitoria.

ACA effettua una verifica semantica e integra le informazioni della posizione:

viene verificata la presenza di tutti i campi obbligatori;
viene verificata l'esistenza dell'EC sulla piattaforma pagoPA;
recupera la denominazione dell’EC;
recupera l’IBAN che verrà utilizzato in fase di accredito.

Fase di aggiornamento

È obbligatorio effettuare un aggiornamento della posizione debitoria usando l'API-Key paCreatePosition nei seguenti casi:

Se l'importo deve essere modificato;
Se lo stato della posizione deve essere aggiornato per segnalare la chiusura o l'annullamento;
Se la data di scadenza deve essere aggiornata.

⚠ Questa chiamata deve essere effettuata contemporaneamente alla modifica dell'archivio dell'EC. Ogni volta che si aggiorna una posizione debitoria, la piattaforma aggiorna automaticamente anche l’informazione dell'IBAN di accredito recuperandolo dal BackOffice pagoPA.

Fase di annullamento

Se una posizione debitoria viene annullata o sostituita con una nuova, è obbligatorio eseguire l'annullamento richiamando l'API-Key paCreatePosition in questione. Questa chiamata deve essere effettuata insieme alla modifica dell'archivio dell'EC.

L'annullamento può essere effettuato solo impostando l'importo della posizione a zero.

Fase di chiusura

Se una posizione debitoria è stata pagata dal debitore tramite canali diversi dalla piattaforma pagoPA, è necessario utilizzare l'API-Key paCreatePosition per chiuderla. Questo processo di chiusura avviene solo impostando l'importo della posizione a zero.

Posizioni multi-beneficiario

Anche le posizioni debitorie multi-beneficiario devono essere inviate all'ACA inserendo nel campo fiscalCodePA il Codice Fiscale dell'Ente che ha creato la posizione debitoria.

⚠ Nei casi in cui il pagamento multi-beneficiario venga gestito tramite Stand-In, solo nel caso di conferimento all’ACA tramite paCreatePosition, le posizioni multi-beneficiario verranno riversate al solo EC presente nel campo fiscalCodePA. Sarà responsabilità di quest’ultimo assicurare una suddivisione accurata delle quote di pagamento tra gli ulteriori EC inseriti come beneficiari, nelle modalità da lui individuate in accordo con gli EC secondari

Gestione Ricevute

Invio di una ricevuta in caso di attivazione dello Stand-In

La ricevuta (receipt) è un documento generato dalla piattaforma pagoPA, la quale viene inoltrata agli Enti Creditori interessati al pagamento effettuato tramite la funzione paSendRT.

Se la paSendRT va in timeout o errore, oppure se l'Ente Creditore è irraggiungibile, viene avviata una procedura di procedura di backup al fine di ottenere una risposta valida dal destinatario, riprovando ad inviare ad eseguire la chiamata ogni ora fino all’ottenimento della risposta. Il limite massimo di chiamate che il sistema può compiere è 48 (equivalenti a provare ad ottenere la risposta per 2 giorni).

La chiamata paSendRT esiste in 2 versioni: la versione 2 permette di gestire i metadata in ogni singolo transfer della receipt, oltre alle informazioni ricavate da Gestione Evoluta Commissioni (i.e., un motore di regole che permette di definire il comportamento tutte le operazioni di pagamento della piattaforma, dando la possibilità ai PSP di creare pacchetti commissionali ad hoc per specifici pagamenti garantendo maggiore flessibilità) e il servizio @e.bollo.

Ai seguenti link è possibile trovare tutti gli attributi da specificare nel body della richiesta:

Recupero di una ricevuta

Il servizio di generazione ricevuta è rivolto a tutti gli Enti Creditori che devono recuperare una ricevuta non disponibile nel proprio sistema a causa di anomalie tecniche e permette di recuperare le ricevute conoscendo

IUR: riferimento unico dell'operazione assegnato al pagamento (Token di Pagamento)
IUV (opzionale): identificazione unica del pagamento. Codice alfanumerico che associa e identifica in modo univoco tre elementi chiave di un pagamento: causale, pagatore, importo

L’utilizzo del servizio non è disponibile durante tutte le fasi del processo di pagamento, ma soltanto dopo la ricezione dei flussi di rendicontazione.

La procedura di adesione al servizio è descritta in Adesione ai servizi con subscription key e dopo aver ottenuto la subscription key, è possibile iniziare ad utilizzare il servizio mediante l’invocazione della API getOrganizationReceipt.

Qui sono disponibili le informazioni dettagliate per la chiamata:

⚠ Il servizio non è pensato per un utilizzo massivo. Il servizio è limitato da politiche di throttling: massimo 10 chiamate ogni 60 minuti per lo stesso Ente Creditore.

In questa pagina