VibeFox Omise for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso; se WooCommerce viene disattivato in seguito, il gateway non viene caricato e viene mostrato un avviso per l'amministratore.

PHP: 8.0 o successivo.

HTTPS: i campi della carta si trovano sulla tua pagina di checkout, quindi il checkout deve essere servito in HTTPS e privo di script non attendibili. I dati della carta, comunque, non raggiungono mai il tuo server. Omise invia i webhook solo a indirizzi HTTPS.

Valuta del negozio: una tra THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Per le altre valute il metodo di pagamento viene nascosto al checkout.

Account Omise: ti servono la chiave pubblica e la chiave segreta del tuo account Omise, sia per la modalità test sia per quella live, che trovi in Settings > Keys nel pannello di Omise, e un endpoint webhook in Settings > Webhooks (vedi Configurazione).

Chiave di licenza VibeFox: si acquista 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. In alternativa puoi caricare la cartella wcp_omise_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

5. Inserisci le chiavi Omise di test e live e aggiungi nel pannello di Omise l'URL del webhook mostrato nella pagina delle impostazioni (vedi Configurazione).

6. Attiva Enable/Disable. Prova un pagamento in modalità test con una carta di test di Omise, come 4242 4242 4242 4242, poi deseleziona Test mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Omise. Sopra i campi la pagina mostra Test mode is on — orders are charged with the test keys, no real money is moved. finché la modalità test è attiva, e ti avvisa se manca la chiave pubblica o segreta della modalità corrente o se la valuta del negozio non è supportata da Omise. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Nell'elenco dei metodi di pagamento, Omise risulta da configurare finché non sono inserite entrambe le chiavi della modalità corrente.

Generali

Enable/Disable: Enable card payments via Omise attiva o disattiva il metodo di pagamento. Predefinito: disattivo.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Credit / Debit Card.

Description: il testo mostrato sopra il modulo della carta al checkout. Predefinito: Pay securely with your credit or debit card via Omise.

Chiavi API

Trovi le chiavi nel pannello di Omise, in Settings > Keys. Le chiavi di test iniziano con pkey_test_ e skey_test_, quelle live con pkey_ e skey_. Al salvataggio, una chiave con il prefisso sbagliato (per esempio una chiave di test in un campo live) viene rifiutata con un errore e il valore precedente viene mantenuto.

Test mode: Use the test keys (no real charges). Cambia entrambe le chiavi. Rimborsi, acquisizioni e verifiche dello stato di un ordine usano sempre le chiavi della modalità in cui l'ordine è stato pagato. Predefinito: attivo.

Test public key: la chiave pubblica della modalità test, pkey_test_...

Test secret key: la chiave segreta della modalità test, skey_test_...

Live public key: la chiave pubblica della modalità live, pkey_...

Live secret key: la chiave segreta della modalità live, skey_...

Pagamento e webhook

La sezione mostra l'URL del webhook del tuo negozio. Ha questo aspetto: https://your-site/wp-json/omise-payment/v1/webhook. Copialo esattamente come lo mostrano le impostazioni e aggiungilo nel pannello di Omise in Settings > Webhooks (solo HTTPS). Il plugin gestisce questi eventi:

Il contenuto del webhook non viene mai considerato affidabile: l'addebito deve essere quello memorizzato nell'ordine, e il suo stato viene riletto dalle API di Omise con le chiavi della modalità dell'ordine. Senza il webhook, un ordine il cui cliente chiude il browser durante il 3-D Secure resta In attesa finché non esegui Omise: Sync payment status, e le acquisizioni effettuate nel pannello di Omise non vengono recepite automaticamente.

Payment action: cosa succede con l'importo sulla carta.

Per-charge webhook: Send the webhook URL with every charge. Utile quando più negozi condividono un unico account Omise. Funziona solo se il sito usa HTTPS; altrimenti viene usato il webhook del pannello. Predefinito: disattivo.

Avanzate

