VibeFox Iugu for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Senza WooCommerce il plugin non si attiva.

PHP: 8.0 o successivo.

Valuta dello shop: real brasiliano (BRL). Iugu addebita solo in BRL. Il metodo di pagamento viene nascosto quando lo shop, o l'ordine nella pagina Pay for order, usa un'altra valuta, e per importi inferiori a R$ 1,00 (il minimo di Iugu).

Account Iugu: servono due token API dalla dashboard di Iugu, uno di tipo "Test" e uno di tipo "Live" (vedi Configurazione). Iugu usa un unico indirizzo API per entrambi: il token decide se le fatture sono di test o reali. Non occorre configurare alcun webhook in Iugu.

Chiave di licenza VibeFox: acquistata 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 fai clic su Install Now. Puoi anche caricare la cartella wcp_iugu_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Imposta la valuta dello shop su real brasiliano (BRL) in WooCommerce > Settings > General.

4. Apri le impostazioni: WooCommerce > Settings > Payments > Iugu > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

5. Inserisci la chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

6. Inserisci i token API di test e di produzione (vedi Configurazione), lascia attivo Test mode, attiva Enable / Disable e salva.

7. Effettua un ordine di prova e pagalo con una carta di test di Iugu. Quando sei pronto, disattiva Test mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Iugu. Sotto il titolo del gateway la pagina mostra TEST MODE (le fatture vengono create con il token API di test, senza addebiti reali) oppure LIVE. Avvisa quando manca il token della modalità attiva (in quel caso il metodo di pagamento viene nascosto al checkout) e quando la valuta dello shop non è BRL. Nell'elenco dei metodi di pagamento, Iugu è segnalato come da configurare finché non viene inserito il token della modalità attiva, e mostra un badge di modalità test finché la modalità test è attiva.

Generali

Enable / Disable: Enable Iugu payments attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Iugu.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Iugu. You will be redirected to complete your payment.

Credenziali API

Crea i token API in Iugu Alia (alia.iugu.com): Settings > API integration > New. Crea un token di tipo "Test" e uno di tipo "Live".

Test mode: Use the test API token (no real charges). Predefinito: on. Finché la modalità test è attiva, il checkout mostra SANDBOX — Test mode enabled. No real charges. sopra la descrizione. Le verifiche di stato e i rimborsi di un ordine usano sempre il token della modalità in cui è stata creata la sua fattura, quindi cambiare modalità non compromette gli ordini precedenti.

Test API token: il token API Iugu di tipo "Test". Viene usato finché la modalità test è attiva.

Live API token: il token API Iugu di tipo "Live" (produzione). Viene usato quando la modalità test è disattivata. Tienilo segreto.

Notifiche di pagamento

Ogni fattura chiede a Iugu di segnalare i cambi di stato all'URL delle notifiche del tuo shop, mostrato in questa sezione delle impostazioni. Ha questo aspetto: https://your-site/wc-api/webhook_wc_iugu/. Non c'è nulla da configurare in Iugu. Un trigger (gatilho) aggiuntivo a livello di account che punta allo stesso URL non causa problemi. Le notifiche non contengono dati di pagamento di cui lo shop si fida: la fattura viene sempre riletta dalle API di Iugu (stato, importo, valuta) prima che l'ordine cambi.

Il plugin reagisce agli eventi di Iugu che possono cambiare lo stato di una fattura: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action e invoices. Per ciascuno legge la fattura e applica il suo stato:

Gli altri eventi e le fatture che non appartengono a un ordine di questo shop ricevono la risposta OK e vengono ignorati. Senza notifiche, un ordine viene verificato solo quando il cliente torna allo shop dalla pagina di Iugu.

Avanzate

Debug log: Log API requests and notifications in WooCommerce > Status > Logs, origine wcp_iugu_gateway, senza token né dati dei clienti. Gli errori vengono sempre registrati. Predefinito: off.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Predefinito: off.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Iugu) e completa l'ordine. È richiesto un indirizzo e-mail di fatturazione valido. Il plugin crea una fattura Iugu per il totale dell'ordine in BRL, con scadenza a 3 giorni, e invia il cliente alla pagina della fattura Iugu. Lì il cliente paga con carta di credito, boleto o PIX, con i metodi attivati nel tuo account Iugu. Nome ed e-mail del cliente vengono passati a Iugu, insieme a CPF/CNPJ, numero civico e quartiere dai campi del checkout di "Brazilian Market on WooCommerce", quando presenti. Telefono e indirizzo vengono inviati solo nel formato accettato da Iugu (numeri di telefono brasiliani, indirizzi brasiliani con CEP a 8 cifre).

Dopo il pagamento, il cliente torna alla pagina « Ordine ricevuto » del tuo shop. L'ordine viene segnato come pagato solo dopo la conferma di Iugu: la fattura viene riletta dalle API di Iugu quando il cliente torna e quando Iugu invia una notifica. Se il cliente ha generato un codice boleto o PIX ed è tornato prima di pagare, l'ordine passa In sospeso finché Iugu non conferma il pagamento. Il timer degli ordini non pagati di WooCommerce non annulla gli ordini la cui fattura Iugu è ancora aperta.

