VibeFox Comgate for PrestaShop — Guida

Requisiti

PrestaShop: dalla 8.0 alla 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

HTTPS: il tuo negozio deve essere raggiungibile via HTTPS da internet, così che Comgate possa inviare la notifica in background.

Valuta: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK o SEK. Per le altre valute e per i totali inferiori al minimo di Comgate, il metodo di pagamento viene nascosto. I pagamenti in HUF vengono arrotondati a fiorini interi, come richiede Comgate.

Account Comgate: ti servono il Merchant ID e il segreto (password per la comunicazione in background) della connessione del tuo negozio nel portale clienti di Comgate, nonché l'URL di notifica impostato lì (vedi Configurazione). Comgate usa lo stesso Merchant ID e lo stesso segreto per i pagamenti di test e quelli reali.

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 Comgate 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 il Merchant ID e il Secret dal portale clienti di Comgate e imposta lì l'URL di notifica (vedi Configurazione).

5. Attiva Enable / Disable e clicca su Save. Lascia attivo Test Mode per un pagamento di prova, poi disattivalo.

All'installazione il modulo crea lo stato dell'ordine Comgate 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.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Comgate Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa se Comgate è attivo ma manca il Merchant ID o il segreto (in tal caso il metodo di pagamento è nascosto al checkout finché entrambi non vengono compilati) e se la valuta predefinita del negozio non è supportata da Comgate. Mentre la modalità test è attiva, mostra Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.

Comgate

Enable / Disable: Enable Comgate Payment Gateway attiva o disattiva il metodo di pagamento. Default: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Default: Comgate. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Default: Pay securely via Comgate — cards, bank transfers, wallets and more. In modalità test viene aggiunto TEST MODE: no real money is charged., oppure viene mostrato da solo se la descrizione è vuota.

Connessione Comgate

Prendi l'identificativo del negozio (Merchant ID) e la password (segreto) dal portale clienti di Comgate, Integration > shop connection settings. Nello stesso punto imposta la URL for passing the payment result (notifica in background) sull'URL mostrato in Notification URL in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_comgate_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni. Comgate lo richiama dopo ogni pagamento; il modulo poi ricontrolla il pagamento con l'API di stato di Comgate prima di modificare qualsiasi cosa. Gli URL di ritorno per il cliente vengono inviati con ogni pagamento. Se il portale richiede anche gli URL di ritorno (pagato, annullato, in sospeso), usa il secondo URL mostrato in questa sezione, che termina con return?id=${id}&refId=${refId}.

Merchant ID: l'identificativo del negozio (merchant) su Comgate.

Secret: la password per la comunicazione in background (segreto) di questa connessione del negozio. Un segreto salvato non viene mai mostrato di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Cancella il segreto salvato: spunta la casella e clicca su Save per rimuovere il segreto salvato. Un campo vuoto mantiene il valore salvato.

Test Mode: crea pagamenti di prova (non viene addebitato nessun importo). Comgate usa lo stesso Merchant ID e lo stesso segreto per i pagamenti di test e quelli reali; i pagamenti di test sono contrassegnati con test=true. I rimborsi vengono sempre inviati nella modalità del pagamento originale. Default: on.

Pagina di pagamento

Payment Methods: quali metodi di pagamento Comgate può scegliere il cliente. Vengono mostrati solo i metodi attivi per il tuo negozio in Comgate.

Language: la lingua della pagina di pagamento Comgate. Automatic (shop language, English as fallback) (predefinita) oppure una delle 26 lingue disponibili.

Ordini

Order Status After Payment: lo stato impostato quando Comgate conferma il pagamento.

I pagamenti che non corrispondono all'ordine, i pagamenti di test in modalità live e i pagamenti pre-autorizzati vanno sempre in Comgate payment on hold.

Avanzate

Debug Log: scrive richieste API e notifiche in logs/comgate_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Il segreto e i dati personali non vengono mai registrati. Gli errori vengono sempre registrati. Default: off.