Debug log: Log API requests and payment events scrive i passaggi del pagamento in WooCommerce > Status > Logs, origine wcp_omise_payment. Chiavi, token e dati della carta non vengono mai registrati. Predefinito: disattivo.

Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. Predefinito: disattivo.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / Debit Card) e compila il modulo della carta: Name on card, Card number, Expiry month (MM), Expiry year (YYYY) e Security code (CVV). In modalità test il modulo mostra TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. Quando l'ordine viene effettuato, Omise.js trasforma la carta in un token monouso nel browser. I campi della carta non vengono mai inviati al tuo server.

Il tuo negozio crea l'addebito con la chiave segreta per il totale dell'ordine nella valuta dell'ordine. La descrizione dell'addebito è il nome del negozio e il numero dell'ordine, e l'ID dell'ordine viene salvato nei metadati dell'addebito. Se la banca richiede il 3-D Secure, il cliente viene reindirizzato alla banca e poi torna al tuo negozio. Il risultato viene sempre riletto dalle API di Omise.

L'ordine viene segnato come pagato solo dopo che Omise lo conferma: l'addebito deve essere acquisito e il suo importo e la sua valuta devono corrispondere all'ordine. Con Authorize only, l'ordine va In attesa dopo un'autorizzazione riuscita. Il cliente vede la pagina di conferma dell'ordine.

Se la carta viene rifiutata, il cliente resta al checkout con Payment failed: e un motivo, per esempio fondi insufficienti, codice di sicurezza non valido o rifiuto da parte dell'emittente della carta, e può riprovare. Dopo un 3-D Secure non riuscito, il cliente viene portato alla pagina Pay for order. Se il pagamento non può essere confermato subito dopo il 3-D Secure, il cliente vede We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.

Un nuovo tentativo non addebita mai due volte: se l'addebito precedente dell'ordine è già pagato o autorizzato, l'ordine viene completato senza un nuovo addebito. Tentativi 3-D Secure non conclusi scadono prima di creare un nuovo addebito.

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 solo carte. Non dispone di altri metodi di pagamento Omise (PromptPay, TrueMoney, mobile banking, rate, Konbini, PayNow), né di carte salvate o clienti Omise, né di abbonamenti o acquisizione parziale.

Ordini e rimborsi

Stati dell'ordine

In attesa di pagamento: il cliente è nel 3-D Secure o non ha ancora pagato.

In lavorazione: il pagamento è stato confermato. Gli ordini con soli prodotti virtuali scaricabili diventano Completato, come di consueto in WooCommerce. La nota dell'ordine mostra l'importo, l'ID dell'addebito e come è stato confermato (checkout, ritorno dal 3-D Secure, webhook, acquisizione manuale o sincronizzazione manuale). L'ID transazione è l'ID dell'addebito Omise (chrg_...).

In attesa, in attesa di acquisizione: la carta è stata autorizzata con Authorize only. Usa Omise: Capture payment oppure Omise: Void authorization.

In attesa, pagamento in sospeso: Omise non ha ancora confermato il pagamento, per esempio perché il cliente ha chiuso il browser durante il 3-D Secure. Il webhook o Omise: Sync payment status aggiornano l'ordine.

In attesa, discrepanza: l'importo o la valuta dell'addebito non corrispondono all'ordine. La nota mostra entrambi i valori. Controlla l'ordine e completalo oppure rimborsa il pagamento.

Non riuscito: il pagamento è stato rifiutato. Un ordine pagato non viene mai retrocesso da un successivo evento di errore.

Annullato: l'addebito è scaduto o l'autorizzazione è stata annullata.

Se arriva un addebito pagato o autorizzato per un ordine già Annullato o Rimborsato, l'ordine non viene riaperto. Una nota ti chiede di controllare il pannello di Omise e di rimborsare o riaprire l'ordine manualmente.

Azioni dell'ordine

Omise: Capture payment: acquisisce l'intero importo autorizzato. Mostrato solo per gli ordini autorizzati.

