VibeFox Montonio 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.

Valuta: la valuta del carrello deve essere EUR o PLN. Per qualsiasi altra valuta il metodo di pagamento è nascosto nel checkout.

Account Montonio: ti servono la chiave di accesso e la chiave segreta del tuo negozio dal Montonio Partner System. Le chiavi sandbox e quelle live sono diverse, quindi ti serve una coppia per ogni ambiente che usi. Non c'è altro da configurare in Montonio: l'indirizzo di notifica viene inviato con ogni pagamento.

Sito pubblico: il tuo negozio deve essere raggiungibile da internet per ricevere le notifiche di Montonio. Altrimenti gli ordini vengono comunque creati quando il cliente torna al negozio.

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 Montonio Payment nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in cima alla pagina Configure, poi fai clic su Activate (vedi Chiave di licenza).

4. Nel Montonio Partner System apri Stores > your store > API keys e copia la chiave di accesso e la chiave segreta sandbox. Incollale nelle impostazioni e lascia attivo Sandbox mode.

5. Attiva Enable/Disable, fai clic su Save e prova un pagamento in sandbox. Poi inserisci le chiavi live e disattiva Sandbox mode.

All'installazione il modulo crea lo stato dell'ordine Montonio payment on hold. PrestaShop offre 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 Montonio Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando mancano le chiavi dell'ambiente attuale (il metodo di pagamento viene allora nascosto nel checkout), quando la valuta del negozio non è EUR o PLN, e mostra Sandbox mode is on: payments are simulated and no real money is charged. finché la sandbox è attiva. Title non può essere vuoto.

Montonio

Enable/Disable: Enable Montonio bank payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono nel checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Bank payment (Montonio). Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay directly from your bank account. You will be redirected to Montonio to choose your bank.

Chiavi API

Ottieni le chiavi nel Montonio Partner System, in Stores > your store > API keys. Le chiavi sandbox e quelle live sono diverse. La sandbox usa solo le chiavi sandbox, la modalità live solo le chiavi live.

Sandbox mode: usa la sandbox di Montonio (pagamenti di prova, nessun denaro reale). Cambia sia l'indirizzo API di Montonio sia la coppia di chiavi. Predefinito: attivo. Disattivalo solo dopo aver inserito le chiavi live. I pagamenti effettuati nell'altro ambiente continuano a usare le chiavi del proprio ambiente per conferme e rimborsi.

Sandbox access key: la chiave di accesso (UUID) del tuo negozio nella sandbox di Montonio.

Sandbox secret key: la chiave segreta del tuo negozio nella sandbox di Montonio.

Live access key: la chiave di accesso (UUID) del tuo negozio nell'ambiente live di Montonio.

Live secret key: la chiave segreta del tuo negozio nell'ambiente live di Montonio.

Le chiavi segrete salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.

Clear saved secret keys: spunta una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notification URL: l'indirizzo a cui Montonio invia le notifiche di pagamento. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_montonio_payment/webhook. Non devi inserirlo da nessuna parte: il modulo lo invia a Montonio con ogni pagamento.

Avanzate

Debug log: scrive gli eventi di pagamento in logs/wc_mnt_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, token e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro. Fai clic su Clear log per svuotarlo.

Delete data: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo e il suo registro. Disattivare il modulo non elimina mai nulla. I dati degli ordini (UUID Montonio, note) vengono sempre conservati. Predefinito: disattivato.

Notifiche di pagamento

Montonio informa il tuo negozio di ogni pagamento con un token firmato. Il token arriva in due modi: con una notifica server-to-server all'URL di notifica e con il cliente quando torna al negozio. Vengono verificati entrambi: la firma con la chiave segreta dell'ambiente in cui è stato creato il pagamento, la data di scadenza, la tua chiave di accesso e il fatto che il pagamento sia stato creato dal tuo negozio per quel carrello. Un token firmato con la chiave dell'altro ambiente viene rifiutato. Ogni stato viene applicato una sola volta, quindi le notifiche ripetute non aggiungono note, e-mail o variazioni di magazzino. L'URL di notifica funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Bank payment (Montonio)) e conferma. Il modulo crea un pagamento Montonio per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento di Montonio. Lì il cliente sceglie una banca e paga. Le banche del paese di fatturazione del cliente vengono mostrate per prime (per i carrelli in PLN, la Polonia). Il pagamento compare come Order e il numero del carrello. La pagina di Montonio si apre nella lingua del negozio se è tedesco, inglese, estone, finlandese, lituano, lettone, polacco o russo; altrimenti in inglese. In modalità sandbox il checkout mostra SANDBOX MODE — test payment, no real money is charged. sotto la descrizione. In questa fase non esiste ancora alcun ordine.

