VibeFox Niubiz for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Valuta: soles peruviani (PEN) o dollari statunitensi (USD). Il metodo di pagamento viene offerto solo per i carrelli in una di queste valute. Per le altre valute è nascosto al checkout.

Account Niubiz: Niubiz rilascia un merchant ID (código de comercio), un API user e una API password per ciascun ambiente. Le credenziali sandbox vengono fornite dal team di integrazione di Niubiz, quelle di produzione dopo che Niubiz ha certificato la tua integrazione. Non serve configurare alcun webhook: Niubiz risponde subito all'autorizzazione.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo 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, più tardi, trova VibeFox Niubiz Payment 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 fai clic su Activate (vedi Chiave di licenza).

4. Lascia attivo Sandbox mode e inserisci merchant ID, API user e API password della sandbox (vedi Configurazione).

5. Attiva Enable/Disable, fai clic su Save ed effettua alcuni pagamenti di prova con le carte di test di Niubiz.

6. Quando Niubiz avrà certificato la tua integrazione, inserisci le credenziali di produzione e disattiva Sandbox mode.

All'installazione il modulo crea lo stato dell'ordine Niubiz payment on hold. PrestaShop collega un nuovo modulo di pagamento a tutte le valute, a tutti i gruppi di clienti e ai paesi attivi in quel momento. Puoi modificarlo in Payment > Preferences. Controlla lì che PEN o USD sia consentito per il modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Niubiz Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa se nel negozio non è attiva nessuna valuta PEN o USD, oppure se le credenziali della modalità corrente sono incomplete (in entrambi i casi il metodo di pagamento viene nascosto al checkout). Se la valuta predefinita del negozio non è PEN né USD, la pagina ti informa che Niubiz è offerto solo per i carrelli in PEN o USD. Finché la modalità sandbox è attiva, la pagina mostra La modalità sandbox è attiva: i pagamenti vanno alla sandbox di Niubiz e non viene effettuato alcun addebito reale.

Niubiz

Enable/Disable: Enable Niubiz payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit or debit card (Niubiz). Obbligatorio: un titolo vuoto non viene salvato e resta quello precedente.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Credenziali Niubiz

Niubiz ti fornisce un merchant ID, un API user e una API password per la sandbox e, dopo la certificazione, per la produzione. La documentazione per gli sviluppatori è disponibile su desarrolladores.niubiz.com.pe.

Sandbox mode: usa l'ambiente sandbox (QA) di Niubiz, senza addebiti reali. Cambia sia gli endpoint API sia l'insieme di credenziali qui sotto. Predefinito: attivo. Disattivalo per i pagamenti reali. Finché è attivo, i clienti vedono sotto il metodo di pagamento e nella pagina di pagamento MODALITÀ SANDBOX: usa le carte di test di Niubiz — non viene effettuato alcun addebito reale.

Sandbox merchant ID: il codice commerciante del tuo account sandbox, solo cifre. Gli spazi vengono rimossi. Se il valore contiene altri caratteri, la pagina mostra un errore e mantiene il valore precedente. Gli altri campi vengono salvati.

Sandbox API user: l'API user della sandbox.

Sandbox API password: la API password della sandbox.

Production merchant ID: il codice commerciante del tuo account di produzione (affiliato), solo cifre, con la stessa verifica.

Production API user: l'API user di produzione.

Production API password: la API password di produzione.

Le password salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Salvata — lascia vuoto per mantenerla. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear saved passwords: spunta una password e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Modulo di pagamento

Logo URL: indirizzo HTTPS facoltativo del tuo logo, mostrato nel modulo di pagamento Niubiz, di circa 187 × 40 px. Senza di esso viene mostrato il nome del negozio. Un indirizzo che non è un indirizzo https:// valido viene rifiutato con un errore e resta quello precedente.

Avanzate

Debug log: registra le chiamate API di Niubiz in logs/niubiz_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando questo interruttore è disattivato. Credenziali, token, dati della carta e dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le sue impostazioni e il registro. I dati di pagamento salvati per gli ordini (tentativi Niubiz, note dell'ordine) e lo stato dell'ordine vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit or debit card (Niubiz)) e conferma l'ordine. Il modulo chiede a Niubiz un token di accesso e una sessione di pagamento per il totale del carrello nella valuta del carrello, e apre la pagina di pagamento Niubiz payment del tuo negozio. A questo punto non esiste ancora alcun ordine.

