VibeFox GMO 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 più vecchie.

Valuta: yen giapponese (JPY). GMO-PG addebita solo in yen, quindi il metodo di pagamento viene mostrato solo quando la valuta del carrello è JPY. Aggiungi JPY in International > Localization > Currencies se il tuo negozio non ce l’ha ancora.

Account GMO Payment Gateway: un contratto commerciante GMO-PG con Link Type Plus. Ti servono Shop ID, Shop password e Config ID di Link Type Plus (設定ID) degli ambienti di test e/o di produzione, e la notifica del risultato (結果通知) attivata nella console del negozio GMO-PG (vedi Configurazione). Site ID e Site password non vengono usati.

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 GMO Payment Gateway 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 Configure, e clicca su Activate (vedi Chiave di licenza).

4. Inserisci Shop ID, Shop password e Config ID dell’ambiente di test e/o di produzione e scegli l’Environment.

5. Nella console del negozio GMO-PG attiva 結果通知 (notifica del risultato) e imposta l’URL di notifica mostrato nelle impostazioni (vedi Configurazione).

6. Attiva Enable/Disable e clicca su Save. Effettua un pagamento di prova nell’ambiente di test, poi passa Environment alla produzione.

All’installazione il modulo crea lo stato dell’ordine GMO-PG payment on hold. PrestaShop propone un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences; il JPY deve restare consentito.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox GMO Payment Gateway > Configure. Ogni pulsante Save salva l’intera pagina. Sopra i campi, la pagina ti avvisa se la valuta predefinita del negozio non è JPY e se mancano Shop ID, Shop password o Config ID dell’ambiente attuale (in tal caso il metodo di pagamento viene nascosto al checkout). Mostra anche quale ambiente è attivo: TEST — payments go to pt01.mul-pay.jp with the test credentials, no real money is charged. oppure PRODUCTION — payments go to p01.mul-pay.jp. Gli spazi attorno alle credenziali vengono rimossi al salvataggio.

GMO Payment Gateway — Credit Card

Enable/Disable: Enable GMO Payment Gateway — Credit Card attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento mostrato al checkout. È anche il nome del metodo di pagamento salvato nell’ordine. Predefinito: Credit card. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: You will be redirected to the secure GMO Payment Gateway page to pay by credit card.

Account GMO-PG

Shop ID e Shop password si trovano nella console GMO-PG in Shop management > Shop information, il Config ID in Link Type Plus > Settings (設定ID). Gli ambienti di test e di produzione hanno credenziali diverse.

Environment: quale ambiente GMO-PG riceve i nuovi pagamenti.

Production Shop ID: lo Shop ID dell’ambiente di produzione.

Production Shop password: la Shop password dell’ambiente di produzione.

Production Config ID: il config ID di Link Type Plus (設定ID) registrato nella console GMO-PG.

Test Shop ID: lo Shop ID dell’ambiente di test.

Test Shop password: la Shop password dell’ambiente di test.

Test Config ID: il config ID di Link Type Plus (設定ID) dell’ambiente di test.

Le password salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved passwords: spunta una password e clicca su Save per eliminarla. Un campo vuoto mantiene il valore salvato.

Payment

Capture: quando viene addebitata la carta.

Order status after payment: lo stato di un ordine pagato.

Notifiche di pagamento (結果通知)

La notifica del risultato comunica al tuo negozio che un pagamento è stato effettuato. È obbligatoria. Nella console GMO-PG attiva 結果通知 (notifica del risultato) e imposta l’URL mostrato in Notification URL in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_gmo_payment/notify, eventualmente con un codice lingua come /ja/. Copia l’URL esattamente come lo mostrano le impostazioni. Deve essere raggiungibile da Internet; la modalità manutenzione non lo blocca.

Le notifiche di GMO-PG non sono firmate, quindi il modulo non si fida mai del loro contenuto. La notifica deve provenire da uno degli Shop ID configurati e riferirsi a un pagamento creato da questo negozio, nell’ambiente in cui è stato effettuato il pagamento. Il modulo chiede poi a GMO-PG la transazione (SearchTrade) con la tua Shop password e modifica il carrello o l’ordine solo in base a quella risposta. Una notifica che non corrisponde a una transazione reale non cambia nulla. Le transazioni non create dal negozio, per esempio quelle fatte nella console GMO-PG, vengono confermate e ignorate. Quando il modulo non riesce a verificare una notifica, risponde in modo che GMO-PG la invii di nuovo (GMO-PG riprova fino a 5 volte).

Senza la notifica, l’ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Advanced

Debug log: scrive le richieste API e le notifiche in logs/gmo_pg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche quando l’interruttore è disattivato. Password e dati dei clienti vengono mascherati. Predefinito: disattivato.

