VibeFox Flow for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP precedenti.
Valuta: peso cileno (CLP) o dollaro statunitense (USD). Per i carrelli in altre valute il metodo di pagamento è nascosto al checkout. Per il CLP imposta la precisione della valuta CLP a 0 in International > Localization > Currencies, perché Flow addebita pesos interi.
Account Flow: ti servono API Key e Secret Key del tuo account Flow, in Flow alla voce Mis datos, Datos técnicos. Per i test crea un account sandbox separato su sandbox.flow.cl e usa le sue chiavi. Chiavi sandbox e live sono diverse. Non occorre configurare nulla nell'account Flow.
Sito pubblico: gli URL di conferma, ritorno e rimborso del tuo negozio devono essere raggiungibili da internet, senza protezione con password né firewall che blocchi Flow. La modalità manutenzione del negozio non li blocca.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un dominio.
Installazione
1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento clicca su Configure, oppure trova più tardi VibeFox Flow Gateway nell'elenco dei moduli e clicca su Configure.
3. Inserisci la chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).
4. Inserisci API Key e Secret Key sandbox, attiva Enable / Disable, clicca su Save ed effettua un ordine di prova.
5. Per accettare pagamenti reali, inserisci le chiavi live e disattiva Sandbox mode.
All'installazione il modulo crea due stati dell'ordine, Awaiting Flow payment e Flow payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Flow Gateway > Configure. Ogni sezione con campi ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando le chiavi della modalità corrente sono vuote (Flow viene allora nascosto al checkout), quando la valuta predefinita del negozio non è CLP o USD e quando la valuta CLP ha decimali (imposta la sua precisione a 0 così che prezzi, totali e rimborsi coincidano esattamente). In modalità sandbox mostra Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.
Flow.cl
Enable / Disable: Enable Flow.cl 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: Flow. Obbligatorio.
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: usa la sandbox Flow (sandbox.flow.cl) e le chiavi sandbox. In modalità sandbox non viene addebitato denaro reale. Predefinito: on. Disattivalo e inserisci le chiavi live per accettare pagamenti reali. I rimborsi usano sempre l'ambiente in cui l'ordine è stato pagato.
Sandbox API Key: la API Key del tuo account sandbox.flow.cl.
Sandbox Secret Key: la Secret Key del tuo account sandbox.flow.cl. Serve a firmare ogni richiesta.
Live API Key: la API Key del tuo account www.flow.cl.
Live Secret Key: la Secret Key del tuo account www.flow.cl. Tienila riservata.
Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarla.
Clear saved keys: spunta una chiave e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.
Notifiche
Il modulo invia tre URL a Flow con ogni pagamento e rimborso, quindi non occorre configurare nulla nell'account Flow. Il campo Flow URLs di questa sezione li elenca. Con gli URL leggibili (friendly URL) hanno questo aspetto:
La conferma contiene solo un token di pagamento. Il modulo cerca il token tra i pagamenti creati e chiede a Flow lo stato del pagamento con una richiesta firmata nell'ambiente in cui il pagamento è stato creato, applicando solo la risposta di Flow. Un pagamento che questo negozio non ha creato viene rifiutato senza interrogare Flow. Senza la conferma, l'ordine viene creato quando il cliente torna da Flow.
Avanzate
Debug log: scrive le chiamate API e le notifiche in logs/flw_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono mai registrati. Gli errori vengono sempre registrati, anche quando è disattivato. Predefinito: off.
Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.
Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le sue impostazioni e il registro. I dati Flow salvati sugli ordini vengono mantenuti. Predefinito: off.
Checkout
Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Flow) e vede la descrizione. In modalità sandbox mostra SANDBOX MODE — i pagamenti vanno alla sandbox Flow. Nessun addebito reale. Dopo la conferma, il modulo crea un pagamento Flow per il totale del carrello nella valuta del carrello, con oggetto Cart # seguito dal numero del carrello e dal nome del negozio, e invia il cliente alla pagina di pagamento Flow. L'e-mail del cliente viene passata a Flow. Lì il cliente sceglie un metodo di pagamento abilitato nel tuo account Flow. A questo punto non esiste ancora alcun ordine.
Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo quando Flow lo conferma: con la conferma oppure con una richiesta di stato firmata quando il cliente ritorna. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Flow has been received. Se il cliente ha generato un buono Servipag o Multicaja, l'ordine viene creato in Awaiting Flow payment e la pagina mostra Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Se il pagamento di un ordine con buono fallisce o viene annullato in seguito, la pagina mostra Your Flow payment was not completed. Please contact us about this order. Se l'importo non corrispondeva, la pagina mostra Your Flow payment was received and is being reviewed by the shop.
Se Flow non è raggiungibile al ritorno del cliente, oppure un'altra richiesta sta creando l'ordine in quel momento, una pagina Payment confirmation chiede al cliente di non pagare di nuovo e offre Check again e Back to checkout.
Se il pagamento è stato rifiutato, il cliente torna 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. Il carrello viene conservato e ogni nuovo tentativo crea un nuovo pagamento Flow legato al carrello.
Se Flow non riesce ad avviare il pagamento, il cliente resta al checkout con un messaggio breve, ad esempio Could not connect to Flow. Please try again in a moment. I dettagli sono nel registro.
Se un buono nel carrello smette di essere valido tra il pagamento e la sua conferma, PrestaShop lo rimuove dall'ordine. L'ordine passa quindi a Flow payment on hold con una nota, perché il cliente ha pagato il prezzo con lo sconto.
Il modulo 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 che il carrello è già stato pagato, l'ordine riceve una nota che ti chiede di rimborsare il duplicato in Flow.
Ordini e rimborsi
Stati dell'ordine
No order yet: il cliente è stato inviato a Flow e non ha pagato, oppure Flow non ha ancora confermato il pagamento. Esiste solo il carrello.
Payment accepted: Flow ha segnalato il pagamento come effettuato e importo e valuta corrispondono. Il pagamento viene registrato con il numero d'ordine Flow come ID della transazione, e una nota mostra importo, numero d'ordine Flow e metodo di pagamento.
Awaiting Flow payment: il cliente ha generato un buono di pagamento Servipag o Multicaja. L'ordine passa a Payment accepted quando Flow conferma il pagamento.
Flow payment on hold: Flow ha segnalato un importo o una valuta diversi dal totale dell'ordine (ad esempio il carrello è stato modificato dopo l'avvio del pagamento), un buono è stato rimosso oppure è arrivato un pagamento per un ordine annullato. Il pagamento incassato da Flow viene registrato e la nota lo spiega. Controlla l'ordine e spediscilo oppure rimborsa il pagamento.
Payment error: Flow ha rifiutato il pagamento con buono di un ordine in attesa.
Canceled: il pagamento con buono di un ordine in attesa è stato annullato in Flow.
Refunded: il pagamento è stato rimborsato interamente tramite il modulo.
Se arriva un altro pagamento per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nel tuo account Flow. Un ordine rimborsato non viene mai riaperto.
Blocco pagamento Flow
La pagina dell'ordine mostra un blocco Flow payment con il numero d'ordine Flow e il metodo di pagamento, il riferimento commerceOrder, lo stato del pagamento, l'importo pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, la cronologia dei rimborsi e le Flow notes dell'ordine.
Rimborsi
Nel blocco Flow payment inserisci l'importo (viene compilato quello non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Flow. Conferma la domanda Refund this amount via Flow? Flow e-mails the customer to complete the refund. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi sono limitati all'importo effettivamente addebitato da Flow: dopo una differenza di importo puoi quindi rimborsare fino a quanto ha pagato il cliente, non il totale dell'ordine. I rimborsi in CLP devono essere importi interi. Il rimborso viene inviato all'ambiente in cui il pagamento è stato effettuato (sandbox o live), quindi le chiavi di quell'ambiente devono essere impostate, e il cliente deve avere un'e-mail valida. Se Flow rifiuta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Una richiesta riuscita viene aggiunta alla cronologia dei rimborsi e alle note, con il numero e lo stato del rimborso Flow. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili dopo che Flow ha confermato il pagamento.
Le variazioni di stato successive del rimborso comunicate da Flow vengono aggiunte alle note. Se Flow rifiuta o annulla un rimborso in seguito, la nota indica che il denaro non è stato restituito al cliente e l'importo può essere rimborsato di nuovo. Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Flow. I rimborsi creati nella dashboard Flow non vengono importati in PrestaShop.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Flow Gateway è il primo blocco di Modules > Module Manager > VibeFox Flow Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Poi 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. Sotto ci sono la riga Product: presta-payment-flow 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, clicca 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 dominio: il dominio 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, Flow 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. La vetrina PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo 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 un rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a 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
Flow non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che le chiavi della modalità corrente siano compilate (chiavi sandbox in modalità sandbox, chiavi live in modalità live) e che la valuta del carrello sia CLP o USD. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.
Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la conferma Flow non raggiunge il tuo negozio e il cliente non è tornato. Verifica che l'URL di conferma indicato in Flow URLs si apra da internet e non sia bloccato da protezione con password o firewall. Attiva Debug log e controlla il campo Log nella pagina del modulo.
La conferma risponde Payment does not belong to the order: il token non è un pagamento creato da questo negozio, oppure Flow ha segnalato un altro riferimento per esso. Non viene modificato nulla.
La conferma risponde Gateway not configured: le chiavi dell'ambiente del pagamento sono vuote. Inseriscile di nuovo. Flow ripete la conferma.
La conferma risponde Flow API unavailable or Busy, retry: la richiesta di stato a Flow non è riuscita, oppure l'ordine era in fase di creazione da un'altra richiesta nello stesso momento. Flow ripete la conferma.
Il cliente vede Flow payments are not available at the moment: le chiavi mancano o Flow le ha rifiutate. Verifica API Key e Secret Key della modalità corrente.
Il cliente vede A valid billing email is required for Flow payments: Flow ha bisogno dell'e-mail del cliente.
Il cliente vede The order total is too small to be paid with Flow: il totale del carrello arrotonda a zero nella valuta del carrello.
Il cliente ha pagato, ma l'ordine è Awaiting Flow payment o Flow payment on hold: leggi le note nel blocco Flow payment. Il cliente ha generato un buono di pagamento in contanti non ancora pagato, oppure importo o valuta comunicati da Flow non corrispondono all'ordine. I totali CLP con decimali vengono arrotondati a pesos interi, quindi imposta la precisione del CLP a 0.
Il rimborso fallisce 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 rimborso fallisce con Flow accepts CLP refunds in whole units only: inserisci un importo intero.
Per gli sviluppatori, il README elenca gli hook actionWcpFlowSupportedCurrencies (valute per cui viene offerto il metodo di pagamento) e actionWcpFlowPaymentSubject (l'oggetto del pagamento inviato a Flow).
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Flow 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 modulo e il registro. Se è disattivo, tutte le impostazioni vengono mantenute per una successiva reinstallazione. I record dei pagamenti e dei rimborsi Flow e gli stati d'ordine Awaiting Flow payment e Flow payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID di transazione.
Flow è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da Flow.