VibeFox Iugu for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 alla 9.x.

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

Valuta: real brasiliano (BRL). Iugu addebita solo in BRL. Il metodo di pagamento viene nascosto per i carrelli in un'altra valuta e per i totali 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 a stabilire se le fatture sono di test o reali. Non è necessario configurare alcun webhook in Iugu.

Chiave di licenza VibeFox: si acquista 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 trova più tardi VibeFox Iugu 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 di configurazione e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci i token API di test e di produzione (vedi Configurazione), lascia attivo Test mode, attiva Enable / Disable e fai clic su Save.

5. Effettua un ordine di prova e pagalo nella pagina di Iugu con un pagamento di test di Iugu. Quando sei pronto, disattiva Test mode.

All'installazione il modulo crea due stati dell'ordine: Awaiting Iugu payment e Iugu 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. In ogni caso Iugu viene offerto solo per i carrelli in BRL.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Iugu Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi 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 tal caso il metodo di pagamento è nascosto al checkout) e quando la valuta predefinita del negozio non è BRL (in tal caso Iugu non viene offerto per i carrelli in altre valute).

Iugu

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. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Iugu. Obbligatorio.

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: usa il token API di test, quindi non vengono effettuati addebiti reali. Predefinito: on. Mentre 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 di Iugu di tipo "Test". Viene usato quando la modalità test è attiva.

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

I token salvati non vengono più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarlo.

Clear saved tokens: seleziona un token e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Notifiche di pagamento

Notification URL: ogni fattura indica a Iugu di segnalare i cambi di stato a questo URL del tuo negozio. Con gli URL SEO-friendly appare così: https://your-shop/module/wcp_iugu_gateway/webhook. Non c'è nulla da configurare in Iugu. Un trigger (gatilho) aggiuntivo a livello di account che punta allo stesso URL è innocuo. Le notifiche non contengono dati di pagamento di cui il negozio si fida: la fattura viene sempre riletta dalle API di Iugu (stato, importo, valuta) prima che un ordine venga creato o modificato.

Il modulo 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 di essi legge la fattura e applica il suo stato:

Gli altri eventi e le fatture non create dal tuo negozio ricevono una risposta HTTP 200 e vengono ignorati, senza alcuna richiesta a Iugu. Senza notifiche, una fattura viene controllata solo quando il cliente torna nel negozio dalla pagina di Iugu.

Avanzate

Debug log: scrive le richieste e le notifiche di Iugu in logs/wc_igu_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Token e dati dei clienti non vengono registrati. Errori e avvisi vengono sempre scritti, anche quando l'interruttore è disattivato. Predefinito: off.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il log. Ordini, riferimenti alle fatture Iugu, rimborsi e stati dell'ordine del modulo vengono sempre conservati, quindi gli ordini vecchi continuano a funzionare dopo una reinstallazione. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Iugu) e conferma. È richiesto un indirizzo e-mail valido del cliente. Il modulo crea una fattura Iugu per il totale del carrello 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 attivi nel tuo account Iugu. La fattura mostra Order # e il numero del carrello. Nome e e-mail del cliente vengono trasmessi a Iugu, insieme ad azienda e CPF/CNPJ dal campo Identification number o VAT number dell'indirizzo, quando presenti. Telefono e indirizzo vengono inviati solo nel formato accettato da Iugu (numeri di telefono brasiliani, indirizzi brasiliani con CEP a 8 cifre; il numero civico viene inviato come s/n). A questo punto l'ordine non esiste ancora.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Iugu lo conferma: la fattura viene letta dalle API di Iugu quando il cliente torna e quando Iugu invia una notifica. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Iugu has been received.

Se il cliente ha generato un codice boleto o PIX ed è tornato prima di pagare, l'ordine viene creato in Awaiting Iugu payment e la pagina di conferma mostra Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. L'ordine passa a Payment accepted quando Iugu comunica l'incasso, tramite notifica o quando il cliente riapre il link di ritorno. Se al momento del ritorno del cliente Iugu non è ancora raggiungibile, una pagina Payment confirmation mostra We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. con un pulsante Check again e un pulsante Back to checkout. Un ordine la cui fattura è stata annullata o è scaduta senza pagamento mostra Your Iugu payment was not completed. Please contact us about this order. nella pagina di conferma.

Se la fattura è stata annullata o è scaduta prima che esistesse un ordine, il cliente torna al checkout con The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. Il carrello viene conservato. Quando il cliente paga di nuovo, il modulo lo rimanda alla stessa fattura aperta se importo e modalità non sono cambiati. Altrimenti annulla la vecchia fattura in Iugu e ne crea una nuova, così un carrello non può essere pagato tramite due fatture aperte. Se una fattura precedente viene comunque pagata, il pagamento viene associato al carrello.

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

L'URL delle notifiche funziona anche quando il negozio è in modalità manutenzione e non viene bloccato dalla restrizione per paese del tuo negozio.

Il modulo 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 di Iugu. I metodi di pagamento offerti nella pagina di Iugu non possono essere scelti nelle impostazioni del modulo: vengono offerti tutti i metodi attivi nel tuo account Iugu. Un ordine in Payment error o Canceled non può essere pagato di nuovo dal negozio; il cliente effettua un nuovo ordine.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Iugu e non ha ancora pagato, oppure Iugu non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: Iugu ha confermato il pagamento. Il pagamento viene registrato con l'ID della fattura Iugu come ID transazione, e una nota mostra l'ID della fattura e il metodo di pagamento (carta di credito, boleto o PIX).

