Avviare un pagamento pagoPA da un servizio online: ora si può, a costo zero o quasi. Un’esperienza di vita vissuta e una realizzazione concreta

Negli ultimi due anni, nell’ambito del lavoro presso un ente locale (che poi è il Comune di Rivoli, nessun mistero), sono stato coinvolto nell’implementazione di due servizi online: un portale per il contribuente e un servizio di candidatura ai concorsi pubblici. In entrambi i casi è emersa un’esigenza: avviare un pagamento pagoPA senza uscire dal servizio. Nel primo caso il pagamento riguarda un tributo comunale che il contribuente autenticato al portale, dopo aver consultato la propria posizione, può decidere di avviare direttamente online. Nel secondo caso si tratta invece di pagare la tassa di partecipazione al concorso, senza uscire dalla procedura di candidatura e senza necessità d inviare o allegare ricevute di pagamento.

Prima

Un’esigenza più che ragionevole che, tuttavia, non era facilmente realizzabile. Infatti, all’epoca – semplificando – il pagamento pagoPA poteva essere tecnicamente avviato solo dal PSP (Prestatore di Servizi di Pagamento: la banca o la ricevitoria di turno) o dal Partner tecnologico dell’ente creditore. Insomma, per qualche motivo e banalizzando un po’, era possibile innescare un pagamento pagoPA solo se si era soggetti tecnologicamente noti o interni al mondo pagoPA. Infatti, sempre all’epoca, se qualcuno aveva in mano un avviso di pagamento pagoPA e voleva pagarlo online poteva, alternativamente, o avviare il pagamento dal sito o dalla app di un PSP (la propria banca, la propria app di pagamenti – Satispay per esempio, per capirci) o andare su una pagina dell’ente creditore (fornita dal partner tecnologico).

Nel 2020, raggiungere lo scopo di avviare il pagamento da un servizio online realizzato da un fornitore diverso dal partner tecnologico, richiedeva che il partner tecnologico (il soggetto che fornisce all’ente la porta di accesso al mondo pagoPA) mettesse a disposizione dell’altro fornitore una propria API (interfaccia di programmazione/dialogo col sistema dei pagamenti pagoPA), non standard ma proprietaria, con cui il servizio online potesse chiedere l’avvio del pagamento e ricevere in tempo reale la notizia dell’esito per non guastare la cosiddetta “esperienza utente” (o UX – user experience, per gli acronimisti anglofoni). Ciò si traduce in costi di sviluppo e tempi di attesa.

Adesso