Nella pagina di pagamento il modulo Niubiz si apre automaticamente. La pagina riporta Completa il pagamento nel modulo di pagamento sicuro di Niubiz — i dati della tua carta vengono inseriti su Niubiz, non su questo sito. Ha anche un pulsante Pay con il totale del carrello per riaprire il modulo e un link Choose another payment method. È richiesto JavaScript. Se il modulo Niubiz non può essere caricato, la pagina mostra Impossibile caricare il modulo di pagamento Niubiz. Ricarica la pagina o riprova più tardi.

Il cliente inserisce la carta nel modulo Niubiz. Niubiz restituisce al tuo negozio un token monouso, e il modulo lo autorizza sul server con l'importo, la valuta e il numero di acquisto della sessione, nell'ambiente in cui la sessione è stata creata. Il pagamento viene addebitato subito. L'ordine viene segnato come pagato solo quando Niubiz approva il pagamento e la risposta corrisponde al carrello. Poi l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine.

Carta rifiutata: non viene creato alcun ordine. Il cliente torna alla pagina di pagamento con Il tuo pagamento è stato rifiutato: e il motivo di Niubiz, e può riprovare con la stessa carta o con un'altra. Il modulo non si riapre sopra il messaggio; il cliente fa clic su Pay.

Nessuna risposta da Niubiz: se Niubiz non dà una risposta definitiva (timeout, errore del server, risposta illeggibile), l'ordine viene creato in Niubiz payment on hold e la pagina di conferma mostra Non siamo riusciti a confermare il tuo pagamento con Niubiz. Non pagare di nuovo: il negozio verificherà il pagamento e ti contatterà. Se Niubiz ha approvato un pagamento che non corrisponde al carrello, la pagina mostra Il tuo pagamento è stato ricevuto e il negozio lo sta verificando. Ti contatteremo se serve qualcos'altro.

Richiesta rifiutata: se Niubiz rifiuta la richiesta stessa (per esempio credenziali non valide o un numero di acquisto duplicato), non viene creato alcun ordine e il cliente vede Niubiz non ha potuto elaborare il pagamento e la tua carta non è stata addebitata. Il motivo viene scritto nel registro.

Carrello modificato: se il totale del carrello cambia dopo l'apertura del modulo (per esempio in un'altra scheda del browser), il pagamento non viene autorizzato e il cliente vede Il tuo carrello è cambiato dopo l'apertura del modulo di pagamento, quindi la tua carta non è stata addebitata. Controlla il totale e paga di nuovo.

Sessione scaduta: una sessione di pagamento Niubiz dura fino a 20 minuti. Se è già stata usata, se restano meno di 5 minuti, se appartiene a un'altra modalità o a un altro merchant ID, oppure se il totale del carrello è cambiato, la pagina di pagamento crea una nuova sessione.

Ogni tentativo di pagamento riceve un nuovo numero di acquisto: l'ID del carrello seguito da un numero di tentativo a tre cifre (fino a 12 caratteri), perché Niubiz richiede un numero di acquisto unico per ogni autorizzazione.

Il modulo accetta solo pagamenti singoli con carta. Non prevede rimborsi o annullamenti da PrestaShop, carte salvate, abbonamenti o pagamenti ricorrenti, scelta di pagamenti rateali (cuotas), né pagamenti con PagoEfectivo, Yape o altri wallet e pagamenti QR. Gli ordini messi in attesa perché la risposta è andata persa non vengono ricontrollati automaticamente.

Ordini

Stati dell'ordine

No order yet: il cliente si trova nella pagina di pagamento e non ha pagato, oppure la carta è stata rifiutata o la richiesta respinta. Esiste solo il carrello. Rifiuti e respingimenti vengono scritti nel registro del modulo.

Payment accepted: Niubiz ha approvato il pagamento e la risposta corrispondeva al carrello. Il pagamento viene registrato con l'ID transazione di Niubiz, e una nota mostra l'ambiente, l'ID transazione, il codice di autorizzazione, il numero di acquisto e il marchio della carta con il numero mascherato.

Niubiz payment on hold, approved but not matching: Niubiz ha approvato un pagamento il cui numero di acquisto, importo o valuta differisce dal carrello, oppure la cui risposta non contiene importo o valuta. L'ordine non viene segnato come pagato. Se l'approvazione è nella valuta del carrello, l'importo approvato viene registrato come pagamento con il suo ID transazione. La nota elenca le differenze. Controlla la transazione nella console Niubiz.

Niubiz payment on hold, no definitive answer: Niubiz non ha risposto in modo chiaro, quindi la carta potrebbe essere stata addebitata. Non viene registrato alcun pagamento. La nota riporta il numero di acquisto. Cercalo nella console Niubiz: se la transazione è approvata e corretta, imposta l'ordine su Payment accepted; in caso contrario, annullalo.

