VibeFox Vindi for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

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

PHP: 8.0 o successivo.

Valuta del negozio: real brasiliano (BRL). Vindi addebita solo in BRL, quindi il metodo di pagamento viene nascosto per qualsiasi altra valuta.

Account Vindi: ti serve la chiave API del tuo account Vindi. Vindi sandbox è 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. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin, fai clic su Install Now e poi su Activate. In alternativa puoi caricare la cartella wcp_vindi_gateway in /wp-content/plugins/ via FTP.

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

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

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 salva. Prova un pagamento in modalità sandbox, poi deseleziona Sandbox mode per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Vindi. 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. Nell'elenco dei metodi di pagamento, Vindi è segnalato come da configurare finché la modalità attuale non ha una chiave API. Al salvataggio le chiavi vengono ripulite e, 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.

Generali

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

Title: il nome del metodo di pagamento mostrato al checkout. Predefinito: Vindi.

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 il live e su sandbox-app.vindi.com.br per la sandbox. Ogni ordine ricorda dove è stata creata la sua fattura, quindi verifiche, annullamenti e rimborsi usano sempre quell'ambiente.

Sandbox mode: Create new payments in the Vindi sandbox usa sandbox-app.vindi.com.br con la chiave API sandbox. Al checkout i clienti vedono la nota TEST MODE: Vindi sandbox: no real charges. Predefinito: on. Deseleziona l'opzione per accettare pagamenti reali.

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

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

Metodi di pagamento

Offered methods: i metodi che il cliente può scegliere. Predefinito: credit card. I metodi devono essere attivati anche nel tuo account Vindi.

Notifiche di pagamento (webhook)

Il webhook comunica al tuo negozio che una fattura è stata pagata, annullata o rimborsata. Questa sezione delle impostazioni mostra l'URL del webhook. Ha questo aspetto: https://your-site/wc-api/webhook_wc_vindi/?token=... e contiene un token segreto creato dal plugin. Copialo esattamente come lo mostrano le impostazioni. In Vindi vai su Settings > Webhooks, sia nell'account live sia in quello sandbox, aggiungi questo URL e seleziona questi eventi:

Le richieste con token mancante o errato vengono rifiutate. Ogni notifica fa solo rileggere la fattura tramite l'API di Vindi prima che un ordine cambi. Senza il webhook, i pagamenti con carta, boleto e PIX vengono confermati solo quando il cliente apre la pagina di conferma dell'ordine.

Avanzate

Debug log: Log API calls and notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_vindi_gateway. Errori e avvisi vengono sempre registrati, anche quando l'opzione è disattivata. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: off.

Delete data on uninstall: Remove the settings, webhook token and logs when the plugin is deleted. Predefinito: off.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Vindi). Quando viene offerto più di un metodo, il riquadro di pagamento mostra Pay with e una scelta tra carta di credito, boleto, PIX o BolePix. Quando è offerto boleto, PIX o BolePix, il riquadro mostra anche un campo CPF or CNPJ. È obbligatorio quando sono offerti solo questi metodi; altrimenti mostra Required for boleto and PIX. Il numero viene verificato con le sue cifre di controllo. Nel checkout classico il campo non viene mostrato quando è attivo Brazilian Market on WooCommerce, perché quel plugin chiede già il CPF / CNPJ. In quel caso vengono usati il suo CPF / CNPJ, il numero civico e il quartiere. 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 l'ordine viene effettuato, il plugin crea un cliente Vindi per questo ordine a partire dai dati di fatturazione e una fattura Vindi per il totale dell'ordine, in un'unica rata.

Credit card: il cliente viene inviato alla pagina di fatturazione di Vindi e paga lì. Vindi non ha un URL di ritorno per le fatture, quindi il cliente non torna automaticamente nel negozio. L'ordine viene confermato dal webhook oppure quando il cliente apre la pagina di conferma dell'ordine. Finché il pagamento non è completato, quella pagina e l'ordine in My account mostrano Your payment has not been completed yet. e un pulsante Pay at Vindi.

Boleto, PIX e BolePix: la fattura viene emessa subito, l'ordine viene impostato su In attesa e il cliente arriva alla pagina di conferma dell'ordine. Lì, e in My account > Orders, una sezione Payment mostra il QR code PIX, il codice PIX da copiare e incollare con un pulsante Copy code e la sua data di scadenza, e un pulsante Open boleto. L'e-mail del cliente per l'ordine in attesa e l'e-mail della fattura contengono il codice PIX e il link del boleto.

L'ordine viene segnato come pagato solo dopo la conferma di Vindi: il plugin legge la fattura dall'API di Vindi e verifica che appartenga all'ordine (codice dell'ordine e cliente Vindi) e che l'importo pagato corrisponda al totale dell'ordine.

