VibeFox Netopia for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con le estensioni OpenSSL, DOM e SimpleXML. Il modulo non si installa senza di esse.

Valuta: la valuta del carrello 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 al checkout.

Account Netopia: ti serve un account venditore Netopia Payments con un punto vendita. Dalle sue impostazioni tecniche ti servono la firma dell'account e, per ciascun ambiente che usi (sandbox e live), il certificato pubblico (.cer) e la chiave privata (.key). Non c'è nulla da configurare lato Netopia: l'indirizzo IPN viene inviato con ogni richiesta di pagamento.

Negozio pubblico: l'URL IPN (conferma) deve essere raggiungibile da internet, non protetto da login o autenticazione di base. Gli ordini vengono creati solo dall'IPN di Netopia.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Netopia Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. 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).

5. Attiva Enable/Disable e fai clic su Save. Prova un pagamento in modalità sandbox, poi disattiva Test mode per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine, Awaiting Netopia payment e Netopia payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni sono nella pagina del modulo: Modules > Module Manager > VibeFox Netopia Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa se mancano la firma dell'account, il certificato o la chiave privata dell'ambiente attivo (in tal caso il metodo di pagamento viene nascosto al checkout) e mostra Test mode is on: payments go to the Netopia sandbox and no real money is charged. finché la modalità test è attiva. Al salvataggio, un certificato o una chiave privata non validi vengono rifiutati con un errore e si mantiene il valore precedente; gli altri campi vengono salvati.

IPN (confirm) URL

È mostrato in sola lettura in cima alla pagina. Con gli URL semplificati ha questo aspetto: https://your-shop/module/wcp_netopia_gateway/notify, eventualmente con un codice lingua come /en/. 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 modulo la decifra con la chiave privata dell'ambiente in cui è stato avviato il pagamento e verifica la firma del tuo account e la richiesta di pagamento. Netopia segnala queste azioni:

Una notifica con un codice di errore Netopia (per esempio una carta rifiutata) imposta un ordine in attesa su Payment error; senza ordine il cliente può pagare di nuovo. Le notifiche che non possono essere decifrate, che riportano un'altra firma dell'account o che non rispondono a una richiesta di pagamento di quel carrello vengono rifiutate e non modificano nulla.

Checkout

Enable/Disable: Enable Netopia Payments attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il titolo del metodo di pagamento mostrato al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Card Payment (Netopia).

Description: la descrizione del metodo di pagamento mostrata al 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 tutto il contenuto, incluse le righe BEGIN/END.

Account signature: la firma dell'account venditore (formato XXXX-XXXX-XXXX-XXXX-XXXX), la stessa per sandbox e live.

Test mode: usa la sandbox di Netopia (sandboxsecure.mobilpay.ro) e le chiavi sandbox. Predefinito: on. 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.

Live public certificate (.cer): il contenuto del file del certificato pubblico live.

Live private key (.key): il contenuto del file della chiave privata live.

Le chiavi private salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e il suo testo di aiuto inizia con A private key is saved. Lascialo vuoto per mantenere la chiave salvata, oppure incolla una nuova chiave per sostituirla. Un campo del certificato vuoto rimuove il certificato.

Clear saved private keys: spunta una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene la chiave salvata.

Ordini

Order status after payment: lo stato di un ordine pagato.

Avanzate

Debug log: scrive richieste ed elaborazione delle IPN in logs/netopia_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Dati della carta, chiavi e dati dei clienti non vengono registrati. Gli errori, per esempio le IPN rifiutate, vengono sempre registrati, anche con l'opzione disattivata. Predefinito: off.

Log: mostra la dimensione e le ultime voci del registro. Fai clic su Clear log per svuotarlo.

Delete data on uninstall: alla disinstallazione del modulo rimuove le impostazioni del gateway, i record di pagamento Netopia del modulo e il registro. Gli ordini vengono conservati. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Card Payment (Netopia)) e conferma. La pagina successiva mostra Redirecting you to Netopia for secure payment… e invia automaticamente il cliente alla pagina di pagamento Netopia, con i pulsanti Proceed to payment e Cancel (torna al checkout) come alternativa. La richiesta di pagamento viene cifrata con il tuo certificato Netopia e contiene il totale del carrello nella valuta del carrello, Cart # con il numero del carrello, e i dati di contatto di fatturazione e spedizione. In modalità sandbox la richiesta va alla sandbox di Netopia. A questo punto non esiste ancora alcun ordine.

