Il plugin NMI per Shopware 6 offre ai gestori di negozi online una soluzione sicura, affidabile e flessibile per elaborare i pagamenti tramite il gateway di pagamento NMI. Il plugin è pensato per diversi tipi di transazione e supporta sia carte di credito sia pagamenti ACH, così da soddisfare preferenze diverse dei clienti. Per i merchant in Italia va considerato che ACH è un circuito di pagamento statunitense: per la clientela italiana il canale principale resta la carta. Oltre all’elaborazione dei pagamenti, il plugin NMI consente l’autorizzazione completa degli ordini, permettendo di verificare e incassare i pagamenti in sicurezza. Supporta inoltre i rimborsi, parziali e totali, offrendo strumenti efficienti per gestire le transazioni dopo l’acquisto.
Il plugin permette inoltre ai clienti di salvare in modo sicuro i propri metodi di pagamento, per un checkout più rapido e comodo. Questo riduce gli attriti nel processo d’acquisto e aumenta il tasso di conversione. Grazie all’integrazione nel pannello di amministrazione di Shopware, i merchant possono gestire le transazioni, monitorare lo stato dei pagamenti e tenere registri dettagliati senza uscire dalla piattaforma. Unendo sicurezza, flessibilità e semplicità d’uso, il plugin NMI garantisce un’esperienza di pagamento fluida, affidabile ed efficiente per merchant e clienti.
Il plugin include anche opzioni di configurazione avanzate, tra cui la gestione delle chiavi API per gli ambienti live e sandbox, la firma dei webhook e la verifica 3D Secure per una maggiore sicurezza dei pagamenti.
1. Download
Git
git clone https://github.com/solution25com/nmi-payment-shopware-6-solution25.git
composer require solution25/nmi-payment
2. Installazione del plugin in Shopware 6
3. Attivazione del plugin
4. Verifica dell’installazione
1. Accesso alle impostazioni del plugin
2. Impostazioni generali
Configuri le seguenti impostazioni:
Una volta installato e configurato il plugin, le opzioni di pagamento NMI sono disponibili nello storefront.
1. Incasso con carta di credito
Con questa funzione i clienti possono completare le transazioni con carta di credito tramite il gateway di pagamento NMI. Prima di usarla, verifichi che la configurazione API per le transazioni live sia corretta.
Come funziona:
Passaggi:
2. Incasso ACH
L’incasso ACH (eCheck) permette ai clienti di pagare con i dati del proprio conto bancario e offre un’alternativa alle transazioni con carta di credito.
Come funziona:
Le transazioni ACH trasferiscono i fondi direttamente dal conto bancario del cliente.
Passaggi:
Selezioni “NMI ACH (eCheck)” come metodo di pagamento.
Clicchi su “Paga”.
Inserisca i dati del conto bancario richiesti.
Invii il pagamento.
3. Autorizzazione e incasso per carte di credito
Con questa funzione i pagamenti vengono autorizzati e incassati in due passaggi. Il pagamento viene prima autorizzato e i fondi vengono bloccati sul conto del cliente. L’amministratore può poi approvare o rifiutare l’addebito, completando o annullando la transazione.
Come funziona:
Lo stato del pagamento resta “Autorizzato” finché non viene approvato manualmente.
L’amministratore può scegliere Incassa (addebitare il cliente) oppure Annulla.
Passaggi:
Attivi la funzione “Autorizzazione e incasso” nelle impostazioni del plugin.
I nuovi ordini compaiono come “Autorizzato”.
Vada in Admin → Ordini e modifichi lo stato del pagamento in “Pagato” o “Annullato”.
4. COLI (annullamento di articoli in un ordine)
COLI consente agli amministratori di annullare singoli articoli di un ordine senza intervenire sull’intera transazione. Offre più flessibilità nella gestione dei resi.
Come funziona:
Clienti o amministratori possono scegliere quali prodotti annullare.
Gli articoli restanti possono comunque essere pagati.
Passaggi:
Selezioni il prodotto o i prodotti da annullare.
Clicchi su “Elimina” per rimuovere gli articoli.
Salvi l’ordine aggiornato.
Modifichi lo stato del pagamento da “Autorizzato” a “Pagato”.
La funzione COLI è pensata per funzionare esclusivamente con soluzioni iPaaS (Integration Platform as a Service) e piattaforme simili.
4. Rimborsi (totali e parziali)
Supporta rimborsi totali e parziali tramite NMI.
Come funziona:
I rimborsi totali restituiscono l’intero pagamento.
I rimborsi parziali restituiscono solo una parte dell’importo totale.
Procedura (rimborso totale):
1. Vada su Ordini → sezione Articoli.
2. Selezioni il prodotto o i prodotti da rimborsare.
3. Clicchi su Restituisci articolo.
4. Salvi l’ordine.
5. Clicchi su Crea rimborso.
6. Modifichi lo stato in “In lavorazione”.
Procedura (rimborso parziale):
1. Vada su Ordini → sezione Articoli.
2. Selezioni il prodotto o i prodotti da rimborsare.
3. Adegui l’importo del rimborso (totale o parziale).
4. Clicchi su Restituisci articolo.
5. Salvi l’ordine.
6. Clicchi su Crea rimborso.
7. Modifichi lo stato in “In lavorazione”.
Rimborso totale:
Rimborso parziale:
1. Apra l’ordine e selezioni il prodotto da restituire.
2. Indichi la quantità di articoli da rimborsare.
3. Restituisca gli articoli.
4. Salvi l’ordine.
5. Crei un rimborso parziale.
6. Aggiorni lo stato dell’ordine in “In lavorazione”.
5. Mixed Card
La funzione Mixed Card permette ai clienti di acquistare con un unico carrello sia prodotti normali sia prodotti in abbonamento. Riunisce acquisti standard e abbonamenti nella stessa transazione.
Come funziona:
Il sistema distingue tra acquisti singoli e pagamenti in abbonamento.
La stessa carta di credito può essere usata per entrambi i tipi di transazione.
Procedura:
1. Aggiunga al carrello prodotti normali e prodotti in abbonamento.
2. Vada al checkout.
3. Paghi con un’unica carta di credito.
6. Salvataggio della carta
Permette ai clienti di salvare in modo sicuro i dati della carta per le transazioni future.
Come funziona:
Viene creato un Vaulted ID per memorizzare le informazioni di pagamento del cliente.
Per le transazioni future i clienti possono scegliere il pagamento con un clic.
Procedura:
1. Selezioni i prodotti e vada al checkout.
2. Inserisca le informazioni di pagamento.
3. Spunti la casella “Salva la mia carta per i pagamenti futuri”.
4. La carta salvata comparirà come opzione di pagamento negli ordini successivi.
Gestione delle carte salvate:
Elimina carta: rimuove da NMI i dati della carta salvata.
Aggiungi carta: consente di aggiungere una nuova carta per le transazioni future.
Questo documento contiene informazioni dettagliate sugli endpoint API disponibili nel plugin NMI per Shopware 6. Questi endpoint permettono agli utenti autorizzati di avviare transazioni e di recuperarne i dettagli tramite parametri di interrogazione.
POST /api/transact.php
Avvia una transazione tramite parametri inviati con una richiesta POST. È il tipico endpoint di interazione con il gateway per elaborare i pagamenti tramite NMI.
Accept: application/json
security_key=6457Thfj624V5r7WUwc5v6a68Zsd6YEm
type=sale
ccnumber=4111111111111111
ccexp=1025
cvv=123
amount=1
response=1
responsetext=SUCCESS
authcode=123456
transactionid=10778056102
response_code=100
type=sale
cvvresponse=N
response=3
responsetext=Payment Token does not exist REFID:333061802
response_code=300
POST /api/query.php
Invia una richiesta di interrogazione al gateway NMI per recuperare i dettagli di una transazione. Utile per operazioni successive alla transazione, come la verifica dello stato del pagamento, il recupero di dati storici o la riconciliazione dei record.
Accept: application/json
Content-Type: application/json
{
"security_key": "6457Thfj624V5r7WUwc5v6a68Zsd6YEm",
"report_type": "transaction",
"transactionid": "10778056102"
}
{
"nm_response": {
"transaction": {
"transaction_id": "10778056102",
"transaction_type": "cc",
"condition": "complete",
"order_id": "1234567890",
"first_name": "John",
"last_name": "Smith",
"cc_number": "4xxxxxxxxxxx1111",
"cc_exp": "1025",
"amount": "1.00",
"response_text": "SUCCESS",
"response_code": "100"
}
}
}
{
"nm_response": {
"error_response": "Invalid security key provided. REFID:987654321"
}
}
1. Configurare correttamente le chiavi API
Imposti le chiavi API live e sandbox prima di elaborare transazioni.
Verifichi che chiave di firma e chiavi pubbliche siano corrette per garantire una comunicazione sicura.
2. Monitorare le transazioni
Controlli regolarmente in Admin → Ordini che i pagamenti vengano elaborati correttamente.
Usi “Authorize” e “Capture” per gestire l’approvazione del pagamento prima dell’incasso dei fondi.
3. Gestire i rimborsi con attenzione
Verifichi di aver selezionato il prodotto giusto per rimborsi totali o parziali.
Aggiorni lo stato dell’ordine in “In lavorazione” dopo aver elaborato il rimborso.
4. Usare la funzione Mixed Card
Permetta ai clienti di usare una sola carta di credito sia per prodotti normali sia per prodotti in abbonamento.
5. Salvare le carte in sicurezza
Attivi “Salva carta” per transazioni future più rapide.
Gestisca e aggiorni regolarmente le carte salvate.
6. Svuotare la cache dopo le modifiche
Svuoti sempre la cache di Shopware dopo aver salvato le impostazioni, così che gli aggiornamenti vengano applicati.
7. Testare in modalità sandbox
Usi le chiavi API sandbox per testare tutti i metodi di pagamento prima di andare live.
8. Restare aggiornati
Mantenga il plugin aggiornato per garantire compatibilità e sicurezza.
Nessuna opzione di pagamento con carta disponibile
I pagamenti ACH non vengono elaborati
“Authorize and Capture” non funziona
I rimborsi non vengono elaborati
Il salvataggio della carta non funziona
Le transazioni Mixed Card non funzionano
1. Come configuro le chiavi API?
Apra le impostazioni del plugin nel pannello admin di Shopware e inserisca le chiavi API live e sandbox, la chiave di firma e le chiavi pubbliche per transazioni sicure.
2. Posso usare ACH per i pagamenti?
Sì, può attivare NMI ACH (eCheck) come metodo di pagamento, così che i clienti paghino con i dati del proprio conto bancario. Tenga presente che ACH è un circuito statunitense: per i clienti in Italia è rilevante soprattutto il pagamento con carta.
3. Come funziona la funzione “Authorize and Capture”?
Il pagamento viene prima autorizzato e trattenuto. Gli amministratori possono approvare o rifiutare l’addebito prima che i fondi vengano incassati.
4. Posso annullare singoli articoli di un ordine?
Sì, con la funzione COLI (Cancel Order by Line Item) può annullare singole righe senza intervenire sull’intero ordine.
5. Posso salvare i dati delle carte dei clienti?
Sì, può attivare la funzione “Salva carta” per memorizzare in modo sicuro i dati di pagamento dei clienti per le transazioni future.
6. Come gestisco i rimborsi?
Rimborsi totali o parziali si gestiscono dalla sezione Ordini del pannello admin. Dopo l’elaborazione aggiorni lo stato in “In lavorazione”.
7. I clienti possono acquistare prodotti normali e in abbonamento con una sola carta?
Sì, la funzione Mixed Card consente di acquistare sia prodotti normali sia articoli in abbonamento con un’unica carta di credito.
8. È sicuro salvare i dati della carta?
Sì, i dati della carta vengono memorizzati in modo sicuro tramite un Vaulted ID, conforme PCI, che consente pagamenti futuri con un clic.
9. Come risolvo i problemi di pagamento?
Verifichi le credenziali API, si assicuri che il plugin sia attivo e controlli gli stati dei pagamenti nel pannello admin. Svuoti la cache se le impostazioni non vengono salvate. Se gestisce un negozio Shopware in Italia e desidera supporto per l’integrazione dei pagamenti, il team di solution25 è a disposizione.