VibeFox Vindi 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 del negozio: real brasiliano (BRL). Vindi addebita solo in BRL, quindi il metodo di pagamento è nascosto per i carrelli in qualsiasi altra valuta.

Account Vindi: ti serve la chiave API del tuo account Vindi. La sandbox di Vindi è un account di test separato con una propria chiave. Anche boleto, PIX e BolePix devono essere attivati nel tuo account Vindi se vuoi offrirli.

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 VibeFox Vindi Gateway più tardi 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. Incolla la Sandbox API key e, quando sei pronto, la Live API key. Scegli i Offered methods.

5. Copia l'URL del webhook dalle impostazioni in Vindi (vedi Configurazione).

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

All'installazione il modulo crea due stati dell'ordine: Awaiting Vindi payment e Vindi 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; il modulo deve essere consentito per BRL in quella sezione.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Vindi Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando la valuta del negozio non è BRL o quando la chiave API della modalità attuale è vuota. In entrambi i casi il metodo di pagamento non viene mostrato al checkout. Al salvataggio, le chiavi vengono ripulite dagli spazi iniziali e finali. Se non è selezionato alcun metodo di pagamento, viene selezionata la carta di credito e la pagina mostra Choose at least one payment method — credit card was selected. Un Title vuoto non viene salvato: la pagina mostra Enter a title for the payment method.

Vindi

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

Title: il nome del metodo di pagamento mostrato al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Vindi. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay by credit card on the secure Vindi page, or by boleto / PIX.

Chiavi API

Crea le chiavi nella dashboard di Vindi in Settings > API keys: su app.vindi.com.br per la produzione e su sandbox-app.vindi.com.br per la sandbox. Produzione e sandbox hanno host e chiavi separati. Ogni pagamento ricorda dove è stata creata la sua fattura, quindi verifiche, annullamenti e rimborsi usano sempre quell'ambiente.

Sandbox mode: crea nuovi pagamenti nella sandbox di Vindi, usando sandbox-app.vindi.com.br con la chiave API sandbox. I clienti vedono al checkout una nota TEST MODE: Vindi sandbox: no real charges. Predefinito: attivo. Disattivalo per accettare pagamenti reali.

Live API key: la chiave privata dell'account Vindi di produzione. Viene inviata solo all'API di Vindi.

Sandbox API key: la chiave privata dell'account sandbox di Vindi.

Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un valore nuovo solo se vuoi cambiarlo.

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

Metodi di pagamento

Offered methods: i metodi che i clienti possono scegliere. Predefinito: carta di credito. I metodi devono essere attivati anche nel tuo account Vindi.

Boleto, PIX e BolePix richiedono il CPF o il CNPJ del cliente, che viene richiesto al checkout.

Notifiche di pagamento (webhook)

Il webhook comunica al tuo negozio che una fattura è stata pagata, annullata, rifiutata o rimborsata. Il campo Webhook URL di questa sezione mostra l'URL. Con gli URL parlanti appare così: https://your-shop/module/wcp_vindi_gateway/webhook?token=... e contiene un token segreto creato dal modulo. Copialo esattamente come lo mostrano le impostazioni. In Vindi vai su Settings > Webhooks, sia nell'account di produzione sia in quello sandbox, aggiungi questo URL e seleziona questi eventi:

Vindi non firma le sue notifiche, quindi le richieste con un token mancante o errato vengono rifiutate, e ogni notifica fa solo rileggere la fattura tramite l'API di Vindi prima che un ordine cambi. Senza il webhook, un pagamento con carta viene rilevato solo quando il cliente effettua di nuovo l'ordine con lo stesso carrello (la fattura pagata viene trovata e l'ordine creato), e un pagamento boleto o PIX quando il cliente riapre la pagina di conferma dell'ordine.

Avanzate

Debug log: registra le chiamate API e le notifiche in logs/wc_vdi_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando è disattivato. Chiavi, token del webhook e dati 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 impostazioni, il token del webhook e i registri. Gli ordini e i riferimenti alle fatture Vindi degli ordini vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Vindi). Quando viene offerto più di un metodo, il box di pagamento mostra Pay with e una scelta tra carta di credito, boleto, PIX o BolePix. Quando sono offerti boleto, PIX o BolePix, il box contiene anche un campo CPF or CNPJ. È obbligatorio quando la carta di credito non è offerta; altrimenti mostra Required for boleto and PIX. Il campo viene compilato con il Identification number o con il numero di partita IVA (VAT) dell'indirizzo di fatturazione, quando contengono un CPF o un CNPJ valido. Il numero viene verificato con le sue cifre di controllo. Se manca qualcosa, il cliente vede Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. oppure Please enter your CPF or CNPJ — it is required for boleto and PIX.

