VibeFox Niubiz for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 6.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Valuta del negozio: soles peruviani (PEN) o dollari statunitensi (USD). Per le altre valute il metodo di pagamento viene nascosto al checkout.

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

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. Puoi anche caricare la cartella wcp_niubiz_payment in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Niubiz > Manage, oppure clicca 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 clicca su Activate.

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

6. Attiva Enable/Disable ed effettua alcuni pagamenti di prova con le carte di test di Niubiz.

7. Quando Niubiz certifica la tua integrazione, inserisci le credenziali di produzione e deseleziona Sandbox mode.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > Niubiz. Sopra i campi la pagina ti avvisa quando la valuta del negozio non è PEN né USD, o quando le credenziali della modalità corrente sono incomplete (in entrambi i casi il metodo di pagamento viene nascosto al checkout), e mostra La modalità sandbox è attiva: i pagamenti vanno al sandbox di Niubiz e non viene effettuato alcun addebito reale. finché la modalità sandbox è attiva. Nell'elenco dei metodi di pagamento, Niubiz risulta da configurare finché la modalità corrente non ha credenziali complete.

Generali

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Credit or debit card (Niubiz).

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 un'API password per il sandbox e, dopo la certificazione, per la produzione. La documentazione per sviluppatori si trova su desarrolladores.niubiz.com.pe.

Sandbox mode: Use the Niubiz sandbox (QA) environment — no real charges. Cambia sia gli endpoint dell'API sia l'insieme di credenziali qui sotto. Predefinito: attivo. Deselezionalo per i pagamenti reali.

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

Sandbox API user: l'API user del sandbox.

Sandbox API password: l'API password del sandbox.

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

Production API user: l'API user di produzione.

Production API password: l'API password di produzione.

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 inizia con https:// viene rifiutato e resta il valore precedente.

Avanzate

Debug log: Log API calls scrive le richieste Niubiz in WooCommerce > Status > Logs, origine wcp_niubiz_payment. Gli errori vengono sempre registrati. Credenziali, token e dati della carta o del cliente non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted. La disattivazione non elimina mai nulla. I dati di pagamento salvati sugli ordini vengono conservati. Predefinito: disattivato.

Le impostazioni della versione 1.0, che aveva un solo set di credenziali, vengono spostate automaticamente: nei campi sandbox se la modalità test era attiva, altrimenti nei campi di produzione.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit or debit card (Niubiz)) e conferma l'ordine. Il plugin richiede a Niubiz un token di accesso e una sessione di pagamento per il totale dell'ordine e invia il cliente alla pagina di pagamento dell'ordine del tuo negozio. In modalità sandbox, il checkout e la pagina di pagamento mostrano MODALITÀ SANDBOX: usa le carte di test di Niubiz. Non viene effettuato alcun addebito reale.

Sulla pagina di pagamento il modulo Niubiz si apre automaticamente. La pagina ha anche un pulsante Pay con il totale dell'ordine per riaprire il modulo, un pulsante Cancel order 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 plugin lo autorizza sul server con l'importo, la valuta e il numero di acquisto propri dell'ordine. Il pagamento viene addebitato subito. L'ordine viene segnato come pagato solo quando Niubiz approva il pagamento e la risposta corrisponde all'ordine. Il cliente vede poi la pagina di conferma dell'ordine.

Carta rifiutata: 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 clicca su Pay.

Nessuna risposta da Niubiz: se Niubiz non fornisce una risposta definitiva (timeout, errore del server, risposta illeggibile), il cliente vede la pagina di conferma dell'ordine con Non siamo riusciti a confermare il tuo pagamento con Niubiz. Non pagare di nuovo: il negozio verificherà il pagamento e ti contatterà.

Sessione scaduta: la sessione di pagamento dura fino a 20 minuti. Quando viene usata o sta per scadere, oppure quando cambiano il totale dell'ordine o la modalità, la pagina di pagamento crea una nuova sessione.

Ogni tentativo di pagamento riceve un nuovo numero di acquisto: l'ID dell'ordine seguito da un numero di tentativo di tre cifre (fino a 12 caratteri), perché Niubiz richiede un numero di acquisto univoco per ogni autorizzazione. Un cliente può pagare di nuovo un ordine non pagato o non riuscito dalla pagina Pay for order.

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 solo pagamenti singoli con carta. Non prevede rimborsi o annullamenti da WooCommerce, carte salvate, abbonamenti o pagamenti ricorrenti, selezione di rate (cuotas) né 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

Pagamento in attesa: il cliente è stato inviato alla pagina di pagamento e non ha ancora pagato.

