VibeFox Flow for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 8.0 o successivo, installato e attivo.
PHP: 8.0 o successivo.
Valuta del negozio: peso cileno (CLP) o dollaro statunitense (USD). Per altre valute il metodo di pagamento viene nascosto al checkout. Nei negozi in CLP imposta WooCommerce > Settings > General > Number of decimals su 0, perché Flow addebita pesos interi.
Account Flow: servono API Key e Secret Key del tuo account Flow, in Flow sotto Mis datos, Datos técnicos. Per i test, crea un account sandbox separato su sandbox.flow.cl e usa le sue chiavi. Le chiavi sandbox e live sono diverse. Non occorre configurare nulla nell'account Flow.
Sito web pubblico: gli URL di conferma, ritorno e rimborso del tuo negozio devono essere raggiungibili da Internet, senza modalità manutenzione, protezione con password o firewall che blocchi Flow.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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_flow_gateway in /wp-content/plugins/ tramite FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Flow.cl > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina dei plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco della licenza in cima alla pagina e fai clic su Activate.
5. Inserisci API Key e Secret Key sandbox, attiva Enable / Disable, salva ed effettua un ordine di prova.
6. Per accettare pagamenti reali, inserisci le chiavi live e deseleziona Sandbox mode.
Configurazione
Tutte le impostazioni sono su una pagina: WooCommerce > Settings > Payments > Flow.cl. Sopra i campi, la pagina ti avvisa quando le chiavi della modalità attuale sono vuote (Flow viene quindi nascosto al checkout), quando la valuta del negozio non è supportata e quando un negozio in CLP usa decimali (Flow addebita pesos interi, quindi imposta Number of decimals su 0 affinché prezzi, totali e rimborsi corrispondano esattamente). In modalità sandbox mostra Sandbox mode — i pagamenti vanno a sandbox.flow.cl, senza addebiti reali. Nell'elenco dei metodi di pagamento Flow risulta da configurare finché la modalità attuale non ha le chiavi e mostra un badge di modalità test in sandbox.
Generale
Enable / Disable: Enable Flow.cl payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Flow.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.
Credenziali API Flow
Copia API Key e Secret Key dal tuo account Flow (Mis datos, Datos técnicos): chiavi live su www.flow.cl, chiavi sandbox su sandbox.flow.cl (un account sandbox separato).
Sandbox mode: Use the Flow sandbox (sandbox.flow.cl) and the sandbox keys. In modalità sandbox non viene addebitato denaro reale. Predefinito: attivato. Disattivala e inserisci le chiavi live per accettare pagamenti reali. I rimborsi usano sempre l'ambiente in cui l'ordine è stato pagato.
Sandbox API Key: l'API Key del tuo account sandbox.flow.cl.
Sandbox Secret Key: la Secret Key del tuo account sandbox.flow.cl. Viene usata per firmare ogni richiesta.
Live API Key: l'API Key del tuo account www.flow.cl.
Live Secret Key: la Secret Key del tuo account www.flow.cl. Mantienila riservata.
Notifiche
Il plugin invia tre URL a Flow con ogni pagamento e rimborso, quindi non occorre configurare nulla nell'account Flow. La sezione li elenca:
La conferma contiene solo un token di pagamento. Il plugin chiede quindi a Flow lo stato del pagamento con una richiesta firmata nell'ambiente in cui il pagamento è stato creato e applica solo la risposta di Flow. Un pagamento che questo negozio non ha creato per l'ordine viene rifiutato. Senza conferma, l'ordine viene aggiornato quando il cliente torna da Flow.
Avanzate
Debug log: Log API calls and notifications in WooCommerce > Status > Logs, origine wcp_flow_gateway, senza chiavi o dati dei clienti. Gli errori vengono sempre registrati. Predefinito: disattivato.
Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Flow data saved on orders is kept). Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Flow) ed effettua l'ordine. In modalità sandbox il checkout mostra SANDBOX MODE — i pagamenti vanno alla sandbox Flow. Nessun addebito reale. È richiesta un'e-mail di fatturazione valida. Il plugin crea un pagamento Flow per il totale dell'ordine nella sua valuta, con oggetto Order # seguito dal numero dell'ordine e dal nome del sito, e invia il cliente alla pagina di pagamento Flow. Qui il cliente sceglie un metodo di pagamento abilitato nel tuo account Flow.
Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Flow: tramite la conferma o una richiesta di stato firmata al ritorno del cliente. Un ordine pagato, o un buono per contanti in attesa di pagamento, porta alla pagina di ordine ricevuto.
Se il pagamento è stato rifiutato, il cliente torna alla pagina Pay for order (o al checkout) con Your Flow payment was rejected. Please try again or choose another payment method. Se il cliente ha lasciato la pagina Flow senza pagare, il messaggio è The Flow payment was not completed. You can try again or choose another payment method. Se non è stato possibile verificare il risultato, il messaggio è We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. Ogni nuovo tentativo crea un nuovo pagamento Flow legato all'ordine.
Se Flow non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per esempio Could not connect to Flow. Please try again in a moment. I dettagli si trovano nel registro.
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). I testi rivolti ai clienti sono tradotti in spagnolo (Cile e Spagna).
Il plugin accetta solo pagamenti singoli. Non prevede carte salvate, abbonamenti, addebiti ricorrenti o link di pagamento e non preseleziona un metodo di pagamento Flow. Flow non può annullare un link di pagamento già creato: se un cliente paga un vecchio link dopo averne pagato uno più recente, l'ordine riceve una nota che ti chiede di rimborsare il duplicato in Flow.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Flow e non ha ancora pagato. La nota dell'ordine mostra l'importo e il numero d'ordine Flow del tentativo.
On hold, awaiting coupon payment: il cliente ha generato un buono di pagamento Servipag o Multicaja. L'ordine cambia quando Flow conferma il pagamento.
Processing: Flow ha segnalato che il pagamento è stato effettuato e importo e valuta corrispondono (gli ordini con soli prodotti virtuali scaricabili diventano Completato, il comportamento predefinito di WooCommerce). La nota dell'ordine mostra l'importo e il numero d'ordine Flow. L'ID della transazione dell'ordine è il numero d'ordine Flow.
On hold, amount/currency mismatch: Flow ha segnalato un importo o una valuta diversi da quelli dell'ordine. L'ordine non è stato segnato come pagato; verificalo manualmente.
On hold, payment for a cancelled order: è arrivato un pagamento per un ordine che era stato annullato senza essere pagato. Controlla l'ordine e spediscilo oppure rimborsa il pagamento in Flow.
Failed: Flow ha rifiutato l'ultimo tentativo di pagamento di un ordine non pagato. Il cliente può riprovare.
Cancelled: l'ultimo tentativo di pagamento è stato annullato in Flow.
Se arriva un altro pagamento per un ordine già pagato, l'ordine non cambia. Una nota ti chiede di rimborsare il duplicato nel tuo account Flow. Un ordine pagato e poi annullato o rimborsato non viene mai riaperto.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Flow. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato all'ambiente in cui l'ordine è stato pagato (sandbox o live), quindi devono essere impostate le chiavi di quell'ambiente e l'ordine deve avere un'e-mail di fatturazione. Flow invia un'e-mail al cliente per completare il rimborso. Se Flow rifiuta il rimborso, WooCommerce mostra l'errore e non registra alcun rimborso. Una richiesta riuscita viene aggiunta alle note dell'ordine con il numero e lo stato del rimborso Flow.
Le successive variazioni di stato del rimborso comunicate da Flow vengono aggiunte alle note dell'ordine. Se Flow rifiuta o annulla un rimborso in seguito, la nota indica che il denaro non è stato restituito al cliente; la registrazione del rimborso WooCommerce viene mantenuta, quindi gestiscila manualmente. I rimborsi creati nella dashboard Flow non vengono importati in WooCommerce.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza è in cima a WooCommerce > Settings > Payments > Flow.cl. 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 ricontrollare 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 dominio. Rimuovere la chiave da un sito non libera il posto occupato dal suo dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, Flow non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio connessi continuano a vedere il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina dei plugin e nelle pagine WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono ancora confermati e i rimborsi funzionano.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
Flow non compare al checkout: verifica che la licenza sia attiva, Enable / Disable sia abilitato, le chiavi della modalità attuale siano inserite (chiavi sandbox in modalità sandbox, chiavi live in modalità live) e la valuta del negozio sia CLP o USD. Nella pagina Pay for order viene verificata la valuta dell'ordine.
Il pagamento è riuscito, ma l'ordine resta Pending payment: la conferma Flow non raggiunge il tuo negozio e il cliente non è tornato. Verifica che l'URL di conferma mostrato nelle impostazioni sia accessibile da Internet e non sia bloccato dalla modalità manutenzione, da una password o da un firewall. Attiva Debug log e consulta WooCommerce > Status > Logs, origine wcp_flow_gateway.
La conferma risponde Payment does not belong to the order o Unknown order: il pagamento non è stato creato da questo negozio per questo ordine oppure è stato creato in un altro ambiente. L'ordine non cambia.
La conferma risponde Gateway not configured: le chiavi dell'ambiente del pagamento sono vuote. Inseriscile di nuovo.
La conferma risponde Flow API unavailable: la richiesta di stato a Flow non è riuscita. Flow riprova la conferma.
Il cliente vede Flow payments are not available at the moment: le chiavi mancano o Flow le ha rifiutate. Controlla API Key e Secret Key della modalità attuale.
Il cliente vede A valid billing email is required for Flow payments: Flow ha bisogno dell'e-mail del cliente.
Il cliente ha pagato, ma l'ordine è On hold: leggi la nota dell'ordine. Il cliente ha generato un buono per contanti non ancora pagato oppure l'importo o la valuta comunicati da Flow non corrispondono all'ordine. I totali CLP con decimali vengono arrotondati a pesos interi, quindi imposta Number of decimals su 0.
Il rimborso non riesce con un messaggio sulle chiavi sandbox o live: l'ordine è stato pagato in quell'ambiente e le sue chiavi sono vuote. Inseriscile e riprova.
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.
Per gli sviluppatori, il readme elenca il filtro wc_flw_supported_currencies (valute per cui viene offerto il gateway).
Disinstallazione
La disattivazione del plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti rimangono per una successiva reinstallazione. I dati Flow salvati negli ordini vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID delle transazioni.
Flow è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Flow né approvato da Flow.