Poi, nel 2021, PagoPA spa ha attivato il servizio Checkout (https://checkout.pagopa.it/). Di fatto, una pagina web dove una persona dotata di un avviso di pagamento può inserire codice avviso e codice fiscale dell’ente creditore e avviare un pagamento. Un passo avanti: il pagamento può essere avviato non solo da ente creditore e prestatore di servizi di pagamento, ma anche dal gestore della piattaforma pagoPA che poi fornisce un wizard per scegliere con quale PSP concludere il pagamento. In questo caso d’uso è il debitore che visita una pagina del sito di PagoPA spa e inserisce i dati. A questo punto mancherebbe poco: basterebbe che il Checkout di PagoPA spa si potesse invocare direttamente dal servizio online senza bisogno di immettere i dati dell’avviso. Alla fine, senza entrare in tecnicismi, basterebbe un link “parlante” verso il Checkout di PagoPA spa, che fosse in grado di precompilare le due caselle “codice avviso” e “codice fiscale dell’ente creditore” e cliccare sul tasto “paga”. Niente di tecnicamente complicato. In aggiunta servirebbe qualcosa che, fatto il pagamento, reindirizzasse alla pagina web del servizio online, magari con informazioni circa l’esito del pagamento stesso (“pagato” o “non pagato”).

Proprio per questo avevo avanzato la mia proposta su forum.italia.it: https://forum.italia.it/t/pagare-online-dal-sito-pagopa/27542/61. Nel post descrivo il contenuto dell’idea e il caso d’uso e interagisco con altri utenti interessati all’argomento.

A breve

Ora, non so se qualcuno mi ha ascoltato o se, più probabilmente, la mia proposta era una naturale conseguenza del cammino intrapreso. Fatto sta che adesso quanto avevo ipotizzato è realtà!

La versione attuale delle SANP (Specifiche Attuative del Nodo dei Pagamenti, attualmente alla versione 3.3.1), gestisce anche l’avvio del pagamento a partire da un servizio dell’ente creditore sfruttando il servizio Checkout già realizzato in precedenza da PagoPA spa. Le istruzioni sono qui. In definitiva si tratta di fare una chiamata HTTP di tipo POST con alcuni dati nel payload JSON della richiesta: codice avviso, codice fiscale dell’ente creditore, importo, nome dell’ente creditore, causale del pagamento, indirizzi web a cui far tornare il pagante in caso di pagamento eseguito con successo (OK), pagamento annullato dall’utente oppure pagamento non concluso per qualche errore (KO).

Questo vuol dire che l’avvio del pagamento pagoPA online e la gestione del suo esito in tempo reale è diventata un’operazione standard, con regole uguali per tutti, indipendente dal partner tecnologico o da altre situazioni del contesto informatico dell’ente. Una volta creato il pagamento in attesa, questo sì con dei metodi che variano in base al partner tecnologico ^[1]In realtà le SANP 3.3.1 prevedono anche la possibilità di creare pagamenti spontanei secondo una procedura standard: l’ente tramite il partner tecnologico, espone un catalogo di servizi per i … Continue reading.

Il bello è che questa interazione con il Checkout è di una semplicità di implementazione sbalorditiva. Se scorri sotto puoi rendertene conto, visto che sono (quasi) riuscito a realizzarla anche in questo articolo. Sì, si potrebbe avviare un pagamento pagoPA anche tramite larchivistagitale.it!

Funziona davvero? Scorri in basso per scoprirlo…

SIMULAZIONE DI SERVIZIO ONLINE – Paga con il Checkout di PagoPA spa

Diciamo che il servizio online ha dialogato con il partner tecnologico(PT) pagoPA dell’ente e ha creato un avviso pagoPA pronto al pagamento e te lo ha mostrato per conferma. Fin qui il servizio online ha usato le API proprietarie messe a disposizione dal PT (ogni PT espone le sue).
Adesso, tramite le semplici API esposte dal servizio Checkout di PagoPA spa, è in grado di proporti di pagarlo direttamente online, senza necessità di ulteriori interazioni con il PT e con un metodo standard che va bene per ogni ente.

Prova a premere il bottone “Paga adesso online”: dovresti essere trasportato nel mondo di PagoPA spa per avviare il pagamento. Se poi abbandoni il pagamento dovresti tornare su questa pagina. Sempre che tu voglia inserire un numero di carta di credito per proseguire e poi abbandonare all’ultimo: io personalmente non lo farei 🙂

Comunque, già il fatto che compaia l’indirizzo e-mail impostato nel codice è un buon segno che la comunicazione sta funzionando e ci possiamo fidare che, al netto di eventuali aggiustamenti, tutto funzioni come si deve.

AGGIORNAMENTO: a settembre 2023 PagoPA spa ha attivato il servizio. In fondo al post un esperimento per avviare da questa pagina un qualsiasi pagamento pagoPA “vero”…

Prima di confermare l’e-mail è possibile vedere il riepilogo del pagamento cliccando sull’importo con l’icona “i” in alto a destra.

Cosa c’è sotto

Il flusso di pagamento tramite Checkout è descritto qui: https://docs.pagopa.it/sanp/casi-duso/pagamento-spontaneo-presso-psp.

Le specifiche dell’API da utilizzare sono qui: https://docs.pagopa.it/sanp/appendici/primitive#carts.

In sintesi, tramite la chiamata (request) all’API esposta dal Checkout si passano al servizio gli stessi dati (o poco più) di quelli che si inserirebbero a mano nell’interfaccia web e i tre URL (indirizzi web) a cui rispedire il pagante in base all’esito del pagamento. Il checkout risponde reindirizzando la chiamata verso l’URL (indirizzo) di una pagina web creata ad hoc che consente di avviare il pagamento e gestire il ritorno al servizio online in base al suo esito (tecnicamente, si tratta di una response di redirect con status code 302).

Insieme alle istruzioni PagoPA spa propone anche un esempio di chiamata che con poche operazioni, è possibile inglobare nello script JavaScript utilizzato poco sopra per il bottone “Paga adesso online”. Ecco lo script, dove i dati del pagamento da avviare sono quelli di test indicati da PagoPA spa, mentre gli URL su cui reindirizzare il debitore in base all’esito del pagamento rimandano a questo articolo:

<script type="text/javascript"> 
function invocaCheckout() {
fetch("https://api.uat.platform.pagopa.it/checkout/ec/v1/carts", {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
  "emailNotice": "TESTlarchivistadigitale@mail.it",
  "paymentNotices": [
    {
    "noticeNumber": "301000000002984939",
      "fiscalCode": "02336340159",
      "amount": 5000,
      "companyName": "P.A. di prova",
      "description": "Pagamento di Test LAD"
    }
   ],
  "returnUrls": {
    "returnOkUrl": "https://www.larchivistadigitale.it/2023/03/05/avviare-un-pagamento-pagopa-da-un-servizio-online-ora-si-puo-a-costo-zero-o-quasi-unesperienza-di-vita-vissuta-e-una-realizzazione-concreta/",
    "returnCancelUrl": "https://www.larchivistadigitale.it/2023/03/05/avviare-un-pagamento-pagopa-da-un-servizio-online-ora-si-puo-a-costo-zero-o-quasi-unesperienza-di-vita-vissuta-e-una-realizzazione-concreta/",
    "returnErrorUrl": "https://www.larchivistadigitale.it/2023/03/05/avviare-un-pagamento-pagopa-da-un-servizio-online-ora-si-puo-a-costo-zero-o-quasi-unesperienza-di-vita-vissuta-e-una-realizzazione-concreta/"
  }
})
})
   .then(response => open(response.url));

}
</script>