Se per un carrello che ha già un ordine arriva la risposta a un secondo pagamento, non viene creato un secondo ordine. Una nota sull'ordine riporta il numero di acquisto, l'ID transazione e l'importo, così puoi verificarlo nella console Niubiz e rimborsarlo o annullarlo se necessario.

Blocco pagamento Niubiz

La pagina dell'ordine mostra un blocco Niubiz payment con il numero di acquisto, l'ambiente (sandbox o produzione), l'ID transazione, il codice di autorizzazione, la carta e le note dell'ordine. Per un ordine in Niubiz payment on hold, il blocco ti ricorda di controllare il numero di acquisto nella console Niubiz. Il blocco è di sola lettura.

Rimborsi

Rimborsi e annullamenti non sono disponibili da PrestaShop. Rimborsa o annulla la transazione nella console Niubiz e aggiorna l'ordine manualmente. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Niubiz.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Niubiz Payment è il primo blocco di Modules > Module Manager > VibeFox Niubiz Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché 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 compaiono la riga Product: presta-payment-niubiz 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 Chiave non trovata, Questa chiave appartiene a un altro prodotto, Limite di domini raggiunto o Licenza scaduta il seguito da una data. Dopo che l'indirizzo del negozio cambia, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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, Niubiz non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non provarlo 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.

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 per i 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

Niubiz non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che merchant ID, API user e API password della modalità corrente siano compilati (i campi sandbox in modalità sandbox, quelli di produzione altrimenti) e che la valuta del carrello sia PEN o USD. La pagina delle impostazioni mostra un avviso se le credenziali o le valute non sono corrette. 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: Niubiz non ha un webhook per questo modulo di pagamento, quindi l'ordine viene creato solo dalla risposta all'autorizzazione. Se il cliente non ha completato il modulo, non c'è alcun ordine. Altrimenti controlla il campo Log nella pagina del modulo e cerca il numero di acquisto nella console Niubiz. Se Niubiz ha risposto ma l'ordine non è stato creato (per esempio perché il modulo era disattivato), il cliente vede Il tuo pagamento è stato ricevuto, ma non è stato possibile completare l'ordine automaticamente. Contattaci — non pagare di nuovo., e il modulo riprova a creare l'ordine quando il cliente riapre la pagina di pagamento.

Il cliente vede «Impossibile connettersi a Niubiz»: non è stato possibile ottenere il token di accesso. Verifica API user e API password della modalità corrente e che il tuo server possa raggiungere l'API di Niubiz. Attiva Debug log per i dettagli.

Il cliente vede «Impossibile avviare il pagamento Niubiz»: Niubiz non ha creato la sessione di pagamento. Controlla il merchant ID della modalità corrente e il registro.

Il cliente vede «Questo tentativo di pagamento è già stato elaborato»: lo stesso modulo è stato inviato due volte. Il cliente avvia di nuovo il pagamento dalla pagina di pagamento; la carta non viene addebitata due volte.

Il cliente vede «Questo ordine è già in fase di pagamento»: un'altra richiesta sta autorizzando in questo momento lo stesso carrello. Il cliente attende un momento e controlla l'e-mail prima di riprovare.

Il registro mostra che Niubiz ha segnalato un'autorizzazione duplicata: Niubiz conosce già questo numero di acquisto. Controllalo nella console Niubiz; il cliente può riprovare con un nuovo numero di acquisto.

L'ordine è in Niubiz payment on hold: leggi le note nel blocco Niubiz payment. Niubiz non ha dato una risposta definitiva, oppure ha approvato un pagamento che non corrisponde al carrello. Cerca il numero di acquisto nella console Niubiz e imposta l'ordine su Payment accepted o annullalo.

Errore durante il salvataggio delle impostazioni: il merchant ID deve contenere solo cifre, e l'URL del logo deve essere un indirizzo https:// valido. Resta il valore precedente.

Per gli sviluppatori: se Niubiz chiede di inviare campi antifrode specifici del commerciante (MDD), un altro modulo può aggiungerli con l'hook actionNiubizPMerchantDefineData. I dati del titolare inviati con la sessione di pagamento possono essere modificati con l'hook actionNiubizPCardholderData.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Niubiz Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, le impostazioni del modulo e il registro vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione futura. I tentativi di pagamento Niubiz (numeri di acquisto, ambiente, ID transazione) e lo stato dell'ordine Niubiz payment on hold vengono sempre conservati come storico dei pagamenti. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.

Niubiz è un marchio registrato del suo rispettivo titolare. Questo modulo non è affiliato né approvato da Niubiz.