Omise: Void authorization: annulla l'autorizzazione; non viene acquisito denaro e l'ordine viene annullato. Mostrato solo per gli ordini autorizzati.

Omise: Sync payment status: legge l'addebito da Omise e aggiorna l'ordine. La nota mostra anche il totale rimborsato da Omise.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Omise. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento, quindi deve essere impostata la chiave segreta di quella modalità. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID del rimborso Omise. Per un'autorizzazione non ancora acquisita è possibile solo un rimborso totale, che annulla l'autorizzazione. Se Omise rifiuta il rimborso, WooCommerce mostra Refund failed. con il messaggio di Omise e non viene registrato alcun rimborso.

I rimborsi effettuati nel pannello di Omise non vengono importati come rimborsi di WooCommerce. Omise: Sync payment status mostra il totale rimborsato; se necessario, crea rimborsi manuali corrispondenti in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Omise. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui 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. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Omise 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 connessi 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 interessati: i pagamenti già avviati vengono comunque confermati, e acquisizioni e rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Omise non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che siano inserite entrambe le chiavi della modalità corrente (chiavi di test in modalità test, altrimenti chiavi live) e che la valuta sia supportata. Nella pagina Pay for order conta la valuta dell'ordine. La pagina delle impostazioni mostra un avviso se le chiavi o la valuta sono errate.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento o In attesa: il webhook non funziona. Nel pannello di Omise verifica che l'URL del webhook sia esattamente quello mostrato nelle impostazioni e che usi HTTPS. Poi esegui Omise: Sync payment status sull'ordine. Attiva il Debug log per vedere le risposte del webhook.

Il webhook risponde Earlier charge of the order, order not changed: l'evento riguarda un tentativo precedente dell'ordine, sostituito da un nuovo tentativo. Non viene modificato nulla nell'ordine. Se quell'addebito precedente risulta ancora pagato o autorizzato in Omise, una nota dell'ordine lo segnala una volta: controlla nel pannello di Omise un eventuale doppio pagamento e rimborsalo o annullalo lì.

Il webhook risponde Charge ID does not match order: l'addebito nell'evento appartiene a un altro ordine. Non viene modificato nulla.

Il webhook risponde Order is being processed, retry later oppure Failed to verify charge: l'ordine era bloccato da un'altra richiesta, oppure non è stato possibile raggiungere le API di Omise. Omise ripete il webhook.

Errore al salvataggio: key must start with ... oppure must be a live key: una chiave è stata incollata nel campo sbagliato. Le chiavi di test iniziano con pkey_test_ / skey_test_, quelle live con pkey_ / skey_.

Il cliente vede Card payments are temporarily unavailable: le chiavi sono errate, oppure il token della carta appartiene all'altra modalità (un token di test in modalità live o viceversa). Controlla le chiavi e Test mode.

Il cliente vede We could not reach the payment provider: da Omise non è arrivata una risposta valida durante la creazione dell'addebito. Un addebito potrebbe comunque essere stato creato; la nota dell'ordine ti chiede di controllare il pannello di Omise prima di addebitare di nuovo l'ordine.

Il cliente vede This order is already being paid: il checkout è stato inviato due volte nello stesso momento. Il cliente deve attendere e controllare l'e-mail prima di riprovare.

L'ordine è In attesa dopo il pagamento: leggi la nota dell'ordine. L'ordine attende l'acquisizione, Omise non ha ancora confermato il pagamento, oppure importo o valuta non corrispondono all'ordine.

Il rimborso non riesce con un messaggio sulla modalità: il pagamento è stato fatto in modalità test o live e la chiave segreta di quella modalità non è impostata. Inseriscila e riprova.

Il rimborso parziale di un ordine autorizzato non riesce: il pagamento è solo autorizzato. Acquisiscilo prima, oppure rimborsa l'intero importo per annullarlo.

Il blocco 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 e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. I dati Omise salvati sugli ordini sono lo storico dei pagamenti e vengono sempre conservati. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID delle transazioni.

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