Quando il cliente conferma l'ordine, il modulo crea per questo carrello un cliente Vindi a partire dall'indirizzo di fatturazione e una fattura Vindi per il totale del carrello, in un'unica rata. In Vindi la fattura si chiama Order # seguito dal numero del carrello.

Carta di credito: il cliente viene inviato alla pagina di fatturazione di Vindi e paga lì. A questo punto non esiste ancora alcun ordine. Vindi non ha un URL di ritorno per le fatture, quindi il cliente non viene riportato automaticamente nel negozio. L'ordine viene creato quando Vindi conferma il pagamento tramite il webhook. Se il cliente effettua di nuovo l'ordine con lo stesso carrello, la fattura in sospeso viene riproposta oppure, se è già pagata, l'ordine viene creato subito.

Boleto, PIX e BolePix: la fattura viene emessa subito, l'ordine viene creato con lo stato Awaiting Vindi payment e il cliente arriva nella pagina di conferma dell'ordine. Lì, e nei dettagli dell'ordine nel suo account, una sezione Payment mostra il QR code PIX, il codice PIX da copiare e incollare con un pulsante Copy code e la relativa data di scadenza, e un pulsante Open boleto. L'e-mail di conferma dell'ordine contiene il codice PIX e il link del boleto. Se Vindi non restituisce i dati del boleto o del PIX, la fattura viene annullata e il cliente vede un errore.

L'ordine viene segnato come pagato solo dopo la conferma di Vindi: il modulo legge la fattura dall'API di Vindi e verifica la valuta, che la fattura appartenga al carrello (codice del carrello e cliente Vindi) e che l'importo pagato corrisponda al totale dell'ordine. La pagina di conferma dell'ordine verifica di nuovo tramite API un ordine in attesa, al massimo ogni 15 secondi. Quando il pagamento è stato ricevuto, mostra Your payment with Vindi has been received. Mentre la fattura è in revisione presso Vindi, mostra We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. Per un ordine annullato, mostra This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.

Un nuovo tentativo di pagamento per lo stesso carrello riutilizza la fattura Vindi in sospeso se metodo, importo e ambiente sono gli stessi. Altrimenti la fattura precedente viene annullata in Vindi prima che ne venga creata una nuova, così il cliente non può pagare due volte lo stesso carrello. Se la fattura precedente nel frattempo è stata pagata, l'ordine viene creato e non viene emessa alcuna nuova fattura.

Se Vindi non riesce ad avviare il pagamento, il cliente resta al checkout con un messaggio breve, per esempio per controllare il CPF / CNPJ, l'indirizzo di fatturazione (via, CAP, città e stato sono obbligatori per il boleto), l'e-mail o il numero di telefono, oppure per indicare che Vindi non è disponibile temporaneamente. Il motivo tecnico viene scritto nel registro.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non viene bloccato dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti singoli in un'unica rata. Non prevede abbonamenti o addebiti ricorrenti, carte salvate, rateizzazioni né un modulo carta sul tuo sito: la carta viene sempre inserita nella pagina di Vindi.

Ordini e rimborsi

Stati dell'ordine

No order yet: è stato avviato un pagamento con carta e Vindi non l'ha ancora confermato. Esiste solo il carrello.

Awaiting Vindi payment: un pagamento con boleto, PIX o BolePix è in attesa (nota Awaiting ... payment at Vindi.). L'ordine passa a Payment accepted quando Vindi segnala la fattura come pagata.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID della fattura Vindi come ID transazione, e una nota mostra la fattura Vindi, l'importo e l'ambiente.

Vindi payment on hold: la fattura Vindi è in revisione, la fattura pagata non corrisponde all'ordine (valuta, importo, codice del carrello o cliente Vindi), oppure la fattura è stata pagata dopo che l'ordine era stato annullato. La nota lo spiega, e sull'ordine viene registrato un importo pagato. Controlla l'ordine e le scorte, poi completa l'ordine o rimborsa il pagamento.

Payment error: Vindi ha rifiutato il tentativo di pagamento di un ordine in attesa. La nota mostra il motivo comunicato dall'acquirente, se disponibile. Il cliente può ancora pagare la stessa fattura, e un pagamento successivo porta l'ordine su Payment accepted.