Log: mostra la dimensione e le voci più recenti 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. I dati degli ordini (GMO OrderID, ID delle transazioni) vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit card) e ne vede la descrizione. Nell’ambiente di test, sopra compare il badge TEST — GMO-PG test environment, no real charges.. Dopo la conferma, il modulo crea un pagamento GMO-PG Link Type Plus per il totale del carrello, arrotondato a yen interi, e invia il cliente alla pagina di pagamento di GMO-PG. Lì il cliente paga con carta di credito. Il 3-D Secure 2.0 è gestito da GMO-PG, e l’indirizzo e-mail del cliente viene passato a GMO-PG per il 3-D Secure. La pagina di pagamento si apre in giapponese, cinese o inglese, in base alla lingua del cliente. Il pagamento compare in GMO-PG con PS- e il numero del carrello. Non vengono inviati altri dati del cliente. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna nel tuo negozio. Il risultato firmato viene verificato con la Shop password dell’ambiente del pagamento, e l’ordine viene segnato come pagato solo dopo la conferma di GMO-PG: con una richiesta SearchTrade lato server quando il cliente torna, oppure con la notifica del risultato. Entrambi usano la stessa logica, quindi l’ordine non viene mai creato due volte. Il cliente vede poi la pagina standard di conferma dell’ordine. Se GMO-PG non ha ancora confermato il pagamento, appare una pagina Payment confirmation con il messaggio Your card payment is being confirmed by GMO Payment Gateway. You will receive an e-mail as soon as it is confirmed. e un pulsante Check again; la notifica crea l’ordine non appena arriva.

Se la carta viene rifiutata o il pagamento non va a buon fine nella pagina di GMO-PG, il cliente torna al checkout con il messaggio The card payment was declined or could not be completed. Please try again or use another card.. Se il cliente lascia la pagina di GMO-PG senza pagare, il messaggio è The payment was not completed. You can try again or choose another payment method.. Il carrello viene conservato. Ogni nuovo tentativo annulla il precedente link di pagamento non pagato. Se nel frattempo il link precedente è stato pagato, l’ordine viene creato da quel pagamento e non viene generato un nuovo link.

Si possono pagare totali di carrello da 1 a 9.999.999 JPY. Totali superiori nascondono il metodo di pagamento. Se il pagamento non può essere avviato, il cliente resta al checkout con un breve messaggio, per esempio Card payment could not be started. Please try again or choose another payment method., e il motivo viene scritto nel registro.

La notifica e il ritorno funzionano anche quando il negozio è in modalità manutenzione e non sono bloccati dalla restrizione per paese del tuo negozio.

Il modulo accetta pagamenti con carta di credito solo in JPY, sempre nella pagina di GMO-PG. Non offre altri metodi di pagamento GMO-PG, più valute, carte salvate o registrazione di membro GMO-PG, abbonamenti o addebiti ricorrenti né un modulo della carta sul tuo sito.

Ordini e rimborsi

Stati dell’ordine

Nessun ordine ancora: il cliente è stato inviato a GMO-PG e non ha pagato, oppure GMO-PG non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted o Delivered: il pagamento è stato confermato. Lo stato segue Order status after payment. Il pagamento viene registrato con il TranID di GMO-PG come ID della transazione, e una nota mostra l’importo, lo stato GMO-PG, la transazione e come è stato confermato (notifica o ritorno).

GMO-PG payment on hold (autorizzato): con Authorize only (仮売上) l’importo è stato autorizzato. Acquisiscilo con Capture payment (GMO-PG) o nella console GMO-PG prima che l’autorizzazione scada. Dopo l’acquisizione l’ordine diventa Payment accepted o Delivered. Se l’autorizzazione viene annullata in GMO-PG, l’ordine diventa Canceled.

GMO-PG payment on hold dopo il pagamento: GMO-PG ha segnalato un importo diverso dal totale del carrello, oppure il carrello non era in JPY. La nota lo spiega, e il pagamento viene registrato per l’importo che GMO-PG ha effettivamente incassato. Controlla l’ordine ed evadilo oppure rimborsa il pagamento.

Refunded: il pagamento è stato rimborsato integralmente tramite il modulo. Il rimborso totale di un’autorizzazione mai acquisita imposta Canceled.

Se arriva un secondo pagamento per un carrello il cui ordine è già pagato o chiuso, l’ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nella console GMO-PG.

Blocco GMO Payment Gateway

La pagina dell’ordine mostra un blocco GMO Payment Gateway con GMO OrderID, Transaction ID, lo stato (con lo stato GMO-PG), Paid / refunded, un badge TEST per i pagamenti di test, lo storico dei rimborsi e le GMO-PG notes dell’ordine. Acquisizione e rimborsi richiedono il permesso di modificare gli ordini; non serve l’accesso alle pagine dei Moduli.

Acquisizione