Se si è pratici di Python e si vuole fare qualche ulteriore esperimento, si può utilizzare uno script con l’immancabile modulo requests (python -m pip install requests):

import requests

numavv= "301000000002984939"
fiscalCode = "02336340159"
email = "TESTlarchivistadigitale@mail.it"
amount = 5000

url = "https://api.uat.platform.pagopa.it/checkout/ec/v1/carts"

headers = {"Content-Type":"application/json", "Connection":"keep-alive"}

body  = {
  "emailNotice": email,
  "paymentNotices": [
    {
    "noticeNumber": numavv,
      "fiscalCode": fiscalCode,
      "amount": amount,
      "companyName": "P.A. di prova",
      "description": "Pagamento di Test LAD"
    }
   ],
  "returnUrls": {
    "returnOkUrl": "https://www.larchivistadigitale.it/2023/03/05/avviare-un-pagamento-pagopa-da-un-servizio-online-ora-si-puo-a-costo-zero-o-quasi-unesperienza-di-vita-vissuta-e-una-realizzazione-concreta/",
    "returnCancelUrl": "https://www.larchivistadigitale.it/2023/03/05/avviare-un-pagamento-pagopa-da-un-servizio-online-ora-si-puo-a-costo-zero-o-quasi-unesperienza-di-vita-vissuta-e-una-realizzazione-concreta/",
    "returnErrorUrl": "https://www.larchivistadigitale.it/2023/03/05/avviare-un-pagamento-pagopa-da-un-servizio-online-ora-si-puo-a-costo-zero-o-quasi-unesperienza-di-vita-vissuta-e-una-realizzazione-concreta/"
  }
}


