VibeFox KOMOJU for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin rifiuta l’attivazione senza di esso.

PHP: 8.0 o successivo.

HTTPS: il sito richiede HTTPS e KOMOJU deve poter raggiungere l’URL del webhook.

KOMOJU account: servono la chiave segreta (sk_live_... e, per i test, sk_test_...) e il token segreto di un webhook creato nel pannello KOMOJU (vedi Configurazione). La chiave pubblicabile non serve.

Store currency: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD o VND. Per altre valute il metodo viene nascosto.

VibeFox license key: acquistata su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. In WordPress apri Plugins > Add New > Upload Plugin, scegli lo ZIP del plugin e clicca Install Now. Puoi anche caricare la cartella wcp_komoju_payment in /wp-content/plugins/ tramite FTP.

2. Clicca Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > KOMOJU Payment > Manage, oppure clicca Settings sotto il nome del plugin nella pagina dei plugin.

4. Inserisci la chiave di licenza VibeFox nel blocco licenza in alto e clicca Activate.

5. Nel pannello KOMOJU aggiungi un webhook con URL ed eventi indicati nelle impostazioni e copia il suo token segreto (vedi Configurazione).

6. Inserisci chiave segreta e token segreto del webhook live, e quelli di test per la modalità sandbox. Attiva Enable/Disable e salva.

Configurazione

Tutte le impostazioni sono su una pagina: WooCommerce > Settings > Payments > KOMOJU Payment. Sopra i campi appare KOMOJU Sandbox Mode is enabled. in modalità test. La pagina avvisa se alla modalità corrente manca la chiave segreta (il metodo è nascosto al checkout) o il token segreto del webhook (le notifiche KOMOJU vengono respinte e i pagamenti konbini e con bonifico non vengono mai confermati), e se la valuta non è supportata. Nell’elenco dei metodi KOMOJU risulta da configurare finché la modalità corrente non ha una chiave segreta e mostra un badge di test quando sandbox è attivo.

Generale

Enable/Disable: Enable KOMOJU Payment Gateway attiva o disattiva il metodo. Predefinito: off.

Title: nome del metodo visibile ai clienti al checkout. Predefinito: KOMOJU Payment.

Description: testo sotto il metodo 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 live

Trovi le chiavi nel pannello KOMOJU: la chiave segreta in Settings > API keys, il token segreto del webhook in Settings > Webhooks (aggiungi prima l’URL del webhook mostrato sotto).

Live Secret Key: la tua chiave segreta live KOMOJU. Inizia con sk_live_.

Live Webhook Secret Token: token segreto del webhook live. Verifica la firma di ogni notifica.

Modalità test

KOMOJU usa lo stesso indirizzo API per test e live: decide la chiave. Gli ordini conservano la modalità di pagamento, quindi rimborsi e controlli di stato usano sempre la chiave di quella modalità.

Sandbox Mode: Enable test mode (use the test keys below, no real payments). Predefinito: off. Quando è attivo, il checkout mostra Test mode sopra la descrizione.

Sandbox Secret Key: la tua chiave segreta di test KOMOJU. Inizia con sk_test_.

Sandbox Webhook Secret Token: token segreto del webhook di test.

URL del webhook

Il webhook comunica al negozio i pagamenti, compresi quelli differiti konbini e con bonifico. Nel pannello KOMOJU, in Settings > Webhooks, aggiungi l’URL di questa sezione per live e test. Ha questo aspetto: https://your-site/wc-api/komoju_p_webhook/. Se il sito usa prefissi di lingua negli URL, copia esattamente quello delle impostazioni. Poi copia il token segreto di ciascun webhook in Live Webhook Secret Token o Sandbox Webhook Secret Token.

Seleziona questi eventi:

Gli eventi di scadenza, annullamento ed errore modificano l’ordine solo per il suo pagamento corrente: un pagamento di un tentativo precedente non può annullare un ordine che viene pagato diversamente. I webhook senza firma valida sono respinti. Quelli firmati con uno dei due token segreti sono accettati solo per ordini della stessa modalità. Senza webhook, le carte sono confermate al ritorno del cliente, ma konbini e bonifici non vengono mai confermati.

Avanzate

Invoice Prefix: prefisso dei numeri d’ordine inviati a KOMOJU. Se più negozi usano lo stesso account KOMOJU, rendilo univoco per ciascuno. Predefinito: WC-.

