PagoPa Gateway è un plugin per WooCommerce che permette di integrare in un e-commerce un metodo di pagamento basato sul portale dei pagamenti di Cineca chiamato PagoAtenei.
Il plugin può essere usato su siti realizzati con WordPress e WooCommerce e presuppone che l'Ente abbia attivato il servizio PagoAtenei di Cineca.
PagoPa Gateway permette ai clienti di un e-commerce di pagare con PagoPA sia online, usando una carta di credito, sia offline, stampando l'avviso di pagamento e pagandolo in una ricevitoria.
Il progetto è nato dalla necessità di permettere ai clienti del sito "Edizioni" (edizioni.sns.it) di pagare gli ordini con PagoPA.
Il plugin è in produzione sull'ec-commerce della Scuola.
- Pagamento degli ordini con PagoPA.
- Pannello per configurare la connessione al gateway Cineca e altri parametri di funzionamento del plugin.
- Configurazioni distinte per l'ambiente di test e l'ambiente di produzione.
- Gestione del workflow di pagamento.
- Procedura schedulabile per gestire e aggiornare gli ordini pagati offline.
- Gestione della notifica asincrona dei pagamenti da parte di PagoAtenei (messaggio paNotificaTransazione).
- Gestione della conferma sincrona dei pagamenti.
- Internazionalizzazione di etichetti e messaggi (italiano e inglese).
- Maschera per il controllo delle transazioni nel backoffice di Wordpress.
- Docker per testare il plugin velocemente.
- Concordare con Cineca l'attivazione del servizio PagoAtenei e degli ambienti di test e di produzione. I dati forniti da Cineca sono:
- Una username per utilizzare l'Api Soap.
- Una password per utilizzare l'Api Soap.
- Il WSDL del servizio.
- Un certificato SSL con la relativa password.
- Attivare sul portale dei pagamenti (sia in ambiente di test che di produzione) un Motivo e un Modello da associare ai pagamenti dell'e-commerce. Il codice del Modello è uno dei parametri di confgurazione del plugin.
- Assicurarsi che i requisiti software siano soddisfatti dal proprio sistema (vedere il paragrafo "Requisiti software" di questo documento).
- Scaricare, installare e configurare il plugin come descritto nel paragrafo "Installazione e configurazione" di questo documento.
- Il CMS Wordpress (versione >= 5.6.6).
- Il plugin Woocommerce (versione >= 5.0.0) per Wordpress .
- Un web server Apache (o equivalente) con le estensioni mod_ssl e soap installate e abilitate.
- Leggere la sezione "Campi personalizzati".
Il plugin usa i seguenti campi per compilare la richiesta inviata a PagoAtenei per la creazione di un pagamento:
- _billing_ita_cf: Il Codice Fiscale per le persone fisiche.
- _billing_vat : La Partita Iva per le aziende.
Edizioni usa un altro plugin personalizzato che aggiunge questi meta tag all'ordine, ma purtroppo quel plugin non può essere pubblicato in riuso. Se questi campi non sono specificati il plugin funziona lo stesso, ma un cliente verrà considerato come una persona fisica con Codice Fiscale = Nome + Cognome.
- Scaricare l'ultima versione stabile del plugin.
- Scompattare il contenuto dell'archivio nella cartella wp-content/plugins.
- Attivare il plugin dall'interfaccia di amministrazione di Wordpress.
- Configurare il plugin dall'interfaccia di amministrazione di Wordpress (W->WooCommerce->Impostazioni->Pagamenti->PagoPA Gateway->Gestisci):
- Abilita/Disabilita: Flag per abilitare o disabilitare il plugin.
- Titolo: Il nome del metodo di pagamento che è mostrato nella pagina di checkout d un ordine.
- Descrizione in inglese: Una descrizione in inglese del metodo di pagamento. E' visibile nella versione inglese della pagina di checkout di un ordine.
- Descrizione: Una descrizione in italiano del metodo di pagamento. E' visibile nella versione italiana della pagina di checkout di un ordine.
- Abilita la modalità di test: Flag per abilitare o disabilitare la modalità di test e la connessione all'ambiente di test di Cineca.
- Metodi di conferma del pagamento:
-
- Polling su PagoAtenei: L'ordine è considerato valido se la callback del plugin è invocata da PagoAtenei con un token valido e se esiste un ordine in attesa di pagamento con quel numero d'ordine e quello Iuv. Può essere attivato un controllo ulteriore sullo stato del pagamento abilitando il flag "Conferma di pagamento".
-
- Notifica asincrona di PagoAtenei: L'ordine è considerato pagato solo se PagaoAtenei invia un messaggio paNotificaTransazione con esito=PAGAMENTO_ESEGUITO.
- Conferma di pagamento: Se impostato, la callback invocata da PagoAtenei dopo un pagamento resta in attesa che la notifica di pagamento sia propagata dal PSP a PagoAtenei. Questa verifica è effettuata con un polling su PagoAtenei (gpChiedistatoVersamento), se non impostato, il plugin considera l'ordine pagato senza ulteriori controlli.
- Codice applicazione: Il codice applicazione fornito da Cineca.
- Codice di dominio: La Partita Iva dell'Ente.
- Iban: L'Iban dell'Ente.
- Tipo contabilità: Tipo di contabilità come definita dalla tassonomia di PagoPA consultabile qui.
- Validità del pagamento: Numero di ore in cui il pagamento è valido. E' possibile infatti effettuare il pagamento anche in una ricevitoria usando lo Iuv.
- Nome del file del certificato: Il nome del certificato pem fornito da Cineca. Se il certificato fornito fosse nel formato pk12 allora dovrebbe essere convertito nel formato pem.
- Password del certificato: La password del certificato fornita da Cineca.
- Prefisso dell'ordine: Un prefisso aggiunto al numero d'ordine di WooCommerce rpima che sia inviato al gateway di pagamento. E' utile per distinguere gli ordini di più istanze dello stesso sito, specialmente in fase di test. Può essere vuoto.
- Chiave di crittografia: La chiave usata per criptare il token inviato al gateway.
- Token dell'API del plugin: Il token usato per autenticare l'invocazione delle azioni schedulate e la REST API del plugin. Se vuoto la funzionalità è disabilitata.
Credenziali di produzione
- Indirizzo base del front end Cineca: L'url del front-end di PagoAtenei. E' fornito da Cineca.
- Url di PagoAtenei: L'indirizzo base dei web services Soap di PagoAtenei. E' fornito da Cineca.
- PagoAtenei API username: Lo username da usare per invocare i web services di PagoAtenei. E' fornito da Cineca.
- Password di Pagoatenei: La password da usare per invocare i web services di PagoAtenei. E' fornita da Cineca.
- Username dell'API del plugin: Lo username dell'account che PagoAtenei deve utilizzare per invocare l'entry-point *paNotificaTransazioneé. Deve essere comunicato a Cineca.
- Password dell'API del plugin: La password dell'account che PagoAtenei deve utilizzare per invocare l'entry-point paNotificaTransazione. Deve essere comunicata a Cineca.
- ID del modello di pagamento: L'ID del Modello di pagamento definito nel backoffice di PagoAtenei relativo agli ordini dell'e-commerce.
Credenziali di test
- Indirizzo base del front end Cineca: L'url del front-end di PagoAtenei. E' fornito da Cineca.
- Url di PagoAtenei: L'indirizzo base dei web services Soap di PagoAtenei. E' fornito da Cineca.
- PagoAtenei API username: Lo username da usare per invocare i web services di PagoAtenei. E' fornito da Cineca.
- Password di Pagoatenei: La password da usare per invocare i web services di PagoAtenei. E' fornita da Cineca.
- Username dell'API del plugin: Lo username dell'account che PagoAtenei deve utilizzare per invocare l'entry-point *paNotificaTransazioneé. Deve essere comunicato a Cineca.
- Password dell'API del plugin: La password dell'account che PagoAtenei deve utilizzare per invocare l'entry-point paNotificaTransazione. Deve essere comunicata a Cineca.
- ID del modello di pagamento: L'ID del Modello di pagamento definito nel backoffice di PagoAtenei relativo agli ordini dell'e-commerce.
- Metodo di conferma del pagamento = *Notifica asincrona di PagoAtenei e Payment confirmation = falso: L'ordine è considerato pagato solo quando PagoAtenei invoca l'entry-point paNotificaTransazione. Il sito deve essere ospitato sun un server pubblico e bisogna chiedere a Cineca di attivare e configurare il messaggio paNotificaTransazione. Non è possibile provare questa configurazione in un ambiente di sviluppo locale.
- Metodo di conferma del pagamento = Polling su PagoAtenei e Conferma del pagamento = falso: L'ordine è considerato pagato solo se la callback è invocata correttamente da PagoAtenei e l'ordine è nello stato corretto. Non sono effettuati controlli aggiuntivi.
- Metodo di conferma del pagamento = Polling su PagoAtenei e Conferma del pagamento = vero: La callback, dopo aver controllato il token e lo stato dell'ordine, interroga in polling PagoAtenei fino a quando PagoAtenei non riceve la notifica del pagamento dal PSP.
La prima di quelle elencate è la configurazione consigliata e quella più sicura.
Le immagini seguenti spiegano graficamente il flusso e il funzionamento del sistema:
Dopo aver richiesto ed aver ottenuto i parametri di connessione da Cineca, è possibile usare il programma SoapUI per provare i web services. Nella cartella setup\TestSoap si trova un progetto che può essere importato e usato in SoapUI. In alternativa è possibile creare un nuovo progetto utlizzando il seguente file WSDL. Nella cartella setup\TestApiSoapWithPhp ci sono due script PHP (testCaricaVersamento.php e testChiediStatoVersamento.php) per verificare il collegamento con le Api di PagoAtenei.
Il plugin espone i seguenti entry-point:
-
HOOK_PAYMENT_COMPLETE --> pagopa_payment_complete: è la callback invocata da PagoAtenei quando un oordine è pagato o cancellato.
-
HOOK_SCHEDULED_ACTIONS --> pagopa_execute_actions: è l'entry-point che può essere invocato da un cronjob per gestire gli ordini pagati offline.
-
HOOK_TRANSACTION_NOTIFICATION --> pagopa_notifica_transazione: è l'entry-point invocato da PagoAtenei per notificare il pagamento di un ordine.
Image 1: Backoffice: abilitazione del plugin.
Image 2: Backoffice: configurazione del plugin.
Image 3: Backoffice: controllo delle transazioni.
- I documenti e gli schemi di funzionamento del plugin si trovano nella la cartella doc di questo plugin.
- Il progetto e gli esempi per provare l'Api Soap con SoapUI si trovano nella cartella *setup/TestSoap.
- Per la documentazione e le specifiche sull'API Soap visitare il sito di Cineca:
E' possibile provare il plugin usando un container Docker che contiene tutte le componenti software richieste (Wordpress + WooCommerce + wp-pagopa-gateway-cineca). Il Dockerfile da usare è: Dockerfile.
I comandi da eseguire per creare ed eseguire il container sono:
- docker build -t myshop-img -f Dockerfile .
- docker run -p 80:80 -p 3306:3306 --name=myshop -d myshop-img
Per collegarsi alla shell del container, eseguire il comando:
- docker exec -it myshop /bin/bash
L'url dell'e-commerce appena creato è: http://localhost/myshop/ .
Per provare il plugin è necessario abilitarlo e configurarlo con i dati fornitin da Cineca.
Per autenticarsi come amministratore del sito l'url è http://localhost/wp-admin/ e l'account è: manager / password
Sul container è installato il tool Adminer per gestire le tabelle del databse. L'url di Adminer è: http://localhost/adminer.php Per configurarlo i parametri sono:
- System: Mysql
- Server: 127.0.0.1
- Utente: admin
- Password: admin
- Database: myshop
A partire da WooCommerce 8.3, per le nuove installazioni i blocchi Carrello e Checkout sono presenti di default. Per questo è stato aggiunto un blocco (definito in class-block.php) per la pagina di checkout. Leggere questa pagina per maggiori informazioni.
Il progetto è pubblicato sul catalogo del riuso di Developers Italia. La home page del progetto è questa.
Questo è il repository che contiene il codice sorgente del progetto.
Il progetto è pubblicato sotto la licenza GPL-3.0-only come descritto nel file LICENSE.
Il plugin è disponibile in italiano e in inglese. Questa è la guida in inglese.
Lo scopo principale di questo repository è quello di far evolvere il plugin. Vorremmo rendere il processo per contribuire al progetto il più semplice e trasparente possibile, per questo saremo grati alla comunità di coloro che vorranno contribuire alla soluzione di bug, al miglioramento del codice e all'aggiunta di nuove funzionalità.
- Detentore copyright: Scuola Normale Superiore
- Responsabili del progetto: Michele Fiaschi, Claudio Battaglino, Alida Isolani, Marcella Monreale