VibeFox KOMOJU 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.
Account KOMOJU: ti servono la chiave segreta (sk_live_... e, per la modalità test, sk_test_...) e il token segreto di un webhook creato nel pannello KOMOJU (vedi Configurazione). La chiave pubblicabile non è necessaria. KOMOJU deve poter raggiungere l’URL del webhook del tuo negozio.
Valuta del carrello: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD o VND. Per i carrelli in altre valute il metodo di pagamento viene nascosto.
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 clicca su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento clicca su Configure, oppure trova più tardi VibeFox KOMOJU Payment nell’elenco dei moduli e clicca su Configure.
3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina di configurazione e clicca su Activate (vedi Chiave di licenza).
4. Nel pannello KOMOJU aggiungi un webhook con l’URL e gli eventi indicati nella sezione Webhook URL, e copia il suo token segreto (vedi Configurazione).
5. Inserisci la chiave segreta di produzione e il token segreto del webhook di produzione, e quelli di test per la modalità di test. Attiva Enable/Disable e clicca su Save.
All’installazione il modulo crea due stati dell’ordine: Awaiting KOMOJU payment e KOMOJU payment on hold. PrestaShop collega un nuovo modulo di pagamento solo ai paesi attivi in quel momento: un paese che attivi più tardi deve essere selezionato per il modulo in Payment > Preferences. Lì puoi anche limitare valute e gruppi di clienti.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox KOMOJU Payment > Configure. Ogni sezione ha un proprio pulsante Save, che salva l’intera pagina. Sopra i campi la pagina mostra KOMOJU Sandbox Mode is enabled. mentre la modalità test è attiva. Avvisa quando la modalità corrente non ha una chiave segreta (in tal caso il metodo di pagamento viene nascosto al checkout) o un token segreto del webhook (in tal caso le notifiche KOMOJU vengono rifiutate e quindi i pagamenti konbini e bonifico bancario non vengono mai confermati), e quando KOMOJU non supporta la valuta predefinita del negozio (in tal caso il metodo di pagamento viene nascosto per i carrelli in quella valuta).
Pagamento KOMOJU
Enable/Disable: Enable KOMOJU Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell’ordine. Predefinito: KOMOJU Payment.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.
Chiavi API di produzione
Trovi le chiavi nel pannello KOMOJU: la chiave segreta in Settings > API keys, il token segreto del webhook in Settings > Webhooks (aggiungi prima lì l’URL del webhook mostrato nella sezione Webhook URL).
Live Secret Key: la tua chiave segreta KOMOJU di produzione. Inizia con sk_live_.
Live Webhook Secret Token: il token segreto del webhook di produzione. Serve a verificare la firma di ogni notifica.
Modalità test
KOMOJU usa lo stesso indirizzo API per i pagamenti di test e di produzione: decide la chiave. I pagamenti mantengono la modalità in cui sono stati effettuati, quindi rimborsi e verifiche di stato di un ordine usano sempre la chiave di quella modalità.
Sandbox Mode: Enable test mode (use the test keys below, no real payments). Predefinito: disattivato. Mentre è attiva, il checkout mostra Test mode sopra la descrizione.
Sandbox Secret Key: la tua chiave segreta KOMOJU di test. Inizia con sk_test_.
Sandbox Webhook Secret Token: il token segreto del webhook della modalità test.
Le chiavi e 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.
Cancella i segreti salvati: seleziona una chiave o un token e clicca su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.
URL del webhook
Il webhook informa il tuo negozio sui pagamenti, compresi i pagamenti konbini e bonifico bancario differiti. Nel pannello KOMOJU, in Settings > Webhooks, aggiungi l’URL mostrato in questa sezione, sia per la produzione sia per la modalità test. Con URL leggibili ha questo aspetto: https://your-shop/module/wcp_komoju_payment/webhook, eventualmente con un codice lingua come /en/. Copia l’URL esattamente come lo mostrano le impostazioni. Poi copia il token segreto di ogni webhook in Live Webhook Secret Token o in Sandbox Webhook Secret Token.
Seleziona questi eventi (sono elencati anche in questa sezione):
Gli eventi di scadenza, annullamento e fallimento modificano l’ordine solo per il suo pagamento attuale, quindi un pagamento di un tentativo precedente non può annullare un ordine che viene pagato in un altro modo. I webhook senza firma valida vengono rifiutati. I webhook firmati con uno dei due token segreti sono accettati, ma solo per i pagamenti della stessa modalità. Senza webhook, i pagamenti con carta vengono comunque confermati quando il cliente torna nel negozio, ma i pagamenti konbini e bonifico bancario non vengono mai confermati.
Avanzate
Invoice Prefix: il prefisso dei numeri d’ordine inviati a KOMOJU, seguito dal numero del carrello. Se usi più negozi con lo stesso account KOMOJU, rendilo unico per ogni negozio. Predefinito: PS-.
Enable Logging: scrive gli eventi KOMOJU e le chiamate API in logs/komoju_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono registrati. Errori e avvisi vengono sempre scritti. Predefinito: disattivato.
Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.
Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni del gateway e il registro. Ordini, transazioni e rimborsi KOMOJU e gli stati dell’ordine restano sempre, quindi gli ordini vecchi possono essere ancora confermati e rimborsati dopo una reinstallazione. Predefinito: disattivato.
Checkout
Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita KOMOJU Payment) e conferma. Il modulo crea una sessione di pagamento KOMOJU per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento KOMOJU. L’e-mail, il nome, gli indirizzi di fatturazione e di spedizione e gli articoli ordinati vengono trasmessi a KOMOJU. La pagina viene mostrata in giapponese, inglese o coreano, in base alla lingua del carrello (in inglese per le altre lingue). Lì il cliente sceglie un metodo di pagamento. I metodi offerti dipendono dal tuo account KOMOJU e dalla valuta del carrello. A questo punto non esiste ancora alcun ordine.
Dopo il pagamento, il cliente torna nel tuo negozio. Il modulo legge la sessione di pagamento dall’API KOMOJU con la chiave della modalità del pagamento. L’ordine viene segnato come pagato solo quando KOMOJU lo conferma: tramite il webhook firmato o tramite la lettura della sessione al ritorno del cliente. Poi l’ordine viene creato e il cliente vede la pagina standard di conferma dell’ordine con Your payment with KOMOJU has been received. Se in quel momento KOMOJU non è raggiungibile, una pagina Payment confirmation mostra We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. e un pulsante Check again.
Per i pagamenti konbini e bonifico bancario il cliente riceve un bollettino di pagamento. L’ordine viene creato in Awaiting KOMOJU payment, e la pagina di conferma invita il cliente a completare il pagamento secondo le istruzioni di KOMOJU (per esempio in un convenience store o tramite bonifico bancario). L’ordine diventa Payment accepted quando il cliente paga e KOMOJU invia il webhook. Se il bollettino scade o il pagamento fallisce in seguito, la pagina di conferma mostra Your KOMOJU payment was not completed. Please contact us about this order.
Se il pagamento non è stato completato, il cliente torna al checkout con The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato. Un nuovo tentativo riutilizza la sessione KOMOJU aperta se il totale non è cambiato. Una sessione con un totale vecchio viene annullata in KOMOJU, e una sessione pagata nel frattempo crea l’ordine invece di un nuovo pagamento.
Se KOMOJU non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio KOMOJU could not accept this payment: con il motivo, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. oppure Payment error: Could not connect to KOMOJU. Please try again in a moment. Il motivo tecnico viene scritto 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 in KOMOJU payment on hold con una nota, perché il cliente ha pagato il prezzo con lo sconto.
Il webhook funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.
Il modulo non prevede un modulo della carta sul tuo sito, carte salvate o abbonamenti. Non limita i metodi di pagamento: vengono scelti nella pagina KOMOJU. Non ha un'azione di cattura manuale: i pagamenti autorizzati per la cattura manuale devono essere catturati nel pannello KOMOJU, e fino ad allora l’ordine resta in Awaiting KOMOJU payment.
Ordini e rimborsi
Stati dell’ordine
No order yet: il cliente è stato inviato a KOMOJU e non ha ancora pagato, oppure KOMOJU non ha ancora confermato il pagamento. Esiste solo il carrello.
Payment accepted: KOMOJU ha confermato il pagamento. Il pagamento viene registrato con l’ID pagamento KOMOJU come ID transazione, e una nota mostra l’ID del pagamento, il metodo di pagamento e come è stato confermato (webhook o ritorno).
Awaiting KOMOJU payment: è stato emesso un bollettino konbini o bonifico bancario che attende il pagamento, oppure un pagamento attende la cattura nel pannello KOMOJU.
KOMOJU payment on hold: KOMOJU ha segnalato un importo o una valuta diversi dal totale dell’ordine (per esempio il carrello è stato modificato dopo l’avvio del pagamento), un buono è stato rimosso, oppure il pagamento è stato catturato dopo che l’ordine era stato annullato. La nota lo spiega. Controlla l’ordine e completalo oppure rimborsa il pagamento.
Canceled: il bollettino di pagamento è scaduto oppure il pagamento è stato annullato.
Payment error: un pagamento di un ordine esistente non è riuscito.
Refunded: il pagamento è stato rimborsato integralmente, dalla pagina dell’ordine o nel pannello KOMOJU.
Se per un ordine già pagato viene catturato un secondo pagamento, l’ordine non cambia. Una nota ti chiede di rimborsarlo nel pannello KOMOJU se è un duplicato. Gli ordini rimborsati non vengono mai riaperti.
Blocco pagamento KOMOJU
La pagina dell’ordine mostra un blocco KOMOJU payment con l’ID del pagamento KOMOJU (collegato al pagamento nel pannello KOMOJU) e il metodo di pagamento, la sessione, il numero d’ordine presso KOMOJU, lo stato, l’importo pagato e l’importo rimborsato, un badge Test mode per i pagamenti di test, lo storico dei rimborsi e le KOMOJU notes dell’ordine.
Rimborsi
Nel blocco KOMOJU payment inserisci l’importo (viene compilato l’importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via KOMOJU. Conferma la domanda Refund this amount through KOMOJU? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi sono limitati all’importo effettivamente addebitato da KOMOJU, quindi dopo una discrepanza di importo puoi rimborsare fino a quanto ha pagato il cliente, non fino al totale dell’ordine. Il rimborso viene inviato con la chiave della modalità in cui è stato effettuato il pagamento, quindi deve essere impostata la chiave segreta di quella modalità. Il modulo controlla prima il pagamento in KOMOJU e rifiuta i rimborsi superiori all’importo ancora rimborsabile. Se KOMOJU non può rimborsare un pagamento in automatico (alcuni metodi, per esempio konbini, richiedono i dati bancari del cliente), viene mostrato il messaggio di errore di KOMOJU e non viene registrato nulla: gestisci questi rimborsi nel pannello KOMOJU. Un rimborso è considerato eseguito solo quando KOMOJU lo conferma. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note. Un rimborso totale imposta l’ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili una volta che KOMOJU ha catturato il pagamento.
Per i pagamenti che KOMOJU ha convertito in un'altra valuta (per esempio konbini in JPY per un carrello in EUR), da PrestaShop è possibile solo un rimborso totale. Effettua i rimborsi parziali nel pannello KOMOJU.
Il modulo non crea note di credito. I pulsanti standard di rimborso di PrestaShop nella pagina dell’ordine non restituiscono denaro tramite KOMOJU.
I rimborsi effettuati nel pannello KOMOJU arrivano tramite webhook e vengono aggiunti allo storico dei rimborsi con una nota. Quando l’intero pagamento viene rimborsato, l’ordine viene impostato su Refunded. I rimborsi parziali effettuati nel pannello per pagamenti convertiti in un'altra valuta vengono solo annotati sull’ordine: registra manualmente in PrestaShop l’importo corrispondente (nota di credito).
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox KOMOJU Payment è il primo blocco della pagina Modules > Module Manager > VibeFox KOMOJU Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca 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. Sotto compaiono la riga Product: presta-payment-komoju 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 un cambio di indirizzo del negozio, o dopo aver liberato un posto 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 solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.
Senza una chiave attiva, KOMOJU 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 viene nascosto anche a 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 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
KOMOJU non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia una chiave segreta: Sandbox Secret Key in modalità test, Live Secret Key in modalità produzione. La valuta del carrello deve essere supportata da KOMOJU. La pagina delle impostazioni mostra un avviso quando manca qualcosa. 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: il webhook non funziona. Nel pannello KOMOJU verifica che il webhook esista per la modalità che usi, che il suo URL sia esattamente quello mostrato nella sezione Webhook URL e che gli eventi siano selezionati. Controlla che il suo token segreto sia nel campo giusto (Live Webhook Secret Token o Sandbox Webhook Secret Token) e guarda il campo Log nella pagina del modulo. I pagamenti con carta vengono confermati anche quando il cliente torna nel tuo negozio, ma i pagamenti konbini e bonifico bancario vengono confermati solo dal webhook.
Il webhook risponde Failed to verify KOMOJU webhook signature.: il token segreto manca oppure appartiene a un altro webhook. KOMOJU ripete la notifica.
Il webhook risponde Mode mismatch, ignored.: il webhook è stato firmato con il token segreto dell’altra modalità rispetto a quella del pagamento. Usa webhook e token separati per la produzione e per la modalità test, e verifica che non siano scambiati.
Il webhook risponde Order is busy, retry later. oppure Temporary error, retry later.: l’ordine era in aggiornamento da un’altra richiesta, l’ordine non poteva essere creato in quel momento (per esempio il modulo è disattivato) oppure il pagamento non poteva essere verificato. KOMOJU ripete la notifica. Il motivo è nel registro.
L’URL del webhook mostra un errore nel browser: è normale. L’URL accetta solo richieste firmate da KOMOJU.
L’ordine è in KOMOJU payment on hold o Awaiting KOMOJU payment: leggi le KOMOJU notes nel blocco dell’ordine. Un bollettino è in attesa di pagamento, un pagamento attende la cattura nel pannello KOMOJU, importo o valuta non corrispondevano, un buono è stato rimosso oppure il pagamento è arrivato dopo l’annullamento dell’ordine.
Il rimborso non riesce: leggi il messaggio. Potrebbe mancare la chiave segreta della modalità in cui è stato effettuato il pagamento, il pagamento potrebbe non essere rimborsabile in automatico (rimborsalo nel pannello KOMOJU), KOMOJU potrebbe non riconoscere il pagamento con la chiave configurata, oppure per un pagamento convertito è possibile solo un rimborso totale.
Gli sviluppatori possono modificare l’elenco delle valute con l’hook actionKomojuPSupportedCurrencies e la sessione di pagamento, per esempio i metodi di pagamento, con l’hook actionKomojuPSessionParams.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox KOMOJU Payment 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 registro. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. Le transazioni e i rimborsi KOMOJU e gli stati dell’ordine Awaiting KOMOJU payment e KOMOJU payment on hold restano sempre, quindi gli ordini vecchi possono essere ancora confermati e rimborsati dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento e gli ID delle transazioni.
KOMOJU è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da KOMOJU.