Capture payment (GMO-PG) compare nel blocco di un ordine in attesa che è stato solo autorizzato. Conferma Capture the authorized GMO-PG payment?. Il modulo verifica la transazione in GMO-PG e addebita l’importo autorizzato. Se la transazione non è più autorizzata, per esempio perché è già stata acquisita nella console GMO-PG, una nota mostra lo stato attuale e l’ordine lo segue.

Rimborsi

Nel blocco inserisci l’importo (viene precompilato l’importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via GMO-PG. Conferma Refund this amount through GMO-PG?. Sono supportati rimborsi totali e parziali, in yen interi. Il limite è l’importo che GMO-PG ha effettivamente incassato e che trattiene ancora, non il totale dell’ordine. Rimborsare l’intero importo residuo annulla la transazione GMO-PG, e spetta a GMO-PG decidere se si tratta di un annullamento o di un storno. Un rimborso parziale riduce l’importo della transazione. Il rimborso viene inviato all’ambiente in cui è stato effettuato il pagamento, quindi devono essere impostati Shop ID e Shop password di quell’ambiente. Se GMO-PG non accetta il rimborso, il blocco mostra l’errore e non viene registrato alcun rimborso. 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.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell’ordine non restituiscono denaro tramite GMO-PG.

I rimborsi e le cancellazioni effettuati nella console GMO-PG arrivano tramite la notifica del risultato e vengono aggiunti alle note. Lo stato dell’ordine e le note di credito non vengono modificati automaticamente, tranne nel caso di un’autorizzazione annullata in GMO-PG. Aggiornali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox GMO Payment Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox GMO Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino a cui 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 di essi ci sono la riga Product: presta-payment-gmo 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 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, il pagamento con carta GMO-PG 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 sei connesso 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 acquisizioni e 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 alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

La carta di credito non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la valuta del carrello sia JPY e che l’ambiente attuale abbia Shop ID, Shop password e Config ID. Totali di carrello superiori a 9.999.999 JPY non si possono pagare con carta. La pagina delle impostazioni mostra un avviso se valuta o credenziali sono errate. In Payment > Preferences verifica che il modulo sia consentito per JPY, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la notifica del risultato non funziona. Nella console del negozio GMO-PG dell’ambiente che usi, verifica che 結果通知 sia attivo e che l’URL sia esattamente quello mostrato in Notification URL. Verifica che Shop ID e Shop password di quell’ambiente siano compilati, perché il modulo verifica ogni notifica con essi. Attiva Debug log e controlla il campo Log nella pagina del modulo. L’ordine viene creato anche quando il cliente torna nel negozio dopo il pagamento.

Il registro mostra Notification rejected: unknown ShopID: la notifica proviene da un negozio il cui Shop ID non è nelle impostazioni. Inserisci lo Shop ID di quell’ambiente.

Il registro mostra Notification ignored: OrderID is not a payment of this store: la transazione non è stata creata da questo negozio, per esempio è stata fatta nella console GMO-PG. Non serve fare nulla.

Il registro mostra che il carrello è stato pagato in un altro ambiente: i pagamenti di test e di produzione sono tenuti separati. Una notifica di test non conferma mai un pagamento di produzione e viceversa.

Il registro mostra Cannot create the order: the module is disabled: il modulo è stato disattivato mentre un pagamento era in fase di conferma. Riattivalo; GMO-PG invierà di nuovo la notifica.

Il cliente vede un errore quando sceglie il pagamento con carta: attiva Debug log e controlla il campo Log. Il registro mostra il codice di errore GMO-PG (ErrCode, ErrInfo). La causa più comune è uno Shop ID, una Shop password o un Config ID errati. GMO Payment Gateway accepts payments in Japanese Yen (JPY) only. significa che il carrello non è in JPY.

L’ordine è in GMO-PG payment on hold: leggi le note nel blocco GMO Payment Gateway. L’ordine è stato solo autorizzato e attende l’acquisizione, oppure l’importo pagato differiva dal carrello.

Il rimborso o l’acquisizione non riesce: leggi il messaggio nel blocco. L’ordine potrebbe essere stato pagato nell’altro ambiente, di cui non sono impostati Shop ID e password; la transazione potrebbe essere già annullata in GMO-PG; oppure l’importo potrebbe superare quanto resta sulla transazione. The order is being updated by GMO-PG right now. Try again in a moment. significa che una notifica era in elaborazione nello stesso momento.

Il blocco mostra You do not have permission to refund orders.: il tuo profilo dipendente non ha il diritto di modificare gli ordini. Chiedi a un amministratore di concedertelo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox GMO Payment 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 gateway e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi GMO-PG e lo stato d’ordine GMO-PG payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere ancora acquisiti e rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID delle transazioni.

GMO Payment Gateway è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da GMO Payment Gateway.