Awaiting Iugu payment: il cliente è tornato con un boleto o un PIX emesso. L'ordine passa a Payment accepted quando Iugu comunica il pagamento.

Iugu payment on hold: il pagamento con carta è autorizzato ma non ancora catturato (catturalo in Iugu, e l'ordine viene completato quando Iugu comunica che la fattura è pagata), il pagamento è in analisi, la fattura è stata pagata solo parzialmente, è stato aperto uno chargeback, Iugu ha comunicato un importo o una valuta diversi da quelli del carrello (per esempio se il carrello è stato modificato dopo la creazione della fattura), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. Le note lo spiegano. Controlla l'ordine ed evadilo oppure rimborsa il pagamento.

Payment error: la fattura di un ordine in attesa è scaduta senza pagamento. Se Iugu comunica più tardi che la fattura è pagata, l'ordine passa a Payment accepted.

Canceled: la fattura di un ordine in attesa è stata annullata in Iugu.

Refunded: il pagamento è stato rimborsato integralmente tramite il modulo o nella dashboard di Iugu.

Se un'altra fattura dello stesso carrello viene pagata a sua volta, l'ordine non cambia. Una nota ti chiede di rimborsare in Iugu il pagamento duplicato.

Blocco pagamento Iugu

La pagina dell'ordine mostra un blocco Iugu payment con l'ID della fattura Iugu (collegato alla fattura in Iugu), il metodo di pagamento, lo stato, l'importo incassato da Iugu e l'importo rimborsato, un badge Test mode per le fatture di test, lo storico dei rimborsi e le Iugu notes dell'ordine.

Rimborsi

Nel blocco Iugu payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Iugu. Conferma la domanda Refund this amount through Iugu? This cannot be undone. Ti serve il permesso di modificare gli ordini. Il rimborso viene inviato con il token della modalità in cui è stata creata la fattura, quindi quel token deve essere impostato.

I rimborsi si basano sull'importo che Iugu ha effettivamente incassato per la fattura, quindi dopo una differenza di importo puoi rimborsare fino a quanto ha pagato il cliente, non fino al totale dell'ordine. Possono essere rimborsate solo le fatture pagate, e non più dell'importo ancora rimborsabile in Iugu. Un rimborso è considerato eseguito solo quando Iugu lo conferma. Se Iugu rifiuta il rimborso o non lo conferma, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'ID della fattura e il motivo. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili quando Iugu ha comunicato che la fattura è pagata.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Iugu.

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

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Iugu Gateway è il primo blocco di Modules > Module Manager > VibeFox Iugu Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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. Più in basso ci sono la riga Product: presta-payment-iugu 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, 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: quello del negozio principale, anche in una configurazione multinegozio. Rimuovere la chiave dal negozio 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. Lo storefront di PrestaShop non sa che hai effettuato l'accesso 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 funzionano.

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

Iugu non appare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che il token della modalità attiva sia impostato: Test API token in modalità test, Live API token in modalità produzione. La valuta del carrello deve essere BRL e il totale almeno R$ 1,00. In Payment > Preferences verifica che il modulo sia consentito per la valuta BRL, il paese del cliente e il gruppo del cliente. La pagina delle impostazioni mostra un avviso se il token o la valuta sono errati.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la notifica di Iugu non è arrivata al negozio o non è stato possibile verificarla. Attiva Debug log e controlla il campo Log nella pagina del modulo. Verifica che il negozio sia raggiungibile da internet all'indirizzo della Notification URL e che il token della modalità in cui è stata creata la fattura sia ancora inserito. La fattura viene comunque controllata quando il cliente torna nel negozio dopo il pagamento.

Notification answers verification failed: in quel momento la fattura non è stata letta dalle API di Iugu, per esempio a causa di un errore di rete, di un token errato o dell'assenza del token della modalità della fattura. Iugu ripete la notifica.

Notification answers busy: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Iugu ripete la notifica. Il log mostra il motivo.

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

Ordine in Iugu payment on hold: leggi le Iugu notes nel blocco dell'ordine. Un pagamento con carta attende la cattura, il pagamento è in analisi, pagato parzialmente o contestato, l'importo pagato non corrisponde al carrello, oppure il pagamento è arrivato dopo l'annullamento dell'ordine.

Il cliente vede «Iugu payments are not available right now»: il token API manca o è errato. Controlla il token della modalità attiva.

Il cliente vede «This order already has an Iugu payment that the store has to review»: una fattura precedente del carrello è autorizzata, in analisi o pagata parzialmente, ma non è stato possibile creare alcun ordine. Controlla la fattura in Iugu e il log.

Il rimborso non riesce: leggi il messaggio nel blocco. I pagamenti boleto non possono essere rimborsati tramite Iugu, i pagamenti PIX possono essere rimborsati solo integralmente, e solo le fatture pagate possono essere rimborsate. Se il messaggio dice che il pagamento è stato effettuato in modalità test o produzione e non è configurato alcun token, inserisci il token di quella modalità. Se Iugu non ha confermato il rimborso, controlla la fattura in Iugu prima di riprovare.

Gli sviluppatori possono modificare la richiesta di fattura, per esempio limitando i metodi di pagamento con payable_with, nell'hook actionWcpIuguInvoiceData.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Iugu 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 e il log. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I riferimenti alle fatture Iugu e i rimborsi, insieme agli stati dell'ordine Awaiting Iugu payment e Iugu payment on hold, vengono sempre conservati, così gli ordini pagati in precedenza possono ancora essere rimborsati e le notifiche tardive continuano a essere associate dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.

Iugu è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Iugu né approvato da Iugu.