Plugin eCommerce Numia - Piattaforma eCommerce per PrestaShop 1.7.X & 8.X.X & 9.x
Scopo del documento
Il presente documento descrive la procedura di installazione e utilizzo del plugin IGFS® opzione Buy Now per PrestaShop 1.7.X, 8.X e 9.X. Le eventuali figure presenti nel manuale originale sono puramente esemplificative.
A chi è rivolto
Il documento è rivolto agli utilizzatori della piattaforma PrestaShop 1.7.X, 8.X e 9.X.
Nota: il supporto a 9.x è riportato qui come estensione editoriale. Verificare sempre i requisiti minimi nella sezione Compatibilità prima della messa in produzione.
1. Introduzione
Il plugin IGFS® per PrestaShop consente la gestione di pagamenti elettronici con più metodi di pagamento, in modo semplice e sicuro. È completamente integrato nelle interfacce di PrestaShop 1.7.X e 8.X e comunica con il Payment Gateway IGFS® di Numia®.
Servizi offerti:
- Inserimento di più metodi di pagamento nel negozio
- Pagamento in modalità “Authorize” (due passi)
- Pagamento in modalità “Capture” (un passo)
- Cancellazione di ordini “Authorize” non conclusi
- Rimborsi parziali e totali degli ordini
Vantaggi principali
- Riduzione del time‑to‑cash grazie a “Capture”
- Maggiore controllo del rischio con “Authorize”
- Gestione nativa di refund parziali/totali
2. Carte e metodi di pagamento alternativi supportati
- Supporto ai principali circuiti di carte di credito internazionali
- Supporto ai metodi di pagamento alternativi abilitati dal gateway IGFS®
- Per l’elenco aggiornato, contattare il supporto Numia®
Nota: l’abilitazione dei metodi dipende dal contratto merchant e dalla configurazione PGW.
3. Prima installazione
Installazione dal back‑office di PrestaShop:
- Vai su Moduli → Gestione moduli.
- Clicca “Carica un modulo” e seleziona il file
.ZIPdel plugin fornito da Numia®. - Attendi il completamento e verifica la notifica di conferma.
Consiglio operativo
- Esegui un backup del database e della cartella
modules/prima di installare o aggiornare.- Testa sempre in ambiente di staging prima della produzione.
3.1 Compatibilità
| Componente | Versioni supportate |
|---|---|
| PHP | > 7.4 e <= 8.4.8 |
| PrestaShop | > 1.7.8 e <= 9.0.0 |
| Guzzle | ≥ 6 |
Se la libreria Guzzle non è disponibile, il plugin potrebbe non funzionare correttamente.
Importante: il plugin potrebbe non supportare versioni inferiori a quelle indicate.
4. Aggiornamento plugin
Procedura standard
- Dal menù moduli, seleziona “Disinstalla” per il plugin IGFS®.
- Installa la nuova versione (come in Prima Installazione).
Aggiornamento manuale (se quello automatico fallisce)
- Vai in
Prestashop/modules/ - Elimina la cartella
netsgroupigfspayment - Installa la nuova versione del plugin
- Disinstalla la versione appena installata
- Ri‑installa nuovamente la nuova versione
Attenzione
- Passando a una versione ≥ 3.0.0, disinstallare il plugin e eliminare la directory.
- I dati di configurazione dovranno essere reinseriti.
- La creazione dell’ordine avviene all’inizio della procedura (per ridurre errori), non al completamento. Vedi anche Stati dell’Ordine.
Checklist rapida
- Backup DB e file
- Verifica credenziali disponibili
- Ambiente di staging aggiornato
- Test dei principali metodi di pagamento
- Verifica refund e annullo
5. Configurazione
Accedi dalla lista moduli e premi “Configura” per aprire il pannello di configurazione.
Parametri di configurazione
| Parametro | Descrizione |
|---|---|
| Gateway URL | Indirizzo del Payment Gateway IGFS® per le transazioni. Fornito dal supporto Numia®. |
| ID Merchant | Identificativo dell’esercente. Fornito dal supporto Numia®. |
| Chiave firma | Chiave per la firma elettronica cifrata delle transazioni. Fornita dal supporto Numia®. |
| Azione di pagamento | - Autorizza e Cattura: autorizzazione e incasso contestuali.- Autorizza: due fasi; l’ordine parte in stato “in attesa”, la conferma è manuale dall’esercente. |
| Abilita stringa TxID personalizzata | Permette un prefisso (1–6 caratteri alfanumerici) per l’ID ordine, utile per multi‑store. Esempi: ST01, A123, XYZ. |
| Livello di Debug | Basso / Medio / Alto. Maggiore livello = più log generati nel sistema. |
Pulsanti
| Pulsante | Descrizione |
|---|---|
| Verifica credenziali | Testa la connettività verso il Gateway URL. |
| Scarica i log dal Database | Esporta un file .txt con i log del plugin, utile per l’assistenza. |
| Pulisci vecchi log | Elimina i log generati dal plugin da oltre 30 giorni. |
Suggerimento: mantieni il livello di debug su “Basso” in produzione per evitare file log eccessivamente grandi.
Dopo aver impostato i parametri, premi “Salva”.
5.1 Impostazioni metodi di pagamento
Dopo aver cliccato “Ottieni metodi di pagamento”, vengono caricati i metodi abilitati per il Merchant ID.
| Parametro | Descrizione |
|---|---|
| Abilita metodo | Abilita/disabilita il metodo per i clienti. |
| Pitype | Payment Instrument Type fornito da Numia®. |
| Nome visualizzato | Nome mostrato al cliente (preferibilmente univoco, con supporto traduzioni). |
| Visualizza descrizione | Abilita il campo Testo descrittivo. |
| Testo descrittivo | Descrizione del metodo quando il cliente lo seleziona. |
| Icona del metodo | - Non mostrare - Immagine personalizzata (URL) - [Estensione] altre opzioni |
| Immagine personalizzata | URL dell’immagine da visualizzare. |
Esempio di descrizione efficace “Paga con carta in pochi clic. Transazione sicura con 3‑D Secure ove richiesto.”
6. Checkout ordine
- Al checkout, l’utente viene reindirizzato al Payment Gateway IGFS® per completare il pagamento.
- Al termine o in caso di annullamento, viene riportato sul sito del Merchant e l’ordine viene finalizzato.
- In caso di errore (es. carta non valida), viene mostrato un messaggio di errore e il pagamento viene annullato.
Flusso sintetico
- Cliente seleziona metodo di pagamento
- Redirect a IGFS®
- Autorizzazione / Capture
- Redirect di ritorno al sito
- Stato ordine aggiornato automaticamente
7. Rimborso ordine
- Sono consentiti rimborsi parziali o totali per ordini autorizzati e conclusi con IGFS®.
- Non è possibile rimborsare ordini eseguiti con metodi diversi da IGFS®.
Procedura refund
- Seleziona l’ordine nella pagina “Ordini”.
- Se modalità “Authorize”:
- Cambia lo stato da “Authorized” a “Pagamento accettato”.
- Comparirà l’opzione “Rimborso Parziale”.
- Se modalità “Capture”:
- Il bottone “Rimborso parziale” è direttamente disponibile.
- Inserisci quantità e importo; il placeholder indica il massimo rimborsabile.
Nota PrestaShop
- Il refund totale/parziale dipende dal numero di articoli nell’ordine.
- Con un solo item, il refund è eseguibile una sola volta.
8. Annullo ordini effettuati in modalità Authorize
- L’annullamento è possibile solo per ordini in modalità “Authorize”.
- Cambia lo stato da “Pagamento accettato” ad “Annullato”.
- Un banner confermerà l’esito positivo dell’operazione.
Best practice Annota nel commento ordine il motivo dell’annullo per tracciatura interna.
9. Log del sistema
Dalla versione 3.1.0:
- È disponibile il pulsante “Scarica Log” nella pagina di configurazione del plugin, per esportare i log in
.txt(utile per l’assistenza).
Altre modalità di accesso ai log
- Dashboard → Configura → Parametri avanzati → Logs: elenco dei log di sistema (incluse le transazioni del plugin).
- Query SQL sul database PrestaShop.
Query di esempio per intervallo temporale
SELECT * FROM `ps_log` WHERE date_add BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD';
Esempio per Settembre 2023
SELECT * FROM `ps_log` WHERE date_add BETWEEN '2023-09-01' AND '2023-09-30';
Consiglio:
- Ruotare e archiviare i log periodicamente.
- Impostare avvisi su errori critici (HTTP 5xx, timeout, rifiuti ricorrenti).
10. Stati dell’ordine
Dalla versione ≥ 3.0.0, la gestione degli stati è aggiornata. Non modificare manualmente gli stati IGFS, salvo diversa indicazione.
| Stato | Quando si applica | Note |
|---|---|---|
| IGFS — Autorizzato | Pagamento concluso ma richiede autorizzazione | Non modificare manualmente |
| IGFS — Reso parziale | Eseguito un rimborso parziale | Non modificare manualmente |
| IGFS — Reso totale | Eseguito un rimborso totale | Non modificare manualmente |
| IGFS — Sospeso | Ordine in elaborazione dal modulo | Max ~20 minuti; oltre, controlla i log |
| IGFS — Declinato | Pagamento non accettato dal gateway | Non modificare manualmente |
| IGFS — Cancellato | Il cliente annulla il processo di pagamento | Non modificare manualmente |
| Annullato (PrestaShop) | Applicato dall’esercente | Con “Authorized”, avvia reversal |
| Pagamento accettato (PS) | Applicato dall’esercente | Con “Authorized”, conferma il pagamento |
Tip: è possibile rinominare gli stati dalla pagina Localizzazione → Stati degli ordini in PrestaShop.