Log: mostra le dimensioni e le ultime voci del registro. Clicca su Clear log per svuotarlo.

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. Gli ordini e i loro ID di transazione Comgate vengono sempre conservati. Default: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Comgate) e conferma l'ordine. Il modulo crea il pagamento su Comgate per il totale del carrello nella valuta del carrello e reindirizza il cliente alla pagina di pagamento di Comgate. L'indirizzo e-mail e il nome del cliente vengono passati a Comgate, e il pagamento è etichettato come Cart con il numero del carrello. È richiesto un indirizzo e-mail valido. Sulla pagina di Comgate il cliente paga con uno dei metodi che hai consentito. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Comgate: il modulo legge il pagamento dall'API di stato di Comgate, sia quando arriva la notifica in background sia quando il cliente ritorna. L'ordine viene poi creato e il cliente vede la pagina standard di conferma dell'ordine. Se l'ordine è stato messo in sospeso, la pagina aggiunge Your payment is being reviewed. We will contact you if anything else is needed. Se un ordine pre-autorizzato è stato annullato successivamente, la pagina mostra Your Comgate payment was not completed. Please contact us about this order.

Se il pagamento non è ancora confermato quando il cliente ritorna, per esempio un bonifico bancario in corso, una pagina Payment confirmation mostra Comgate has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. con un pulsante Check again e un pulsante Back to checkout.

Se il pagamento viene annullato o scade, il cliente torna al checkout con The Comgate payment was cancelled or has expired. You can try again or choose another payment method. Il carrello viene conservato. Ogni nuovo tentativo controlla prima il precedente, così un pagamento già andato a buon fine non viene addebitato due volte, e il tentativo precedente viene annullato su Comgate se è ancora aperto. Un pagamento tardivo di un tentativo più vecchio crea comunque l'ordine.

Se Comgate non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio The Comgate payment could not be started. Please try again or choose another payment method., che Comgate non può accettare questo importo o questa valuta, oppure che il metodo di pagamento Comgate selezionato non è disponibile. Il motivo tecnico viene scritto nel registro.

La notifica funziona anche quando il negozio è in modalità manutenzione e non viene bloccata dalla restrizione per paese del tuo negozio.

Il modulo gestisce pagamenti una tantum solo sulla pagina di Comgate. Non prevede pagamenti ricorrenti, abbonamenti o carte salvate, né checkout Comgate integrato, né pulsanti Apple Pay o Google Pay sul tuo sito (sono disponibili nella pagina di Comgate), né cattura o annullamento delle pre-autorizzazioni da PrestaShop. Senza la notifica, lo stato del pagamento non viene verificato automaticamente; viene controllato solo quando il cliente ritorna.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Comgate e non ha ancora pagato, oppure Comgate segnala il pagamento come in attesa. Esiste solo il carrello.

Payment accepted or Delivered: Comgate ha segnalato il pagamento come PAID con lo stesso importo e la stessa valuta. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID di transazione Comgate. I pagamenti di test ricevono la nota Comgate test payment — no money was charged.

Comgate payment on hold: l'importo o la valuta pagati non corrispondono all'ordine, un pagamento di test è stato confermato con il negozio in modalità live (nessun denaro ricevuto), oppure il pagamento è solo autorizzato (pre-autorizzazione sul tuo account Comgate). Un pagamento autorizzato diventa pagato automaticamente quando lo catturi nel portale Comgate. La nota spiega il motivo.

Canceled: un pagamento autorizzato è stato annullato o è scaduto su Comgate. Se Comgate conferma il pagamento in seguito, l'ordine viene riaperto come pagato con una nota che ti invita a verificare la disponibilità prima della spedizione.

Refunded: il pagamento è stato rimborsato interamente tramite il modulo.

Se Comgate segnala un altro pagamento PAID per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di verificarlo nel portale Comgate e di rimborsare il duplicato. Una conferma riprodotta non riapre mai un ordine rimborsato.

Blocco pagamento Comgate

La pagina dell'ordine mostra un blocco Comgate payment con l'ID di transazione, lo stato Comgate, l'importo pagato, il totale dell'ordine e l'importo rimborsato, un badge Test mode per i pagamenti di test, il motivo di una verifica, lo storico dei rimborsi e le Comgate notes dell'ordine.

