VibeFox Omise 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.
HTTPS: i campi della carta si trovano nella pagina di checkout, quindi il checkout deve essere servito in HTTPS. I dati della carta comunque non raggiungono mai il tuo server. Omise invia i webhook solo a indirizzi HTTPS, e la pagina 3-D Secure della banca deve essere un indirizzo HTTPS.
Valuta: una tra THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Per un carrello in un'altra valuta il metodo di pagamento non viene mostrato al checkout.
Account Omise: ti servono la chiave pubblica e la chiave segreta del tuo account Omise, per la modalità test e per la modalità live, da Settings > Keys nel pannello di Omise, e un endpoint webhook in Settings > Webhooks (vedi Configurazione).
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 fai clic su Upload a module. Scegli il file ZIP del modulo.
2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Omise Payment nell'elenco dei moduli e fai clic su Configure.
3. Inserisci la chiave di licenza VibeFox nel campo License key del blocco licenza in alto nella pagina Configure e fai clic su Activate (vedi Chiave di licenza).
4. 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).
5. Attiva Enable/Disable e fai clic su Save. Prova un pagamento in modalità test con una carta di test Omise, come 4242 4242 4242 4242, poi disattiva Test mode.
All'installazione il modulo crea tre stati dell'ordine: Omise payment authorized, Omise payment on hold e Awaiting Omise payment. Il metodo di pagamento viene offerto per i paesi attivi al momento dell'installazione. Se attivi altri paesi in seguito, consenti il modulo anche per loro in Payment > Preferences, dove puoi anche limitarlo per valuta e gruppo di clienti.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Omise Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. 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, avvisa se manca la chiave pubblica o segreta della modalità corrente e avvisa quando Omise non accetta la valuta predefinita del tuo negozio. In questi casi il metodo di pagamento viene nascosto al checkout.
Omise
Enable/Disable: Enable card payments via Omise 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: Credit / Debit Card. Obbligatorio.
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, sotto 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) non viene salvata: resta il valore precedente e viene mostrato un avviso.
Test mode: usa le chiavi di test, senza addebiti reali. Scambia entrambe le chiavi. Acquisizioni, rimborsi e verifiche dello stato di un ordine usano sempre le chiavi della modalità in cui l'ordine è stato pagato. Predefinito: on.
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_...
Le chiavi segrete salvate non vengono più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.
Clear saved secrets: seleziona una chiave segreta e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.
Pagamento e webhook
Webhook URL: l'indirizzo del webhook del tuo negozio. Con URL semplici ha questo aspetto: https://your-shop/module/wcp_omise_payment/webhook. Copialo esattamente come lo mostrano le impostazioni e aggiungilo nel pannello di Omise, in Settings > Webhooks (solo HTTPS). Il modulo gestisce questi eventi (sono elencati anche in questa sezione):
Omise non firma i webhook, quindi il contenuto del webhook non viene mai considerato attendibile: l'addebito deve essere stato creato da questo negozio per quel carrello, e il suo stato viene riletto dalle API di Omise con la chiave segreta della modalità del pagamento. Senza il webhook, un ordine il cui cliente chiude il browser durante il 3-D Secure non viene creato automaticamente, e le acquisizioni effettuate nel pannello di Omise non vengono recepite finché non fai clic su Sync payment status.
Payment action: cosa succede all'importo sulla carta.
Per-charge webhook: invia l'URL del webhook con ogni addebito. Utile quando più negozi condividono un unico account Omise. Funziona solo se il negozio usa HTTPS; altrimenti si usa il webhook del pannello. Predefinito: off.
Avanzate
Debug log: scrive le richieste API e gli eventi di pagamento in logs/omise_p_debug.log.php nella cartella del modulo. Il file non può essere letto dal web. Chiavi, token e dati della carta non vengono mai registrati. Predefinito: off. Finché è disattivato non viene scritto nulla, errori compresi, quindi attivalo quando cerchi un problema.
Log: mostra la dimensione e le ultime voci del registro, con un pulsante per svuotarlo.
Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni e il registro di debug. Gli addebiti e i rimborsi Omise degli ordini fanno parte dello storico dei pagamenti e vengono sempre conservati. Predefinito: off.
Checkout
Nel passaggio di pagamento 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 il cliente effettua l'ordine, Omise.js trasforma la carta in un token monouso nel browser, usando l'indirizzo di fatturazione del carrello. I campi della carta non vengono mai inviati al tuo negozio. I campi mancanti o non validi vengono mostrati sotto il modulo, per esempio Please enter a valid card number.
Il tuo negozio crea poi l'addebito con la chiave segreta per il totale del carrello nella valuta del carrello. La descrizione dell'addebito è il nome del negozio e il numero del carrello, e l'ID del carrello viene salvato nei metadati dell'addebito. A questo punto non esiste ancora alcun ordine. Se la banca richiede il 3-D Secure, il cliente viene inviato alla pagina della banca e torna al tuo negozio, e il risultato viene riletto dalle API di Omise.
L'ordine viene segnato come pagato solo dopo la conferma di Omise: l'addebito deve essere acquisito e il suo importo e la sua valuta devono corrispondere al carrello. Il cliente vede la normale pagina di conferma dell'ordine con Your card payment has been received. Con Authorize only la pagina dice Your card payment has been authorized. The amount will be charged when your order is processed. Se Omise segnala ancora il pagamento come in sospeso, l'ordine viene creato in Awaiting Omise payment e la pagina dice Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. Se il pagamento non può essere confermato subito dopo il 3-D Secure, compare una pagina Payment confirmation con We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. e un pulsante Check again.
Se la carta viene rifiutata, non viene creato alcun ordine. Il cliente resta al checkout con Payment failed: e un motivo, per esempio fondi insufficienti, codice di sicurezza non valido o un rifiuto dell'emittente della carta, e può riprovare con lo stesso carrello. Se il 3-D Secure fallisce, il cliente torna al checkout anche con il motivo; se nel frattempo l'addebito è scaduto o stornato, il messaggio è The payment was not completed. Please try again.
Un nuovo tentativo non addebita mai due volte: se l'addebito precedente del carrello è già pagato o autorizzato, l'ordine viene creato senza un nuovo addebito. Un tentativo 3-D Secure non concluso scade prima che venga fatto un nuovo addebito. Se un secondo addebito risulta ancora pagato per un carrello che ha già un ordine (per esempio in un'altra scheda del browser), l'ordine non viene modificato e una nota ti chiede di rimborsarlo o annullarlo nel pannello di Omise.
Il webhook funziona anche mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.
Il modulo accetta solo carte. Non ha altri metodi di pagamento di Omise (PromptPay, TrueMoney, mobile banking, rate), né carte salvate o clienti Omise, né abbonamenti né acquisizione parziale.
Ordini e rimborsi
Stati dell'ordine
No order yet: il cliente è in 3-D Secure, oppure la carta è stata rifiutata. Esiste solo il carrello.
Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID addebito Omise (chrg_...) come ID transazione, e una nota mostra l'importo, l'addebito e come è stato confermato (checkout, ritorno dal 3-D Secure, webhook, nuovo tentativo di pagamento, acquisizione manuale o sincronizzazione manuale). Le note sono messaggi privati dell'ordine, visibili solo nel back office.
Omise payment authorized: la carta è stata autorizzata con Authorize only. Usa Capture payment o Void authorization.
Awaiting Omise payment: Omise non ha ancora confermato il pagamento. Il webhook o Sync payment status aggiornano l'ordine.
Omise payment on hold: l'importo o la valuta dell'addebito non corrispondono all'ordine, per esempio perché il carrello è stato modificato durante il 3-D Secure. La nota mostra entrambi i valori. Un pagamento acquisito viene comunque registrato sull'ordine. Controlla l'ordine e poi evadilo o rimborsa il pagamento.
Payment error: un pagamento in sospeso è fallito in seguito. Un ordine pagato non viene mai retrocesso da un evento di errore successivo.
Canceled: l'addebito è scaduto o l'autorizzazione è stata annullata.
Refunded: il pagamento è stato rimborsato interamente tramite il modulo.
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.
Blocco pagamento Omise
La pagina dell'ordine mostra un blocco Omise payment con l'ID addebito, l'azione di pagamento, lo stato dell'addebito, il marchio e le ultime cifre della carta, gli importi addebitati, dell'ordine e rimborsati, un badge Test mode per i pagamenti di test e lo storico dei rimborsi. I pulsanti del blocco richiedono il permesso di modificare gli ordini e la chiave segreta della modalità in cui è stato effettuato il pagamento. Non serve l'accesso alle pagine dei moduli. Il risultato di ogni azione viene mostrato in alto nel blocco.
Capture payment: acquisisce l'intero importo autorizzato e imposta l'ordine su Payment accepted. Mostrato solo per gli ordini autorizzati.
Void authorization: annulla l'autorizzazione; non viene acquisito denaro e l'ordine passa a Canceled. Mostrato solo per gli ordini autorizzati.
Sync payment status: rilegge l'addebito da Omise e aggiorna l'ordine. La nota mostra anche il totale rimborsato da Omise.
Rimborsi
Nel blocco Omise payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Omise. Conferma la domanda Refund this amount through Omise? This cannot be undone. Sono supportati rimborsi totali e parziali. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Omise, quindi dopo una discrepanza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento, quindi la chiave segreta di quella modalità deve essere impostata. Il motivo viene salvato con il rimborso presso Omise. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'ID rimborso Omise. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. Per un'autorizzazione non ancora acquisita è possibile solo un rimborso totale, che annulla l'autorizzazione. Se Omise rifiuta il rimborso, il blocco mostra Refund failed. con il messaggio di Omise, e nessun rimborso viene registrato.
Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non rimborsano denaro tramite Omise. I rimborsi effettuati nel pannello di Omise non vengono registrati in PrestaShop; Sync payment status mostra il totale rimborsato.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Omise Payment è il primo blocco di Modules > Module Manager > VibeFox Omise Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché 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-omise 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 Chiave non trovata, Questa chiave appartiene a un altro prodotto, Limite di domini raggiunto o Licenza scaduta il seguito da una data. Dopo che l'indirizzo del negozio cambia, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Omise non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. La vetrina 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 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 continuano a funzionare.
Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla 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
Omise does not appear at 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, chiavi live altrimenti) e che la valuta del carrello sia una di quelle supportate. La pagina delle impostazioni mostra un avviso quando mancano le chiavi. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.
The payment went through, but no order was created or the order stays Awaiting Omise payment: il webhook non funziona. Nel pannello di Omise verifica che l'URL del webhook sia esattamente quello mostrato in Webhook URL e che usi HTTPS. Su un ordine esistente fai clic su Sync payment status. Attiva Debug log per vedere le risposte del webhook.
Webhook answers Charge ID does not match order or Order not found: l'addebito nell'evento non è stato creato da questo negozio per quel carrello. Non viene modificato nulla.
Webhook answers Order is being processed, retry later or Failed to verify charge: il carrello è stato bloccato da un'altra richiesta nello stesso momento, le API di Omise non erano raggiungibili, oppure manca la chiave segreta della modalità del pagamento. Omise riprova il webhook.
Webhook answers The order could not be created, retry later: non è stato possibile creare l'ordine, per esempio perché il modulo è disattivato. Attiva Debug log per vedere il motivo.
The webhook URL shows Method not allowed in the browser: è normale. L'URL accetta solo richieste da Omise.
Warning on save: key must start with ... or must be a live key: una chiave è stata incollata nel campo sbagliato e non è stata salvata. Le chiavi di test iniziano con pkey_test_ / skey_test_, quelle live con pkey_ / skey_.
The customer sees Card payments are temporarily unavailable: le chiavi sono errate, oppure il token della carta appartiene all'altra modalità (un token di test in live o viceversa). Controlla le chiavi e Test mode.
The customer sees We could not reach the payment provider: nessuna risposta valida è arrivata da Omise durante la creazione dell'addebito. Un addebito potrebbe comunque essere stato creato; controlla il pannello di Omise prima che il cliente paghi di nuovo.
The customer sees This order is already being paid: il checkout è stato inviato due volte nello stesso momento. Il cliente attende un momento e controlla l'e-mail prima di riprovare.
Order is Omise payment on hold after payment: leggi la nota nell'ordine (vedi Stati dell'ordine), poi evadi l'ordine o rimborsa il pagamento.
Refund fails with a message about the mode: il pagamento è stato effettuato in modalità test o live, e la chiave segreta di quella modalità non è impostata. Inseriscila e riprova.
Partial refund of an authorized order fails: il pagamento è solo autorizzato. Acquisiscilo prima, oppure rimborsa l'intero importo per annullarlo.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Omise 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 e il registro di debug. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Gli addebiti e i rimborsi Omise e gli stati dell'ordine Omise payment authorized, Omise payment on hold e Awaiting Omise payment vengono sempre conservati, così gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.
Omise è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Omise né approvato da Omise.