VibeFox Netopia for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo.
PHP: 8.0 o successivo con le estensioni OpenSSL e DOM.
Valuta: la valuta del negozio o dell'ordine deve essere RON, EUR, USD o GBP. EUR, USD e GBP devono essere abilitate nel tuo account Netopia. Per le altre valute il metodo di pagamento viene nascosto nel checkout.
Account Netopia: ti serve un account venditore Netopia Payments con un punto vendita. Dalle impostazioni tecniche ti servono la firma dell'account e, per ogni ambiente che usi (sandbox e live), il certificato pubblico (.cer) e la chiave privata (.key). Non c'è nulla da configurare lato Netopia: l'indirizzo dell'IPN viene inviato con ogni richiesta di pagamento.
Sito pubblico: l'URL dell'IPN (conferma) deve essere raggiungibile da internet, senza essere protetto da login, autenticazione di base o pagina di manutenzione. Gli ordini vengono aggiornati solo dall'IPN di Netopia.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_netopia_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Netopia Payments > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Nel pannello di Netopia apri il tuo punto vendita, copia la firma dell'account e scarica il certificato e la chiave privata dell'ambiente sandbox e dell'ambiente live. Incolla la firma e il contenuto completo dei file nelle impostazioni (vedi Configurazione).
6. Attiva Enable/Disable. Prova un pagamento in modalità sandbox, poi deseleziona Test mode per accettare pagamenti reali.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Netopia Payments. Sopra i campi la pagina ti avvisa quando mancano la firma dell'account, il certificato o la chiave privata dell'ambiente attivo (il metodo di pagamento viene quindi nascosto nel checkout), e mostra Test mode is on: payments go to the Netopia sandbox and no real money is charged. finché la modalità test è attiva. Nell'elenco dei metodi di pagamento, Netopia risulta da configurare finché l'ambiente attivo non è completo. Al salvataggio, un certificato o una chiave privata non validi vengono rifiutati con un errore e viene mantenuto il valore precedente.
IPN (confirm) URL
Mostrato in sola lettura in cima alle impostazioni. Ha questo aspetto: https://your-site/wc-api/netopia_payment_callback/. Viene inviato con ogni richiesta di pagamento come URL di conferma, quindi non devi inserirlo nel pannello di Netopia. Netopia invia l'IPN a questo URL; il plugin la decifra con la chiave privata dell'ambiente attivo e verifica la firma del tuo account e la richiesta di pagamento. Netopia segnala queste azioni:
Una notifica con un codice di errore Netopia (ad esempio una carta rifiutata) segna come fallito un ordine non pagato. Le notifiche che non possono essere decifrate, che riportano un'altra firma dell'account o che non rispondono a una richiesta di pagamento di quell'ordine vengono rifiutate e non modificano nulla.
Checkout
Enable/Disable: Enable Netopia Payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il titolo del metodo di pagamento mostrato nel checkout. Predefinito: Card Payment (Netopia).
Description: la descrizione del metodo di pagamento mostrata nel checkout. Predefinito: Pay securely with your credit or debit card via Netopia.
Account Netopia
Nel pannello di Netopia vai su Seller accounts > your point of sale > Technical settings: copia la firma dell'account e scarica il certificato pubblico (.cer) e la chiave privata (.key) di ogni ambiente. Apri i file con un editor di testo e incolla il loro contenuto completo, comprese le righe BEGIN/END.
Account signature: la firma dell'account venditore (formato XXXX-XXXX-XXXX-XXXX-XXXX), uguale per sandbox e live.
Test mode: Use the Netopia sandbox (sandboxsecure.mobilpay.ro) and the sandbox keys. Cambia la pagina di pagamento e la coppia di chiavi. Predefinito: attivo. Disattivalo per accettare pagamenti reali con le chiavi live.
Sandbox public certificate (.cer): il contenuto del file del certificato pubblico sandbox. Serve a cifrare la richiesta di pagamento.
Sandbox private key (.key): il contenuto del file della chiave privata sandbox. Serve a decifrare l'IPN. Dopo il salvataggio non viene più mostrato; il campo riporta A private key is saved. Lascialo vuoto per mantenere la chiave salvata, oppure incolla una nuova chiave per sostituirla.
Live public certificate (.cer): il contenuto del file del certificato pubblico live.
Live private key (.key): il contenuto del file della chiave privata live. Dopo il salvataggio non viene più mostrato; lascia il campo vuoto per mantenere la chiave salvata.
Ordini
Order status after payment: lo stato di un ordine pagato che deve essere spedito. Gli ordini con soli articoli virtuali o scaricabili vengono comunque completati da WooCommerce. Lo stato viene impostato con un solo cambio di stato e una sola e-mail al cliente.
Avanzate
Debug log: Log requests and IPN processing scrive in WooCommerce > Status > Logs, origine wcp_netopia_gateway. Dati della carta, chiavi e dati dei clienti non vengono registrati. Gli errori, ad esempio le IPN rifiutate, vengono sempre registrati, anche con l'opzione disattivata. Predefinito: disattivato.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (orders are kept). Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Card Payment (Netopia)) e invia l'ordine. La pagina successiva mostra Redirecting you to Netopia for secure payment… e invia automaticamente il cliente alla pagina di pagamento di Netopia, con i pulsanti Proceed to payment e Cancel order come alternativa. La richiesta di pagamento viene cifrata con il tuo certificato Netopia e contiene il totale dell'ordine nella valuta dell'ordine, Order # con il numero dell'ordine e i dati di fatturazione e spedizione. In modalità sandbox la richiesta va alla sandbox di Netopia.
Il cliente paga con la carta sulla pagina di Netopia e torna alla pagina di conferma ordine del tuo negozio. Il ritorno da solo non segna l'ordine come pagato. L'ordine viene segnato come pagato solo dopo che Netopia lo conferma tramite IPN. Fino ad allora la pagina di conferma ordine mostra Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Per un ordine in attesa mostra Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Se il pagamento è stato annullato, mostra The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time.
Se la carta viene rifiutata, l'ordine viene segnato come fallito e il cliente può pagarlo di nuovo dalla pagina dell'ordine. Se il plugin non è configurato correttamente, la pagina di pagamento mostra Netopia gateway is not configured properly. Please contact the store administrator.
Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin accetta pagamenti con carta solo tramite il protocollo carte Netopia v1. Non prevede rimborsi o acquisizioni da WooCommerce, né carte salvate o pagamenti con un clic, né abbonamenti, rate, SMS, bonifici bancari o pagamenti in criptovalute, e non supporta Netopia API v2.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Netopia, oppure Netopia non ha ancora inviato l'IPN.
Processing or Completed: Netopia ha confermato il pagamento. Lo stato segue Order status after payment. La nota dell'ordine mostra l'importo, il numero della carta mascherato e la transazione Netopia; i pagamenti sandbox sono contrassegnati con [sandbox]. L'ID transazione è quello della transazione Netopia.
On hold: il pagamento è una pre-autorizzazione in attesa di acquisizione nel pannello di Netopia, oppure è in verifica presso Netopia. L'ordine viene segnato come pagato quando Netopia lo conferma. Un ordine viene messo in attesa anche quando importo o valuta della fattura differiscono dall'ordine, quando è stata acquisita solo una parte del pagamento, o quando Netopia conferma il pagamento di un ordine annullato. La nota dell'ordine lo spiega. Verifica la transazione nel pannello di Netopia e completa o rimborsa l'ordine manualmente.
Failed: Netopia ha segnalato un errore, ad esempio una carta rifiutata. Il cliente può pagare di nuovo.
Cancelled: Netopia ha annullato il pagamento, oppure il cliente ha fatto clic su Cancel order prima di passare a Netopia.
Le notifiche tardive non retrocedono mai un ordine pagato. Se Netopia conferma un altro pagamento per un ordine già pagato, una nota ti chiede di rimborsare il duplicato nel pannello di Netopia.
Rimborsi
I rimborsi non si effettuano da WooCommerce: il protocollo carte Netopia v1 non ha una chiamata di rimborso, quindi non esiste il pulsante Refund via. Rimborsa la transazione nel pannello di Netopia. Netopia invia poi un'IPN di accredito, e il plugin registra automaticamente il rimborso sull'ordine con il motivo Refund initiated by Netopia. I rimborsi parziali lasciano invariato lo stato dell'ordine; quando non resta nulla da rimborsare, WooCommerce imposta l'ordine su Refunded. Per gli ordini in EUR, USD e GBP, l'importo rimborsato, che Netopia riporta in RON, viene riconvertito nella valuta dell'ordine. Un rimborso non viene mai registrato due volte né per un importo superiore a quello residuo. Lo stock non viene ripristinato automaticamente.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Netopia Payments. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.
Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Netopia non viene mostrato ai clienti nel checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio connessi vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati, e i rimborsi effettuati nel pannello di Netopia continuano a essere registrati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
Risoluzione dei problemi
Netopia non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che l'ambiente attivo sia completo (Account signature più il certificato e la chiave privata della sandbox in modalità test, oppure quelli di live in modalità live) e che la valuta del negozio o dell'ordine sia RON, EUR, USD o GBP. La pagina delle impostazioni mostra un avviso quando manca qualcosa.
Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: l'IPN non ha raggiunto il tuo negozio o è stata rifiutata. Verifica che l'URL dell'IPN (conferma) indicato nelle impostazioni sia raggiungibile da internet (senza modalità manutenzione, autenticazione di base o firewall). Attiva Debug log e cerca le righe IPN in WooCommerce > Status > Logs, origine wcp_netopia_gateway. Il ritorno del cliente, da solo, non segna mai l'ordine come pagato.
Log shows failed decrypting data: la chiave privata non corrisponde al certificato dell'ambiente usato da Netopia. L'IPN viene decifrata con la chiave dell'ambiente attivo e, per i pagamenti avviati prima del cambio di modalità test, con la chiave dell'altro ambiente. Netopia la rinvia.
Log shows signature mismatch: la Account signature non corrisponde al punto vendita che ha inviato l'IPN. Copiala di nuovo dal pannello di Netopia.
Log shows unknown payment request: l'IPN non risponde a una richiesta di pagamento che il tuo negozio ha fatto per quell'ordine in quell'ambiente (sandbox o live). Non viene modificato nulla.
Log shows gateway not configured: manca la chiave privata o la firma dell'account. Netopia rinvia l'IPN, e il pagamento viene registrato quando le impostazioni sono complete.
Error on save about the certificate or private key: il testo incollato non è un certificato o una chiave validi. Incolla il contenuto completo del file, comprese le righe BEGIN/END. È stato mantenuto il valore precedente.
Order is On hold after payment: leggi la nota dell'ordine. Il pagamento potrebbe essere una pre-autorizzazione o essere in verifica, importo o valuta potrebbero essere diversi, è stata acquisita solo una parte, l'ordine era stato annullato, oppure è stato confermato un pagamento sandbox mentre il negozio era in modalità live (non è stato ricevuto denaro reale). Verifica la transazione nel pannello di Netopia.
A refund made in Netopia does not appear on the order: l'IPN di accredito non ha raggiunto il negozio o è stata rifiutata. Controlla il log. Se necessario, crea un rimborso manuale in WooCommerce.
The license block shows an error: segui il messaggio nel blocco. Ad esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Disinstallazione
Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, comprese le chiavi salvate, e i registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano disponibili per una futura reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID delle transazioni.
Netopia Payments e mobilPay sono marchi dei rispettivi proprietari. Questo plugin non è affiliato né approvato da Netopia Payments.