Enable Logging: Log KOMOJU events and API calls in WooCommerce > Status > Logs, origine wcp_komoju_payment, senza chiavi o dati dei clienti. Gli errori vengono sempre registrati. Predefinito: off.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Disattivare il plugin non elimina mai nulla. I dati degli ordini (ID dei pagamenti KOMOJU) restano sempre. Predefinito: off.

Checkout

Il cliente sceglie il metodo (predefinito KOMOJU Payment) e invia l’ordine. Il plugin crea una sessione KOMOJU per il totale nella valuta dell’ordine e lo invia alla pagina di pagamento KOMOJU. E-mail di fatturazione, nome, indirizzi di fatturazione e spedizione e articoli ordinati vengono trasmessi a KOMOJU. La pagina appare in giapponese, inglese o coreano secondo la lingua del sito (inglese per le altre). Qui il cliente sceglie il metodo. Quelli offerti dipendono dal tuo account KOMOJU e dalla valuta dell’ordine.

Dopo il pagamento, il cliente torna al negozio. Il plugin legge la sessione tramite API KOMOJU con la chiave della modalità dell’ordine. L’ordine è pagato solo dopo conferma KOMOJU: webhook firmato o lettura della sessione al ritorno. Se KOMOJU è irraggiungibile, il cliente arriva alla pagina di ordine ricevuto con 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.

Per konbini e bonifici il cliente riceve un bollettino. L’ordine resta in sospeso e si completa quando il cliente paga e KOMOJU invia il webhook. Se il bollettino scade, l’ordine viene annullato.

Se il pagamento non è completato, il cliente torna a Pay for order con The payment was not completed. You can try again or choose another payment method. Un nuovo tentativo riusa la sessione aperta se il totale non cambia. Una sessione con vecchio totale viene annullata in KOMOJU, una pagata nel frattempo conferma l’ordine. Quando un ordine non pagato viene annullato (da te, dal cliente o dal timer WooCommerce per la riserva delle scorte), si annulla anche la sessione KOMOJU aperta, impedendone il pagamento.

Se KOMOJU non può avviare il pagamento, il cliente vede un messaggio breve, ad esempio KOMOJU could not accept this payment: con il motivo, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. o Payment error: Could not connect to KOMOJU. Please try again in a moment. I dettagli sono aggiunti alle note dell’ordine e al registro.

Il metodo funziona nel checkout classico, nel blocco Checkout e su Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin non offre modulo della carta sul sito, carte salvate o abbonamenti. Non limita i metodi, scelti sulla pagina KOMOJU. Non offre acquisizione manuale: i pagamenti così autorizzati vanno acquisiti nel pannello KOMOJU e l’ordine resta in sospeso fino ad allora.

Ordini e rimborsi

Stati degli ordini

Pending payment: il cliente è stato inviato a KOMOJU e non ha ancora pagato, oppure KOMOJU non ha ancora confermato.

Processing or Completed: KOMOJU ha confermato il pagamento. WooCommerce assegna lo stato consueto per un ordine pagato. La nota mostra ID pagamento KOMOJU, metodo e conferma (webhook o ritorno). L’ID transazione è l’ID pagamento KOMOJU e nella schermata dell’ordine rimanda al pagamento nel pannello KOMOJU.

On hold: è stato emesso un bollettino konbini o bonifico e si attende il pagamento, oppure un pagamento attende acquisizione nel pannello KOMOJU. L’ordine resta in sospeso anche se importo o valuta non corrispondono o se un pagamento è stato acquisito dopo l’annullamento. La nota lo spiega. Evadi l’ordine o rimborsa il pagamento.

Failed: pagamento non riuscito. Il cliente può riprovare.

Cancelled: bollettino scaduto o pagamento annullato.

Refunded: pagamento interamente rimborsato da WooCommerce o dal pannello KOMOJU.

Se un secondo pagamento viene acquisito per un ordine già pagato, l’ordine non cambia ancora. Una nota chiede di rimborsarlo nel pannello KOMOJU se duplicato. Gli ordini rimborsati non vengono mai riaperti.

Rimborsi

Apri l’ordine, clicca Refund, inserisci l’importo e clicca Refund via KOMOJU Payment. Sono supportati rimborsi totali e parziali. Si usa la chiave della modalità di pagamento dell’ordine: la sua chiave segreta deve essere configurata. Il plugin controlla prima il pagamento in KOMOJU e rifiuta importi superiori al saldo rimborsabile. Se KOMOJU non può rimborsare automaticamente (alcuni metodi, come konbini, richiedono i dati bancari del cliente), appare il suo errore e nulla viene registrato: gestisci questi rimborsi nel pannello KOMOJU. Un rimborso risulta effettuato solo dopo conferma KOMOJU. Quello riuscito viene aggiunto alle note.