Il cliente paga con la carta nella pagina di Netopia e torna nel tuo negozio. Il ritorno non crea né paga mai un ordine. L'ordine viene segnato come pagato solo dopo che Netopia lo conferma tramite IPN. Se l'ordine esiste, il cliente vede la normale pagina di conferma dell'ordine. Per un ordine in attesa 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 di conferma mostra Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Per un ordine annullato mostra The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. Per un ordine con errore di pagamento mostra The payment was declined by Netopia.

Se l'IPN non è ancora arrivata quando il cliente torna, una pagina Payment confirmation mostra lo stesso testo «non ancora confermato» con i pulsanti Check again e Back to checkout. L'ordine viene creato appena arriva l'IPN.

Se Netopia ha segnalato un annullamento o un rifiuto prima che venisse creato un ordine, il cliente torna al checkout con The payment was cancelled at Netopia. You can try again or choose another payment method. oppure The payment was declined by Netopia. You can try again or choose another payment method. Il carrello viene conservato. Ogni nuovo tentativo è una nuova richiesta di pagamento; le richieste precedenti del carrello restano valide, quindi un'IPN in ritardo di un tentativo precedente viene comunque registrata.

Se il modulo non è configurato correttamente, il cliente resta al checkout con Netopia gateway is not configured properly. Please contact the store administrator. Gli altri messaggi sono Netopia cannot process payments in seguito dalla valuta, This order has nothing to pay. e Payment encryption failed. Please try again or contact support. Il motivo tecnico viene scritto nel registro.

L'IPN funziona mentre il negozio è in modalità manutenzione e non viene bloccata dalla restrizione per paese del tuo negozio.

Il modulo accetta pagamenti con carta solo tramite il protocollo carte Netopia v1. Non prevede rimborsi o acquisizioni da PrestaShop, carte salvate o pagamenti con un clic, abbonamenti, rate o altri metodi di pagamento, e non supporta Netopia API v2.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Netopia e non ha ancora pagato, oppure Netopia non ha ancora inviato l'IPN. Esiste solo il carrello.

Payment accepted or Delivered: Netopia ha confermato il pagamento. Lo stato segue Order status after payment. Il pagamento viene registrato con la transazione Netopia come ID transazione, e una nota privata mostra l'importo, il numero della carta mascherato e la transazione Netopia; i pagamenti sandbox sono contrassegnati con [sandbox].

Awaiting Netopia payment: il pagamento è una preautorizzazione in attesa di acquisizione nel pannello di Netopia, oppure è in verifica presso Netopia. Non è ancora registrato alcun pagamento. L'ordine passa allo stato pagato quando Netopia lo conferma.

Netopia payment on hold: l'importo o la valuta della fattura differiscono dal carrello o dall'ordine, è stata acquisita solo una parte del pagamento, Netopia ha confermato il pagamento di un ordine annullato o di un ordine effettuato con un altro metodo di pagamento, oppure un pagamento sandbox (di prova) è stato confermato mentre il negozio è in modalità live (non è stato ricevuto denaro reale, quindi non viene registrato alcun pagamento). La nota lo spiega. Controlla la transazione nel pannello di Netopia, poi elabora l'ordine o rimborsa lì il pagamento.

Payment error: Netopia ha segnalato un errore, per esempio una carta rifiutata, per un ordine in attesa.

Canceled: Netopia ha annullato il pagamento di un ordine in attesa.

Refunded: il pagamento è stato rimborsato interamente nel pannello di Netopia.

Le notifiche tardive non retrocedono mai un ordine pagato o chiuso. Se Netopia conferma un altro pagamento per un ordine già pagato, una nota ti chiede di rimborsare il duplicato nel pannello di Netopia.

Blocco Netopia

