> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazione-con-intermediari-di-pagamento-pagopa/schema-di-funzionamento.md). # Schema di Funzionamento ### Creazione di un pagamento Un pagamento nasce da una interazione con il cittadino: il cittadino presenta una pratica per la quale l'Ente richiede un pagamento.

Rispetto al Core della piattaforma, i pagamenti sono gestiti mediante un insieme dedicato di microservizi

Il cuore dell'integrazione con un intermediario di pagamento è un microservizio apposito che dialoga con l'intermediario da un lato, implementando le chiamate specifiche in protocollo ReST o SOAP, e con il core della piattaforma dall'altro lato, mediante la lettura e la scrittura su un topic di Kafka. ## Componenti coinvolte ### Componenti del core della piattaforma In questo momento i pagamenti hanno una relazione 1 a 1 con le pratiche, di conseguenza ci sono due servizi che fanno da intermediari tra le pratiche e i pagamenti, ovvero il **payment dispatcher** e il **payment updater**. #### Core È l’interfaccia dalla quale l’utente usufruisce di un servizio digitale, inserendo i dati di una pratica attraverso un modulo: se il servizio prevede un pagamento, i dati di questo sono presenti nella descrizione JSON della pratica e saranno utilizzati dal dispatcher per creare il pagamento. #### Payment dispatcher È il microservizio che, a partire dall'evento di una pratica nel topic `applications`, crea l'evento del pagamento nel topic `payments`. #### Payment dispatcher API È il microservizio che sostituirà il Payment Dispatcher, esso, anziche leggere l'evento di una pratica dal topic applications, esporrà un API che, quando chiamata, crea l'evento del pagamento nel topic payments. Questo permette di avere una soluzione unica per gestire tutti i flussi di pagamento della piattaforma, quindi sia pagamenti creati a partire dalle pratiche, che i pagamenti importati tramite csv o API esterne. #### Payment updater Il microservizio legge gli eventi dal topic `payments` e contestualmente aggiorna lo stato della pratica cambiando lo stato da Payment pending a Inviata. ### Sottosistema dei pagamenti #### Payment proxy E' il microservizio che gestisce la comunicazione e l’aggiornamento della posizione debitoria con l'Intermediario di pagamento di riferimento. Esso gestisce inoltre il salvataggio delle configurazioni tramite le quali può interagire con l'intermediario di pagamento di riferimento. Queste configurazioni sono inserite dall'operatore mediante l'interfaccia del Core, il quale comunica con il payment proxy mediante delle apposite API che quest'ultimo serve. #### Ksql E' un microservizio che ascolta dal topic payments e crea un database interrogabile con SQL contenente tutti i pagamenti in stati non definitivi. #### Payments poller E' il microservizio che monitora lo stato dei pagamenti: periodicamente legge su KSQL l'elenco dei pagamenti aperti e invia per ognuno di questi una chiamata alla "update.url" specificata nel pagamento stesso: questa url è una url del proxy stesso che consente al proxy di interrogare l'Intermediario per avere lo stato aggiornato del pagamento. ```mermaid sequenceDiagram %% syntax help https://mermaid.js.org/syntax/sequenceDiagram.html autonumber participant u as User link c: Pagamenti @ https://docs.opencityitalia.it/installazione-e-manutenzione/integrazioni/pagamenti box transparent Opencity Italia participant c as App-Core participant p as Payment Proxy participant rm as Read Model end box lightcyan PagoPA participant i as Intermediario participant pa as PagoPA end u ->> +c: Hello c ->> p: dati di pagamento loop Every 3s c-->rm: polling end Note over c,p: Il core si mette in attesa
della creazione del pagamento %% con questa parte diventa forse poco leggibile, meglio separare gli errori? critical Creazione del pagamento p ->> i: creazione pagamento i ->> p: payment creation IUV option service config error p --> p: log error about service option wrong payment data p --> p: log error about payment end break when payment creation fails c ->> u: mostra errore end p ->> rm: payment Note right of p: event PaymentPending c ->> u: payment page ``` #### Checkout pagoPA API Questo microservizio si occupa di centralizzare il pagamento online dei dovuti in un'unica API, ovvero quella del checkout di pagoPA, in questo modo si astrae dall'intermediario con cui ci si deve integrare facilitando quindi lo sviluppo dell'integrazione e omogeneizzando l'esperienza di pagamento del cittadino, che diventa quindi indipendente dall'intermediario tramite qui andrà a pagare. ```mermaid sequenceDiagram participant U as User (frontend) participant Checkout as Checkout pagoPA API participant pagoPA U->>Checkout: Invia id dei pagamenti creati (/payment) alt Creazione link carrello riuscita Checkout-->>U: Restituisce link carrello pagoPA else Errore nella creazione del carrello Checkout-->>U: Mostra errore di creazione carrello end Note over U, pagoPA: L'utente viene reindirizzato alla pagina di pagoPA ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazione-con-intermediari-di-pagamento-pagopa/schema-di-funzionamento.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.