L'ordine viene segnato come pagato solo dopo che Montonio lo ha confermato: con la notifica o con il ritorno del cliente. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your Montonio bank payment has been received. Se la banca non ha ancora confermato il pagamento, o l'ordine è in attesa, la pagina mostra We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. Se la banca rifiuta in seguito un pagamento autorizzato, la pagina mostra Your Montonio payment was not completed. Please contact us about this order.

Se Montonio segnala che il pagamento è ancora in sospeso quando il cliente torna, una pagina Payment confirmation mostra lo stesso testo e un pulsante Check again. Il pulsante chiede a Montonio lo stato attuale del pagamento. La notifica crea l'ordine non appena arriva.

Se il pagamento è stato annullato o rifiutato, il cliente torna al checkout con uno di questi messaggi: The payment was cancelled or rejected by the bank. You can try again or choose another payment method., The payment was not completed. You can try again or choose another payment method. oppure Montonio could not complete the payment. Please try again or choose another payment method. Il carrello viene mantenuto. Prima di creare un nuovo pagamento, il modulo chiede a Montonio informazioni su quello precedente. Se è già pagato, l'ordine viene creato e non viene effettuato un secondo pagamento.

Se Montonio non riesce ad avviare il pagamento, il cliente resta nel checkout con un breve messaggio, ad esempio Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method. Il motivo tecnico viene scritto nel registro.

Il modulo accetta solo pagamenti bancari (avvio del pagamento). Non prevede pagamenti con carta, BLIK, Apple Pay o Google Pay, Pay Later o finanziamenti, spedizioni Montonio, abbonamenti, metodi di pagamento salvati né la scelta della banca sul tuo sito.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Montonio e non ha pagato, oppure Montonio segnala il pagamento come in sospeso. Esiste solo il carrello.

Payment accepted: Montonio ha confermato il pagamento (PAID) con l'importo e la valuta esatti del carrello. Il pagamento viene registrato con l'UUID dell'ordine Montonio come ID transazione, e una nota mostra la banca, l'UUID, l'importo e l'ambiente.

Montonio payment on hold: la banca non ha ancora confermato il pagamento (AUTHORIZED); l'ordine diventa Payment accepted quando Montonio segnala PAID. Un ordine viene anche messo in attesa quando Montonio ha segnalato un importo o una valuta diversi dal totale del carrello, quando è arrivato un pagamento in sandbox mentre il negozio è in modalità live (nessun pagamento viene registrato, perché non è stato ricevuto denaro), o quando il pagamento è arrivato dopo che l'ordine era stato annullato. La nota lo spiega. Controlla il pagamento nel Montonio Partner System ed evadi l'ordine oppure rimborsa il pagamento.

Payment error: la banca ha rifiutato un pagamento autorizzato, oppure il cliente non lo ha completato. Solo l'ultimo pagamento del carrello può modificare l'ordine.

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

Gli ordini pagati, annullati o rimborsati non vengono mai riaperti dalle notifiche successive. Se per un ordine già pagato arriva un secondo pagamento, l'ordine non viene modificato. Una nota ti chiede di rimborsare il secondo pagamento nel Montonio Partner System.

Blocco Montonio payment

La pagina dell'ordine mostra un blocco Montonio payment con l'UUID dell'ordine Montonio, l'ambiente (con un badge Sandbox per i pagamenti di prova), la banca, lo stato del pagamento, l'importo pagato e rimborsato, lo storico dei rimborsi e le Montonio notes dell'ordine.

Rimborsi