La pagina dell'ordine mostra un blocco Netopia Payments con la transazione Netopia, l'ambiente (sandbox o live), la richiesta di pagamento, l'ultima azione IPN, la carta mascherata, gli importi pagato, rimborsato e rimanente, e lo storico dei rimborsi. Il blocco è di sola lettura.

Rimborsi

I rimborsi non si effettuano da PrestaShop: il protocollo carte Netopia v1 non ha una chiamata di rimborso. Rimborsa la transazione nel pannello di Netopia. Netopia invia quindi un'IPN di accredito, e il modulo registra automaticamente il rimborso sull'ordine con la nota Netopia refund processed: e l'importo. Un rimborso parziale mantiene lo stato dell'ordine; quando non resta nulla da rimborsare, l'ordine viene impostato 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 rimanente. Se Netopia segnala un errore per il rimborso, viene aggiunta solo una nota.

Il modulo non crea note di credito e non ripristina le scorte dei prodotti. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Netopia.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Netopia Gateway è il primo blocco nella pagina Modules > Module Manager > VibeFox Netopia Gateway > Configure, sopra le impostazioni. Inserisci la chiave nel campo License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto di essi ci sono la riga Product: presta-payment-netopia e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Netopia non viene mostrata ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. 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 modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Netopia non compare al 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 live in modalità live) e che la valuta del carrello sia RON, EUR, USD o GBP. La pagina delle impostazioni mostra un avviso quando manca qualcosa. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: l'IPN non ha raggiunto il tuo negozio oppure è stata rifiutata. Verifica che l'URL IPN (conferma) indicato nelle impostazioni sia raggiungibile da internet (nessuna autenticazione di base né firewall). Controlla il campo Log nella pagina del modulo: le IPN rifiutate vengono sempre registrate. Attiva Debug log per vedere ogni IPN. Il solo ritorno del cliente non crea mai un ordine.

Il log mostra failed decrypting data: la chiave privata non corrisponde al certificato usato da Netopia. L'IPN viene decifrata con la chiave privata salvata di ciascun ambiente, quindi mantieni salvata la chiave dell'altro ambiente finché i suoi pagamenti sono aperti. Netopia ripete l'IPN.

Il log mostra signature mismatch: la Account signature non corrisponde al punto vendita che ha inviato l'IPN. Copiala di nuovo dal pannello di Netopia.

Il log mostra unknown payment request: l'IPN non risponde a una richiesta di pagamento che il tuo negozio ha fatto per quel carrello in quell'ambiente (sandbox o live). Non viene modificato nulla.

Il log mostra gateway not configured: non sono salvate una chiave privata o una firma dell'account. Netopia ripete l'IPN, e il pagamento viene registrato quando le impostazioni sono complete.

Il log mostra busy, retry later or processing failed: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). Netopia ripete automaticamente l'IPN.

Errore al salvataggio su certificato o chiave privata: il testo incollato non è un certificato o una chiave validi. Incolla il contenuto completo del file, incluse le righe BEGIN/END. È stato mantenuto il valore precedente.

L'ordine è in Netopia payment on hold dopo il pagamento: leggi la nota privata dell'ordine (vedi Stati dell'ordine). L'importo o la valuta erano diversi, è stata acquisita solo una parte, l'ordine era stato annullato, oppure un pagamento sandbox è stato confermato mentre il negozio era in modalità live. Controlla la transazione nel pannello di Netopia.

Un rimborso effettuato in Netopia non compare sull'ordine: l'IPN di accredito non ha raggiunto il negozio oppure è stata rifiutata. Controlla il log.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Netopia Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni del gateway (incluse le chiavi salvate), i record di pagamento Netopia del modulo (mostrati nel blocco Netopia degli ordini) e il registro. Se è disattivo, tutto viene conservato per una successiva reinstallazione. Gli ordini e gli stati dell'ordine Awaiting Netopia payment e Netopia payment on hold non vengono mai eliminati. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.

Netopia Payments e mobilPay sono marchi dei rispettivi titolari. Questo modulo non è affiliato né approvato da Netopia Payments.