Per pagamenti convertiti da KOMOJU in altra valuta (ad esempio konbini in JPY per un ordine EUR), WooCommerce permette solo rimborsi totali. Esegui quelli parziali nel pannello KOMOJU.

I rimborsi del pannello KOMOJU arrivano via webhook e vengono registrati automaticamente in WooCommerce. Un rimborso totale imposta Rimborsato. Quelli parziali dal pannello per pagamenti convertiti sono solo annotati: registra l’importo corrispondente in WooCommerce con "Refund manually".

Chiave di licenza

Il plugin usa una chiave VibeFox di vibefox.net. Il blocco licenza è in cima a WooCommerce > Settings > Payments > KOMOJU Payment. Incolla la chiave in License key e clicca Activate. Il blocco mostra stato, ad esempio scadenza della licenza e dominio. Usa Check now per ricontrollare, Change key per un’altra chiave, Remove key per rimuoverla dal sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un dominio. Rimuoverla dal sito non libera il posto del dominio. Liberalo nel tuo account vibefox.net.

Senza chiave attiva, KOMOJU non appare ai clienti al checkout. Se parte comunque un pagamento, il cliente vede This payment method is not available. Please choose another one. I gestori connessi vedono ancora il metodo con (unlicensed — visible to admins only), per configurare e provare il plugin prima dell’acquisto. Un promemoria appare nella pagina dei plugin e nelle pagine WooCommerce. Gli ordini esistenti non sono coinvolti: pagamenti avviati confermati e rimborsi funzionanti.

Alla scadenza della licenza il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

KOMOJU non appare al checkout: verifica licenza attiva, Enable/Disable attivo e chiave segreta della modalità corrente: Sandbox Secret Key in sandbox, Live Secret Key in live. La valuta deve essere supportata da KOMOJU. Le impostazioni segnalano ciò che manca.

Pagamento riuscito, ma ordine ancora Pending payment: il webhook non funziona. Nel pannello KOMOJU verifica che esista per la modalità usata, che l’URL sia esattamente quello delle impostazioni e gli eventi selezionati. Verifica il token nel campo corretto (Live Webhook Secret Token o Sandbox Webhook Secret Token) e consulta WooCommerce > Status > Logs, origine wcp_komoju_payment. Le carte sono confermate anche al ritorno del cliente, konbini e bonifici solo via webhook.

Il webhook risponde Failed to verify KOMOJU webhook signature: token segreto mancante o di un altro webhook. KOMOJU ritenta la notifica.

Il webhook risponde Mode mismatch, ignored: è firmato con il token di una modalità diversa da quella dell’ordine. Usa webhook e token separati per live e test.

Il webhook risponde Order is busy, retry later o Temporary error, retry later: un’altra richiesta aggiornava l’ordine o il pagamento non era verificabile. KOMOJU ritenta la notifica.

L’ordine è On hold: leggi la nota. Un bollettino attende pagamento, un pagamento attende acquisizione nel pannello KOMOJU, importo o valuta non coincidevano, oppure il pagamento è arrivato dopo l’annullamento.

Rimborso non riuscito: leggi il messaggio. Può mancare la chiave della modalità originale, il pagamento può non essere rimborsabile automaticamente (usa il pannello KOMOJU), oppure per una conversione è possibile solo il rimborso totale.

Il blocco licenza mostra un errore: segui il messaggio. Se la chiave è usata su un altro dominio, libera un posto nell’account vibefox.net e clicca Check now. Se l’indirizzo del sito è cambiato, clicca Check now per attivare il nuovo dominio. Se il server licenze non risponde, il plugin mantiene l’ultimo stato noto.

Gli sviluppatori possono modificare le valute con komoju_p_supported_currencies e la sessione, ad esempio i metodi di pagamento, con komoju_p_session_params.

Disinstallazione

La disattivazione conserva tutti i dati. Per rimuovere il plugin, disattivalo ed eliminalo su Plugins. Chiave e stato licenza vengono sempre rimossi. Impostazioni e registri del gateway vengono rimossi solo se Delete data on uninstall era attivo; altrimenti restano per una reinstallazione. Gli ordini conservano note di pagamento e ID transazione.

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