Un cliente può pagare di nuovo un ordine non pagato dalla pagina Pay for order. Se metodo, importo e ambiente sono gli stessi, la fattura Vindi in sospeso viene riutilizzata. Altrimenti viene annullata su Vindi prima di crearne una nuova, così il cliente non può pagare due volte lo stesso ordine. Se la fattura precedente è stata pagata nel frattempo, l'ordine viene segnato come pagato e non viene creata alcuna nuova fattura.

Se Vindi non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per esempio di controllare il CPF / CNPJ, l'indirizzo di fatturazione, l'e-mail o il telefono, oppure che Vindi è temporaneamente non disponibile. Se nello stesso momento lo stesso ordine è in elaborazione da un'altra richiesta, al cliente viene chiesto di attendere un momento e riprovare.

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

Pending payment: è stato avviato un pagamento con carta e Vindi non lo ha ancora confermato.

On hold: un pagamento boleto, PIX o BolePix è in attesa (nota Awaiting ... payment at Vindi.), oppure la fattura Vindi è in verifica.

Processing or Completed: il pagamento è stato confermato. Lo stato viene impostato nel modo standard di WooCommerce: In elaborazione, oppure Completato per gli ordini con soli prodotti virtuali scaricabili. La nota dell'ordine mostra la fattura Vindi, l'importo e l'ambiente. L'ID della transazione è l'ID della fattura Vindi.

On hold after payment: la fattura pagata non corrisponde all'ordine (importo, codice dell'ordine o cliente Vindi), oppure la fattura è stata pagata dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega. Controlla l'ordine e le scorte, poi completa l'ordine oppure rimborsa il pagamento.

Failed: Vindi ha rifiutato il tentativo di pagamento. La nota mostra il motivo comunicato dall'acquirente, se disponibile. Il cliente può comunque pagare la stessa fattura, e un pagamento successivo completa l'ordine.

Cancelled: la fattura è stata annullata su Vindi, oppure l'ordine è stato annullato da te, dal cliente o dal timeout di prenotazione delle scorte di WooCommerce. Quando un ordine viene annullato 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. Prima che il timeout di prenotazione delle scorte annulli un ordine, la fattura viene verificata: se nel frattempo è stata pagata, l'ordine viene invece segnato come pagato.

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

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Vindi. Sono supportati rimborsi totali e parziali dei pagamenti con carta e PIX. Un rimborso totale annulla anche la fattura su Vindi. Il rimborso viene inviato nell'ambiente del pagamento (live o sandbox), quindi deve essere impostata la chiave API di quell'ambiente. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'addebito Vindi e lo stato. Se Vindi o l'acquirente rifiutano il rimborso, WooCommerce mostra l'errore e non viene registrato alcun rimborso.

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

I rimborsi effettuati dalla dashboard di Vindi arrivano tramite il webhook charge_refunded e vengono aggiunti alle note dell'ordine. Non vengono registrati automaticamente come rimborsi di WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza usare Refund via Vindi.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Vindi. 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 vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il suo posto per il dominio. Liberalo 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. I gestori del negozio con l'accesso effettuato continuano a vedere il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi 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 coinvolti: i pagamenti già avviati vengono comunque confermati 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

Vindi non compare al checkout: controlla che la licenza sia attiva, che Enable / Disable sia attivo, che la valuta del negozio 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à live. La pagina delle impostazioni mostra un avviso quando la chiave manca o la valuta non è BRL.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment o On hold: il webhook non funziona. In Vindi controlla che il webhook esista nell'account che usi (live o sandbox), che il suo URL sia esattamente quello mostrato nelle impostazioni, token compreso, e che siano selezionati i quattro eventi. L'ordine viene confermato anche quando il cliente apre la pagina di conferma dell'ordine.

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 oppure Order busy, retry later: la fattura non è stata letta tramite l'API di Vindi (per esempio perché la chiave API di quell'ambiente è stata rimossa), oppure l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Vindi invierà di nuovo la notifica.

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

Il cliente vede un errore quando effettua l'ordine: apri le note dell'ordine o il log in WooCommerce > Status > Logs, origine wcp_vindi_gateway. Gli errori vengono registrati anche quando Debug log è disattivato. Per il boleto, l'indirizzo di fatturazione deve includere via, CAP, città e provincia.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo pagato, il codice dell'ordine o il cliente Vindi non corrispondevano all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Completa l'ordine oppure rimborsa il pagamento.

Vecchi ordini sandbox dopo il passaggio a live: ogni ordine 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.

Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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.

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, il token del webhook, gli altri dati salvati dal plugin e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le loro note di pagamento, gli ID delle transazioni e i dati Vindi.

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