In lavorazione: Niubiz ha approvato il pagamento e la risposta corrispondeva all'ordine. Gli ordini con soli prodotti virtuali scaricabili passano a Completato, come di consueto in WooCommerce. La nota dell'ordine mostra l'ambiente, l'ID transazione, il codice di autorizzazione, il numero di acquisto e il marchio della carta con il numero mascherato. L'ID transazione dell'ordine è l'ID transazione di Niubiz.

Non riuscito: la carta è stata rifiutata. La nota dell'ordine mostra il motivo di Niubiz, il codice azione e il numero di acquisto. Il cliente può pagare di nuovo.

In attesa, approvato ma non corrispondente: Niubiz ha approvato un pagamento il cui numero di acquisto, importo o valuta differisce dall'ordine, oppure la cui risposta non contiene importo o valuta. L'ordine non viene segnato come pagato; la nota elenca le differenze. Verifica la transazione nella console Niubiz. Il cliente vede Il tuo pagamento è stato ricevuto ed è in fase di verifica da parte del negozio.

In attesa, nessuna risposta definitiva: Niubiz non ha risposto in modo chiaro, quindi la carta potrebbe essere stata addebitata. La nota riporta il numero di acquisto. Cercalo nella console Niubiz: se la transazione è approvata e corretta, imposta l'ordine su In lavorazione; altrimenti annullalo.

Annullato: il cliente ha cliccato su Cancel order nella pagina di pagamento, oppure l'ordine è stato annullato da te o dal timeout di prenotazione dello stock di WooCommerce.

Quando Niubiz rifiuta la richiesta in sé (per esempio un numero di acquisto duplicato, HTTP 406 o credenziali non valide), lo stato dell'ordine non cambia. Una nota indica che la carta non è stata addebitata, e il cliente può riprovare con un nuovo numero di acquisto.

Rimborsi

Rimborsi e annullamenti non sono disponibili da WooCommerce. Rimborsa o annulla la transazione nella console Niubiz e aggiorna manualmente l'ordine, per esempio con un rimborso manuale di WooCommerce.

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 > Niubiz. Incolla la chiave in License key e clicca su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare 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 solo dominio. Rimuovere la chiave da un sito 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 un pagamento viene avviato comunque, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. Gli amministratori del negozio connessi vedono ancora il metodo di pagamento, contrassegnato come (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 coinvolti: i pagamenti già avviati nel modulo Niubiz vengono comunque autorizzati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

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 (campi sandbox in modalità sandbox, campi di produzione altrimenti) e che la valuta sia PEN o USD. Nella pagina Pay for order conta la valuta dell'ordine. La pagina delle impostazioni mostra un avviso quando le credenziali o la valuta sono errate.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: Niubiz non ha un webhook per questo modulo di pagamento, quindi l'ordine viene aggiornato solo dalla risposta all'autorizzazione. Se l'ordine è In attesa con una nota, cerca il numero di acquisto nella console Niubiz. Se resta In attesa di pagamento, il cliente non ha completato il modulo; controlla WooCommerce > Status > Logs, origine wcp_niubiz_payment.

Il cliente vede Non siamo riusciti a connetterci 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 il Debug log per i dettagli.

Il cliente vede Non siamo riusciti ad avviare il pagamento Niubiz: Niubiz non ha creato la sessione di pagamento. Verifica il merchant ID della modalità corrente e il log.

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 La tua sessione di pagamento è scaduta e la tua carta non è stata addebitata: la pagina di pagamento è rimasta aperta troppo a lungo. Il cliente riprova sulla stessa pagina.

Nota dell'ordine: Niubiz ha segnalato un'autorizzazione duplicata: Niubiz conosce già questo numero di acquisto. Verificalo nella console Niubiz; il cliente può riprovare con un nuovo numero di acquisto.

L'ordine è In attesa con una nota di Niubiz: leggi la nota. Niubiz non ha fornito una risposta definitiva, oppure ha approvato un pagamento che non corrisponde all'ordine. Cerca il numero di acquisto nella console Niubiz e imposta l'ordine su In lavorazione oppure annullalo.

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

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca su Check now per attivare la chiave sul nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Per gli sviluppatori: se Niubiz chiede di inviare campi antifrode specifici del commerciante (MDD), aggiungili con il filtro niubiz_p_merchant_define_data. Le chiavi sono MDD seguito da un numero, i valori fino a 100 caratteri. Altri filtri: niubiz_p_cardholder_data (dati del titolare inviati con la sessione di pagamento), niubiz_p_purchase_number (numero di acquisto di un tentativo, da 1 a 12 lettere o cifre, univoco per tentativo) e niubiz_p_icon (icona del metodo di pagamento).

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log vengono rimossi solo se Delete data on uninstall era attivo. I dati Niubiz salvati sugli ordini (ID transazione, numero di acquisto, carta mascherata) costituiscono lo storico dei pagamenti e vengono sempre conservati. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

Niubiz è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Niubiz né approvato da Niubiz.