Canceled: la fattura di un ordine in attesa è stata annullata in Vindi. Quando annulli un ordine nel negozio, anche la sua fattura Vindi in sospeso viene annullata, quindi non può più essere pagata. Se non è possibile, una nota ti chiede di annullare la fattura nella dashboard di Vindi.

Refunded: il pagamento è stato rimborsato interamente tramite il modulo.

Se per un ordine già pagato viene pagata una seconda fattura, l'ordine non cambia. Una nota ti chiede di rimborsare un pagamento in Vindi.

Blocco pagamento Vindi

La pagina dell'ordine mostra un blocco Vindi payment con la fattura e l'addebito Vindi, l'ambiente (con un badge Sandbox per i pagamenti sandbox), il metodo di pagamento, lo stato, l'importo pagato e rimborsato, lo storico dei rimborsi, tutte le Bills of this cart e le Vindi notes dell'ordine.

Rimborsi

Nel blocco Vindi payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Vindi. Conferma la domanda Refund this amount through Vindi? This cannot be undone. Sono supportati rimborsi totali e parziali dei pagamenti con carta e PIX. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine dei moduli. I rimborsi sono limitati all'importo effettivamente addebitato da Vindi, quindi dopo una discrepanza puoi rimborsare fino a quanto ha pagato il cliente, non il totale dell'ordine. Il rimborso viene inviato nell'ambiente del pagamento (produzione o sandbox), quindi la chiave API di quell'ambiente deve essere impostata. Un rimborso totale annulla anche la fattura in Vindi e imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'addebito Vindi e lo stato. Se Vindi o l'acquirente rifiutano il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. I rimborsi sono disponibili quando Vindi ha segnalato la fattura come pagata.

Vindi non può rimborsare i pagamenti boleto. Il blocco mostra Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Vindi. I rimborsi effettuati nella dashboard di Vindi arrivano tramite il webhook charge_refunded e vengono aggiunti alle note. Lo stato dell'ordine non viene modificato automaticamente; registrali in PrestaShop con un rimborso manuale se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Vindi Gateway è il primo blocco di Modules > Module Manager > VibeFox Vindi Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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 si trovano la riga Product: presta-payment-vindi 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, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on con 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 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, Vindi 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: le fatture già create vengono comunque confermate dal webhook di Vindi, e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Vindi non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che la valuta del carrello sia BRL, che almeno un metodo sia selezionato in Offered methods e che la modalità attuale abbia una chiave API: Sandbox API key in modalità sandbox, Live API key in modalità produzione. La pagina delle impostazioni mostra un avviso quando la chiave manca o la valuta non è BRL. In Payment > Preferences verifica che il modulo sia consentito per BRL, per il paese del cliente e per il suo gruppo di clienti.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine oppure l'ordine resta su Awaiting Vindi payment: il webhook non funziona. In Vindi verifica che il webhook esista nell'account che usi (produzione o sandbox), che il suo URL sia esattamente quello mostrato nelle impostazioni, token compreso, e che siano selezionati tutti e quattro gli eventi.

Il webhook risponde Forbidden: il token nell'URL manca o è errato. Copia di nuovo l'URL dalle impostazioni.

Il webhook risponde Verification failed, retry later: la fattura non è stata letta tramite l'API di Vindi (per esempio è stata rimossa la chiave API di quell'ambiente), il carrello era in aggiornamento da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Vindi invia di nuovo la notifica. Il registro mostra il motivo.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste da Vindi.

Il cliente vede This payment method is temporarily unavailable: Vindi ha rifiutato la chiave API. Verifica la chiave della modalità attuale.

Il cliente vede un errore quando effettua l'ordine: controlla il campo Log nella pagina del modulo. Gli errori vengono registrati anche quando Debug log è disattivato. Per il boleto, l'indirizzo di fatturazione deve avere via, CAP, città e stato.

L'ordine è Vindi payment on hold: leggi le note nel blocco Vindi payment (vedi Stati dell'ordine), poi completa l'ordine o rimborsa il pagamento.

Vecchi ordini sandbox dopo il passaggio a produzione: ogni pagamento mantiene l'ambiente della sua fattura. Verifiche, annullamenti e rimborsi degli ordini sandbox continuano a usare la chiave sandbox finché resta nelle impostazioni.

Il rimborso non riesce: leggi il messaggio. I pagamenti boleto non possono essere rimborsati tramite Vindi, e la chiave API dell'ambiente del pagamento deve essere impostata.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Vindi 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, il token del webhook e i registri. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le fatture e i rimborsi Vindi degli ordini e gli stati dell'ordine Awaiting Vindi payment e Vindi payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

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