Nel blocco Montonio payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo (viene conservato solo nella nota dell'ordine), e fai clic su Refund via Montonio. Conferma la domanda Refund this amount through Montonio? 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. I rimborsi sono limitati all'importo addebitato da Montonio, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato all'ambiente in cui è stato effettuato il pagamento (sandbox o live), quindi le chiavi di quell'ambiente devono essere impostate. Se Montonio non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso inviato viene aggiunto allo storico dei rimborsi e alle note con il suo stato e l'ID di rimborso Montonio. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili quando Montonio ha segnalato il pagamento come pagato.

Montonio conferma o rifiuta ogni rimborso in seguito, con una notifica. Una conferma viene aggiunta alle note. Se Montonio rifiuta il rimborso, la nota indica che il denaro non è stato restituito al cliente; verificalo nel Montonio Partner System e correggi il rimborso in PrestaShop.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Montonio. I rimborsi effettuati nel Montonio Partner System vengono aggiunti alle note quando Montonio li segnala. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente. Aggiornali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Montonio Payment è il primo blocco nella pagina Modules > Module Manager > VibeFox Montonio Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, 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 ricontrollare 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-montonio 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 incluse 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, 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 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, Montonio non viene mostrato ai clienti nel checkout. Se comunque viene avviato un pagamento, 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 è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo nel 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Montonio non appare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che siano impostate entrambe le chiavi dell'ambiente attuale (Sandbox access key e Sandbox secret key in modalità sandbox, Live access key e Live secret key in modalità live) e che la valuta del carrello sia EUR o PLN. La pagina delle impostazioni mostra un avviso quando mancano chiavi o quando la valuta del negozio non è supportata. 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: la notifica non è arrivata al tuo negozio. Verifica che il negozio sia raggiungibile da internet e che le chiavi nelle impostazioni appartengano all'ambiente del pagamento. L'ordine viene creato anche quando il cliente torna al negozio dopo aver pagato, quando il cliente fa clic su Check again e quando il cliente prova a pagare di nuovo lo stesso carrello.

La notifica risponde Invalid token: firma, scadenza o chiave di accesso del token non corrispondevano. Verifica che chiave di accesso e chiave segreta siano copiate correttamente e appartengano all'ambiente giusto, e che l'orologio del server sia corretto. Anche un token firmato con la chiave dell'altro ambiente viene rifiutato.

La notifica risponde Payment does not belong to this order: il pagamento non è stato creato da questo negozio per questo carrello. Succede quando due negozi usano lo stesso account Montonio e gli stessi numeri di carrello.

La notifica risponde Gateway not configured: non sono impostate chiavi Montonio, oppure mancano le chiavi dell'ambiente del pagamento. Inserisci le chiavi; Montonio riprova la notifica.

La notifica risponde Temporarily unavailable: il carrello era in fase di conferma da un'altra richiesta nello stesso momento, oppure l'ordine non ha potuto essere creato (per esempio perché il modulo è disattivato). Montonio riprova la notifica. Controlla il campo Log per il motivo.

Il cliente vede un errore scegliendo Montonio: controlla il campo Log nella pagina del modulo. This payment method is temporarily unavailable. Please choose another payment method. di solito indica chiavi errate o mancanti. Montonio could not start the payment. Please check your order details or choose another payment method. significa che Montonio ha rifiutato i dati del pagamento; il registro contiene il motivo.

L'ordine è in Montonio payment on hold dopo il pagamento: leggi le note nel blocco Montonio payment (vedi Stati dell'ordine), poi evadi l'ordine oppure rimborsa il pagamento.

I pagamenti in sandbox non confermano un ordine live: un pagamento in sandbox non completa mai un ordine mentre il negozio è in modalità live; l'ordine viene invece messo in attesa. Imposta Sandbox mode sull'ambiente che desideri e usa le chiavi di quell'ambiente.

Il rimborso fallisce con un messaggio sull'ambiente: il pagamento è stato effettuato nell'ambiente sandbox o live, e le chiavi di quell'ambiente non sono impostate. Inseriscile e riprova.

Per gli sviluppatori, il modulo offre gli hook actionWcpMontonioSupportedCurrencies, actionWcpMontonioOrderData e actionWcpMontonioLocale per modificare le valute supportate, i dati di pagamento e la lingua della pagina di Montonio.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Montonio Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data è attivo, vengono rimosse le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I record dei pagamenti e dei rimborsi Montonio e lo stato dell'ordine Montonio 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 transazione.

Montonio è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da Montonio.