Rimborsi

Nel blocco Comgate payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Comgate. Conferma la domanda Refund this amount through Comgate? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei Moduli. Il rimborso va alla transazione Comgate pagata ed è inviato nella modalità (test o live) del pagamento originale. Comgate rimborsa solo pagamenti PAID e al massimo l'importo pagato; i rimborsi in HUF devono essere in fiorini interi. Se Comgate 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 con importo, transazione Comgate e motivo. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

I rimborsi sono disponibili solo per gli ordini pagati. Un ordine in sospeso dopo una differenza di importo o valuta non può essere rimborsato da PrestaShop; rimborsalo nel portale Comgate. Il modulo non crea note di credito. I normali pulsanti di rimborso di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Comgate. I rimborsi effettuati nel portale Comgate non vengono segnalati al negozio.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Comgate Gateway è il primo blocco di Modules > Module Manager > VibeFox Comgate 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 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 ci sono la riga Product: presta-payment-comgate 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 cambiare 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 spiega 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: quello 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, Comgate 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. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Comgate non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che Merchant ID e Secret siano compilati, che la valuta del carrello sia supportata e che il totale dell'ordine non sia inferiore al minimo di Comgate (per esempio 1 CZK, 0,10 EUR o 100 HUF). 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: Comgate non ha consegnato la notifica in background. Controlla la URL for passing the payment result nel portale Comgate (esattamente la Notification URL delle impostazioni), che il tuo negozio sia raggiungibile via HTTPS da internet e il registro (attiva Debug Log). Comgate ripete le notifiche non consegnate; il modulo risponde con un errore ogni volta che non ne ha elaborata una, quindi verrà riprovata. L'ordine viene creato anche quando il cliente torna nel negozio.

La notifica risponde Invalid merchant or secret: il Merchant ID o il segreto nelle impostazioni non corrispondono alla connessione del negozio nel portale Comgate.

La notifica risponde Gateway not configured: il Merchant ID o il segreto nelle impostazioni è vuoto. Comgate riprova quando vengono compilati.

La notifica risponde Unknown transaction, Order not found o Reference mismatch: la notifica riguarda un pagamento che questo negozio non ha creato per quel carrello. Non viene modificato nulla.

La notifica risponde Status verification failed, Status verification rejected o Busy, retry later: l'API di stato di Comgate non è raggiungibile, ha rifiutato la richiesta, oppure il carrello era in elaborazione da un'altra richiesta nello stesso momento. Busy è anche la risposta quando non è stato possibile creare l'ordine; il motivo è nel registro. Comgate riprova la notifica.

L'URL di notifica mostra code=1&message=POST%20required nel browser: è normale. L'URL accetta solo richieste da Comgate.

Il cliente vede We could not verify the Comgate payment: il link di ritorno non corrispondeva al carrello. Se il denaro è stato addebitato, la notifica crea comunque l'ordine. Controlla il pagamento nel portale Comgate prima che il cliente paghi di nuovo.

Il cliente vede The order total is below the minimum amount accepted by Comgate oppure A valid billing e-mail address is required for Comgate payments: il carrello non può essere pagato con Comgate così com'è.

L'ordine è in Comgate payment on hold dopo il pagamento: leggi le note nel blocco Comgate payment. L'importo o la valuta pagati erano diversi, è arrivato un pagamento di test in modalità live, oppure il pagamento è solo autorizzato. Controlla il pagamento nel portale Comgate e completa o rimborsa l'ordine manualmente.

Il rimborso non riesce: leggi il messaggio nel blocco. Comgate rejected the refund: the amount exceeds the refundable amount. significa che l'importo è superiore a quanto resta da rimborsare; un pagamento in uno stato diverso da PAID non può essere rimborsato. Comgate could not be reached. The refund was not made — please try again later. indica un problema di connessione.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Comgate 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 reinstallazione successiva. Le transazioni e i rimborsi Comgate e lo stato dell'ordine Comgate payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.

Comgate è un marchio registrato del suo rispettivo titolare. Questo modulo non è affiliato a Comgate né approvato da Comgate.