Se la fattura è stata annullata o è scaduta e l'ordine può ancora essere pagato, il cliente arriva alla pagina Pay for order con il messaggio The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. Quando il cliente paga di nuovo, il plugin lo riporta alla stessa fattura aperta se l'importo non è cambiato. Altrimenti annulla la vecchia fattura in Iugu e ne crea una nuova, così che un ordine non possa essere pagato due volte tramite due fatture aperte. Se una fattura vecchia viene comunque pagata, il pagamento viene associato all'ordine.

Se Iugu non riesce a creare la fattura, il cliente vede un breve messaggio, per esempio Iugu could not create the invoice: con il motivo e un invito a verificare i dati di fatturazione, oppure Could not connect to Iugu. Please try again in a moment. Il motivo tecnico viene aggiunto alle note dell'ordine e al log.

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 una tantum. Non include un modulo di pagamento con carta nel sito, carte salvate, abbonamenti o addebiti ricorrenti, carnê (bollettari di pagamento), pagamenti suddivisi o impostazioni di rateizzazione: per le rate usa le impostazioni della pagina Iugu. I metodi di pagamento offerti sulla pagina Iugu non si possono scegliere nelle impostazioni del plugin: vengono offerti tutti i metodi attivi nel tuo account Iugu.

Ordini e rimborsi

Stati dell'ordine

Pending payment: la fattura è stata creata e il cliente non ha ancora pagato.

Processing or Completed: Iugu ha confermato il pagamento. WooCommerce applica lo stato consueto per un ordine pagato. La nota dell'ordine mostra l'ID della fattura Iugu e il metodo di pagamento (carta di credito, boleto o PIX). L'ID transazione è l'ID della fattura Iugu e, nella schermata dell'ordine, rimanda alla fattura in Iugu.

On hold: il cliente ha generato un boleto o un PIX ed è tornato allo shop (pagamento in attesa); il pagamento con carta è autorizzato ma non ancora acquisito (acquisiscilo in Iugu: l'ordine viene completato quando Iugu segnala la fattura come pagata); il pagamento è in analisi; la fattura è stata pagata solo parzialmente; è stato aperto uno storno (chargeback); oppure importo o valuta pagati non corrispondevano all'ordine. Un pagamento arrivato dopo l'annullamento dell'ordine lo porta anch'esso In sospeso invece di riaprirlo silenziosamente. Le note dell'ordine indicano il caso.

Failed: la fattura è scaduta senza pagamento. Il cliente può pagare di nuovo l'ordine.

Cancelled: la fattura è stata annullata in Iugu.

Refunded: la fattura che ha pagato l'ordine è stata rimborsata in Iugu.

Se viene pagata anche un'altra fattura dello stesso ordine, l'ordine non viene modificato di nuovo. Una nota ti chiede di rimborsare il pagamento duplicato in Iugu.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Iugu. Il rimborso viene inviato con il token della modalità in cui è stata creata la fattura.

Si possono rimborsare solo le fatture pagate, e non oltre l'importo ancora rimborsabile in Iugu. Un rimborso è considerato eseguito solo quando Iugu lo conferma. Se Iugu rifiuta il rimborso o non lo conferma, WooCommerce mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID della fattura e il motivo.

Un rimborso totale effettuato nella dashboard di Iugu imposta l'ordine su Rimborsato. I rimborsi parziali effettuati nella dashboard non vengono importati.

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 > Iugu. Incolla la chiave in License key e fai clic 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 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 su 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, Iugu non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. I gestori dello shop che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così da poter configurare e provare 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 confermati comunque e i rimborsi funzionano.

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

Risoluzione dei problemi

Iugu non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che sia impostato il token della modalità attiva: Test API token in modalità test, Live API token in modalità live. La valuta dello shop deve essere BRL e il totale dell'ordine almeno R$ 1,00. La pagina delle impostazioni mostra un avviso quando il token o la valuta non sono corretti.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: la notifica di Iugu non è arrivata al tuo shop o non è stata verificata. Attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_iugu_gateway. Verifica che il tuo sito sia raggiungibile da Internet all'URL delle notifiche mostrato nelle impostazioni e che il token della modalità in cui è stata creata la fattura sia ancora inserito. L'ordine viene verificato anche quando il cliente torna allo shop dopo il pagamento.

Notification answers verification failed: in quel momento la fattura non è stata letta dalle API di Iugu, per esempio per un errore di rete o un token errato. Iugu riprova la notifica.

Notification answers invalid invoice id: la notifica non aveva un ID fattura valido. Non viene modificato nulla.

L'ordine è On hold: leggi le note dell'ordine. Un boleto o un PIX è ancora non pagato, un pagamento con carta attende l'acquisizione, il pagamento è in analisi, è pagato parzialmente o contestato, l'importo pagato non corrispondeva all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine.

The customer sees "Iugu payments are not available right now": il token API manca o è errato. Controlla il token della modalità attiva.

Il rimborso non riesce: leggi il messaggio. I pagamenti boleto non possono essere rimborsati tramite Iugu, i pagamenti PIX solo per l'intero importo, e si possono rimborsare solo le fatture pagate. Se Iugu non ha confermato il rimborso, controlla la fattura in Iugu prima di riprovare.

Il blocco licenza mostra un errore: segui il messaggio del blocco. Per 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.

Gli sviluppatori possono modificare la richiesta di fattura, per esempio limitare i metodi di pagamento con payable_with, tramite il filtro wc_igu_invoice_data.

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; altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.

Iugu è un marchio del rispettivo titolare. Questo plugin non è affiliato a Iugu né approvato da Iugu.