r = requests.post(url, headers = headers, timeout = 100, json = body, allow_redirects = False)
#se non disabilito il follow dei redirect ottengo come response direttamente la pagina bersaglio del reindirizzamento

Lo script non fa tutto il lavoro ma consente di ispezionare la response dell’API del Checkout:

>>> r.status_code
302
>>> r.is_redirect
True

L’URL da chiamare per avviare il pagamento è contenuto nell’header della response:

>>> r.headers
{'Date': 'Tue, 07 Mar 2023 12:45:12 GMT', 'Content-Length': '0', 'Connection': 'keep-alive', 'Location': 'https://api.uat.platform.pagopa.it/ecommerce/checkout/v1/carts/f1dcde8f-7da7-493d-8fba-68da15aaed14/redirect', 'Request-Context': 'appId=cid-v1:58b37248-3089-47ba-aa07-a2844fabe46a', 'Strict-Transport-Security': 'max-age=15724800; includeSubDomains'}

L’URL restituito, se visitato in tempo utile, consente effettivamente di avviare il pagamento.

Conclusione

Se tutto è come sembra questo è un notevole passo avanti. Infatti, allo stato attuale – già detto, ma ripetiamolo – per raggiungere questo risultato occorre sviluppare connettori fra ogni servizio online e il partner tecnologico, con duplicazioni di interfacce da mantenere e sforzi implementativi da… pagare!

Avviare un pagamento online e gestire il ritorno dell’utente sul servizio online che ha generato l’esigenza di pagamento non è alchimia, io l’ho fatto da zero in una domenica di marzo. Quindi, un fornitore non può pretendere chissà cosa. Anzi, l’integrazione con il Checkout di PagoPA spa dovrebbe essere di serie in ogni servizio online, non un optional a pagamento.

Insomma, un bell’esempio di come un intervento non eclatante e che da solo non fa prima pagina è invece in grado di risolvere un bel po’ di grattacapi a chi è impegnato sul campo in progetti di trasformazione digitale!

Ringraziamenti

Ringrazio il gruppo di supporto di pagoPA che mi ha fornito assistenza sul canale GitHub dedicato alle API di pagoPA. In particolare per le risposte fornite in una issue aperta parallelamente agli esperimenti qui raccontati: https://github.com/pagopa/pagopa-api/issues/893

Aggiornamento (27 novembre 2023)

Il servizio di invocazione del Checkout via API è adesso attivo in produzione (https://github.com/pagopa/pagopa-api/issues/901#issuecomment-1810418203).

L’URL per la chiamata “vera” è: https://api.platform.pagopa.it/checkout/ec/v1/carts

Qui sotto l’aggiornamento dello script javascript di sopra, che vi consente di avviare un pagamento vero anche dalle pagine di larchivistadigitale.it.

Provate pure con un avviso pagoPA reale.

Poiché le prima informazioni sull’avviso le fornisce lo script stesso, nome dell’ente e causale del pagamento sono fittizi. L’importo reale si vede dopo aver inserito i dati della carta (ho provato, se si annulla il pagamento si torna su questa pagina senza diventare più poveri).

Mi sono accorto che:

• se non si inserisce l’importo esatto si ottiene un errore e non c’è ritorno alla pagina del servizio;
• nome dell’ente creditore e descrizione dell’oggetto del pagamento non si aggiornano.

Indago 🙂

Aggiornamento post indagine (1 dicembre 2023): https://github.com/pagopa/pagopa-api/issues/925#issuecomment-1835722889 – pare che ci fosse un’anomalia che sarà sistemata nella prossima settimana.

larchivistadigitale.it è lieto di aver contribuito alla causa 🙂

Foto di Free stock photos from www.rupixen.com da Pixabay