Plugin eCommerce Numia - Piattaforma eCommerce per WordPress e WooCommerce
Scopo del documento
Il presente documento descrive la procedura di installazione e utilizzo del PLUGIN eCommerce Numia per la piattaforma WordPress tramite il plugin WooCommerce.
Le eventuali figure utilizzate nel presente manuale sono solo a titolo di esempio.
A chi è rivolto
Il documento è rivolto agli utilizzatori della piattaforma WordPress e WooCommerce.
1. Introduzione
Il plugin eCommerce (di seguito indicato anche solo con il termine plugin) è una soluzione di pagamento che permette agli esercenti di gestire i pagamenti elettronici con carte di credito in maniera semplice e sicura.
Il plugin ha un unico modulo di configurazione ed è completamente integrato nelle interfacce della piattaforma WordPress e WooCommerce, che ne gestiscono la configurazione.
La versione plugin 3 è validata per versioni uguali o superiori a:
- WordPress 5.9.X
- WooCommerce 6.9.X
Le transazioni avvengono in maniera sicura attraverso la Piattaforma eCommerce Numia.
Il plugin offre i seguenti servizi:
- Inserimento di più metodi di pagamento all’interno del negozio
- Pagamento con carta in modalità Autorizza (Authorize)
- Pagamento in modalità Acquisisci (Capture)
- Annulli (Delete) di ordini effettuati con modalità “Autorizza” non conclusi
- Rimborsi (Refund) parziali e totali degli ordini
2. Carte e metodi di pagamento alternativi supportati
È possibile utilizzare, nei pagamenti elettronici, le carte di credito dei circuiti più diffusi a livello internazionale.
Sono utilizzabili, inoltre, i principali metodi di pagamento alternativi supportati dal Payment Gateway.
Per approfondimenti su carte di credito e pagamenti alternativi supportati, rivolgersi al supporto tecnico.
3. Compatibilità
Versioni di sviluppo e test:
- PHP > 7.4 e <= 8.3
- WordPress >= 5.9.3
- WooCommerce >= 6.9.4
Il plugin richiede la libreria Guzzle in versione superiore alla 6. Qualora il sistema non consenta l’uso di questa libreria, il plugin potrebbe non funzionare correttamente. In tal caso inviare un ticket di supporto agli sviluppatori del plugin per ulteriori informazioni.
4. Installazione
La versione plugin 3.0 per la piattaforma WordPress necessita dell’installazione del plugin WooCommerce. Se WooCommerce non è presente, procedere all’installazione/configurazione seguendo le istruzioni del paragrafo seguente.
4.1 Installazione WooCommerce
- Aprire la dashboard di amministrazione (pannello di controllo) del proprio negozio online.
- Dal menu verticale a sinistra, selezionare “Plugin”.
- Nel sottomenu, selezionare “Aggiungi plugin”.
- Cercare “WooCommerce”, selezionarlo ed eseguire l’installazione.
- Configurare WooCommerce secondo le proprie esigenze.
4.2 Installazione Plugin
- Caricare il file
.zipdel plugin in locale sul proprio sistema (PC o supporto di memoria). - Nella dashboard WordPress, andare su “Plugins > Aggiungi plugin”.
- Cliccare sul pulsante “Carica plugin” e caricare il file
.zip. - Avviare l’installazione.
- Al termine dell’installazione verrà visualizzata una finestra di conferma.
Contattare il supporto tecnico qualora l’installazione non andasse a buon fine.
5. Aggiornamento Plugin
Per l’aggiornamento del plugin, procedere nei seguenti passi:
- Disattivare il plugin esistente dal menu “Plugin installati”.
- Eliminare il plugin (la voce appare dopo la disattivazione).
- Installare il nuovo plugin.
Attenzione: Nel caso si passi da una versione superiore o uguale alla 3.0.0, è necessario disinstallare il plugin. I dati di configurazione dovranno essere inseriti nuovamente. La creazione dell’ordine viene generata all’inizio della procedura, non al completamento (per limitare errori di creazione ordine). Vedi anche la sezione “Gestione Stati Ordine”.
6. Configurazione Plugin
Per accedere al pannello di configurazione del plugin:
- Dal menu della dashboard del sito WordPress, selezionare “Plugin”.
- Cliccare su “Plugin installati”.
- Cliccare su “Impostazioni” accanto al plugin Numia per aprire il pannello di configurazione.
Figura 1 – Configurazione
Tramite la voce “Impostazioni” si accede al menu di configurazione del plugin. Parametri da configurare:
| Campo | Descrizione |
|---|---|
| IGFS Gateway URL | Indirizzo del Payment Gateway utilizzato dal plugin per le transazioni. Fornito dal supporto tecnico. |
| ID Merchant | Identificativo dell’esercente. Fornito dal supporto tecnico. |
| Chiave firma | Chiave di sicurezza per la firma elettronica cifrata delle transazioni. Fornito dal supporto tecnico. |
| Azione di pagamento | Scelta tra:Authorize: il pagamento è autorizzato e poi confermato dall’esercente (contabilizzazione differita).Capture: il pagamento è autorizzato e concluso in un solo step (contabilizzazione immediata). |
| Abilita la stringa TxID personalizzata | Permette di inserire un prefisso (da 1 a 6 caratteri alfanumerici) all’ID ordine (TxID). Utile per multi‑store. |
| Livello di Debug | Livello di verbosità dei log (intermedio, alto). Più alto = più messaggi di log. |
| Scaricare i log IGFS | Pulsante per scaricare un file .txt con tutti i log del plugin. Consigliato inviare al supporto in caso di problemi. |
| Verifica connessione (pulsante) | Verifica il corretto collegamento al gateway URL. |
6.1 Impostazioni Metodi di Pagamento
Sezione relativa alla configurazione dei metodi di pagamento:
| Campo | Descrizione |
|---|---|
| Configurazione API Type | Codice API specifico fornito per il metodo di pagamento. Determina il behavior del pagamento e funzionalità disponibili. |
| Abilita metodo | Abilita il metodo di pagamento per il cliente (in coerenza con la configurazione contrattuale). |
| Nome visualizzato | Nome del metodo che appare al cliente nel checkout. |
| Abilita descrizione | Abilita la visualizzazione del campo Descrizione visualizzata. |
| Descrizione visualizzata | Testo descrittivo del metodo, visibile quando il cliente lo seleziona. |
| Opzioni immagini | Non mostrare: nessuna immagine.Immagine personalizzata: consente di inserire una URL. |
| URL dell’immagine personalizzata visualizzata | URL dell’immagine personalizzata. Verificare dimensioni e rendering in front‑end. |
Una volta configurati i parametri, premere “Salva” per confermare.
7. Creazione e pagamento ordine
Al momento del checkout, il cliente viene reindirizzato al Payment Gateway, dove inserisce i dati di pagamento. Al termine del pagamento o in caso di cancellazione, viene riportato sul sito del merchant e l’ordine viene finalizzato.
Se si verificano problemi con il pagamento (es. carta non valida), comparirà un avviso di errore e il pagamento sarà annullato.
8. Rimborso ordine
È possibile effettuare Rimborsi (Refund) parziali o totali degli ordini il cui pagamento è stato autorizzato esclusivamente tramite il plugin IGFS®.
Non è possibile effettuare refund di ordini effettuati con altri metodi di pagamento diversi da IGFS®.
Procedura rimborso
- Dal menu WordPress, selezionare “WooCommerce > Ordini”.
- Aprire la pagina di dettaglio dell’ordine autorizzato.
- Cliccare su “Rimborsa via Metodo di Pagamento”.
Nota: le operazioni di rimborso sono irreversibili.
9. Annullo ordine: modalità Authorize
È possibile annullare l’ordine effettuato con il plugin solo in modalità “Authorize”.
Procedura annullamento
- Cambiare lo stato dell’ordine da “In sospeso” a “Annullato”.
- Premere il bottone “Aggiorna” per confermare.
10. Visualizzazione log del plugin
Dalla versione 3.1.0 è disponibile la funzionalità “Scarica Log” direttamente dalla pagina di configurazione del plugin.
Questa opzione consente di scaricare un file contenente informazioni dettagliate utili per la diagnosi e la risoluzione di problemi. In caso di necessità, inviare il log al supporto tecnico.
I log del plugin sono disponibili anche tramite:
- WooCommerce > Stato > Log
Figura 2 – Log di Sistema
È possibile selezionare, tramite il menù a tendina, il file di log relativo alla data desiderata. La data è inclusa nel nome del file.
Figura 3 – Selezione data
11. Gestione pagamenti NON notificati
Durante il pagamento, l’utente potrebbe chiudere il browser prima di tornare su WordPress. In questo caso il plugin non riceve la notifica dell’esito di pagamento.
Per gestire questo scenario, è stato implementato un meccanismo server‑to‑server che garantisce la corretta notifica di tutti gli esiti.
Figura 4 – Diagramma pagamenti non notificati
12. Gestione stati ordine
La gestione degli stati dell’ordine rispetta la logica standard di WooCommerce (riferimento: https://woocommerce.com/document/managing-orders/).
Di seguito il diagramma degli stati ordine:
Figura 5 – Stati Ordine