VibeFox PayMongo for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni di PHP più vecchie.
Valuta: peso filippino (PHP). PayMongo viene mostrato al checkout solo per i carrelli in PHP. Se la valuta predefinita del negozio non è PHP, la pagina delle impostazioni ti avvisa e i clienti devono passare a PHP per vedere PayMongo.
Account PayMongo: ti servono le chiavi API segrete del tuo account PayMongo e un webhook per ciascuna modalità (vedi Configurazione). Vengono usate solo le chiavi segrete (sk_test_..., sk_live_...) e i segreti di firma dei webhook (whsk_...). Le chiavi pubbliche non servono, perché la pagina di pagamento è ospitata da PayMongo. I metodi di pagamento che offri devono essere attivati nel tuo account PayMongo.
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 PayMongo Payment Gateway 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. Incolla le chiavi segrete PayMongo, crea i webhook in PayMongo e incolla i loro segreti di firma (vedi Configurazione).
5. Seleziona i metodi di pagamento, attiva Enable/Disable e fai clic su Save. Prova un pagamento con Test mode attivo, poi disattivalo.
All'installazione il modulo crea due stati dell'ordine, Awaiting PayMongo payment e PayMongo payment on hold. In Payment > Preferences verifica che il modulo sia consentito per il peso filippino, i paesi dei tuoi clienti e i loro gruppi di clienti.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando la valuta predefinita del negozio non è PHP, quando la modalità attuale non ha una chiave segreta (PayMongo non viene quindi mostrato al checkout) o nessun segreto di webhook (i pagamenti vengono quindi confermati solo quando il cliente torna nel tuo negozio), e mostra Test mode is on: no real payments are made. finché la modalità test è attiva.
PayMongo
Enable/Disable: Enable PayMongo attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo salvato nell'ordine. Predefinito: PayMongo (Card, GCash, GrabPay, Maya). Obbligatorio.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.
Payment methods: i metodi offerti sulla pagina di checkout di PayMongo. Seleziona solo i metodi attivati nel tuo account PayMongo, altrimenti PayMongo rifiuta il checkout. Se non ne selezioni nessuno, vengono usati quelli predefiniti. Predefinito: Cards, GCash, GrabPay and Maya.
Chiavi API
Copia le chiavi segrete da PayMongo Dashboard > Developers > API keys. Le chiavi pubbliche non servono. Ogni chiave deve iniziare con il prefisso previsto. Un valore con un prefisso errato non viene salvato: la pagina mostra che il campo must start with il prefisso e che The previous value was kept.
Test mode: Enable test mode (no real payments). I nuovi pagamenti usano le chiavi di test. I pagamenti effettuati in precedenza mantengono la modalità in cui sono stati fatti, quindi i controlli di stato e i rimborsi usano la chiave corrispondente. Predefinito: attivo. Disattivalo per accettare pagamenti reali.
Test secret key: la chiave segreta della modalità test. Inizia con sk_test_.
Test webhook secret: il segreto di firma del webhook della modalità test. Inizia con whsk_.
Live secret key: la chiave segreta della modalità live. Inizia con sk_live_.
Live webhook secret: il segreto di firma del webhook della modalità live. Inizia con whsk_.
Le chiavi e i segreti salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarlo.
Clear saved secrets: seleziona una chiave o un segreto e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.
Webhook
Il webhook comunica al tuo negozio che un pagamento è stato effettuato, anche quando il cliente chiude il browser dopo aver pagato. Crea un webhook nella dashboard di PayMongo (o tramite l'API di PayMongo) per ciascuna modalità, test e live, con l'URL mostrato in Webhook URL in questa sezione. Con URL parlanti ha questo aspetto https://your-shop/module/wcp_paymongo_payment_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni.
Seleziona questi eventi (sono elencati anche in questa sezione):
Copia il segreto di firma (whsk_...) di ogni webhook in Test webhook secret o Live webhook secret. I webhook senza una firma valida vengono rifiutati. La firma viene verificata con il segreto della propria modalità, e la modalità dell'evento deve corrispondere, così un webhook di test non conferma mai un pagamento live. Ogni evento viene ricontrollato tramite l'API di PayMongo con la chiave segreta della modalità del pagamento prima che un ordine venga creato o modificato. PayMongo invia gli eventi dell'intero account a ogni webhook; gli eventi di pagamenti non avviati in questo negozio vengono ignorati. Senza webhook, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.
Ordini
Order status after payment: lo stato dell'ordine impostato dopo un pagamento riuscito.
I pagamenti ancora in elaborazione restano in Awaiting PayMongo payment. Le discrepanze di importo o valuta e i pagamenti di test su un negozio live vanno sempre in PayMongo payment on hold.
Avanzate
Debug log: registra le chiamate all'API di PayMongo e gli eventi dei webhook in logs/paymongo_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando l'interruttore è disattivato. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: disattivato.
Log: mostra la dimensione e le ultime voci del log. Fai clic su Clear log per svuotarlo.
Delete data on uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni e il log. Gli ID PayMongo salvati per gli ordini, i rimborsi e gli stati dell'ordine del modulo vengono sempre conservati, perché servono per i rimborsi e la contabilità. Predefinito: disattivato.
Checkout
Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita PayMongo (Card, GCash, GrabPay, Maya)) e ne vede la descrizione. In modalità test il checkout mostra anche Test mode: no real payment will be made. PayMongo viene offerto solo per i carrelli in PHP con un totale di almeno ₱100,00.
Dopo la conferma, il modulo crea una Checkout Session di PayMongo per il totale del carrello in PHP, con una riga Cart # e il numero del carrello, e invia il cliente alla pagina di checkout di PayMongo. Nome, e-mail, telefono e indirizzo di fatturazione del cliente vengono passati a PayMongo. Lì il cliente sceglie uno dei metodi selezionati e paga. 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 PayMongo: il modulo interroga l'API di PayMongo sul pagamento quando il cliente torna e quando arriva il webhook. Solo allora l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your PayMongo payment has been received. Se PayMongo sta ancora elaborando il pagamento quando il cliente torna, l'ordine viene creato in Awaiting PayMongo payment e la pagina mostra PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. Se quel pagamento fallisce in seguito, la pagina mostra Your PayMongo payment was not completed. Please contact us about this order. Se PayMongo non è raggiungibile quando il cliente torna, una pagina Payment confirmation chiede al cliente di non pagare di nuovo e mostra un pulsante Check again; il webhook crea l'ordine appena arriva.
Se il cliente annulla nella pagina di PayMongo o non completa il pagamento, torna al checkout con You cancelled the PayMongo payment. You can try again or choose another payment method. oppure Your PayMongo payment was not completed. You can try again or choose another payment method. Il carrello viene conservato. Un nuovo tentativo controlla prima quello precedente: se nel frattempo è stato pagato, l'ordine viene creato senza un nuovo pagamento; altrimenti il link di checkout PayMongo precedente scade, così il carrello non può essere pagato due volte. Mentre il pagamento precedente è ancora in elaborazione, il cliente vede Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.
Se PayMongo non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio The payment could not be started. Please try again or choose another payment method. oppure PayMongo could not be reached. Please try again in a moment. Il motivo tecnico viene scritto nel log.
Il webhook funziona anche mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.
Il modulo accetta pagamenti una tantum nella pagina di PayMongo. Non ha campi per la carta nella tua pagina di checkout, né carte salvate, abbonamenti o pagamenti ricorrenti, rate, né autorizzazione e cattura separate.
Ordini e rimborsi
Stati dell'ordine
No order yet: il cliente è stato inviato a PayMongo e non ha ancora pagato, oppure PayMongo non ha ancora confermato il pagamento. Esiste solo il carrello.
Payment accepted or Delivered: il pagamento è stato confermato. Lo stato segue Order status after payment. Il pagamento viene registrato con l'ID di pagamento PayMongo (pay_...) come ID transazione, e una nota mostra il pagamento, l'importo, il metodo, la modalità e come è stato confermato (webhook o ritorno).
Awaiting PayMongo payment: il cliente è tornato mentre PayMongo stava ancora elaborando il pagamento. L'ordine passa allo stato di pagato quando PayMongo lo conferma.
PayMongo payment on hold: l'importo o la valuta pagati non corrispondono al totale del carrello (per esempio, il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento); oppure un pagamento è stato effettuato in modalità test mentre il negozio era in modalità live, quindi non è stato ricevuto denaro e nessun pagamento viene registrato; oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota lo spiega. Controlla l'ordine e gestiscilo oppure rimborsa il pagamento.
Payment error: un webhook payment.failed firmato ha segnalato che l'ultimo tentativo di pagamento di un ordine in Awaiting PayMongo payment è fallito. La nota mostra il codice e il messaggio di errore di PayMongo. Se lo stesso pagamento riesce più tardi, l'ordine passa allo stato di pagato.
Refunded: il pagamento è stato rimborsato interamente tramite il modulo.
Se arriva un secondo pagamento per un ordine già pagato, per esempio tramite un vecchio link di checkout, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato nella dashboard di PayMongo. Un ordine pagato e poi annullato o rimborsato non viene mai riaperto.
Blocco PayMongo payment
La pagina dell'ordine mostra un blocco PayMongo payment con l'ID del pagamento PayMongo e il metodo, il payment intent, il checkout, la modalità, lo stato, l'importo pagato e l'importo rimborsato, un badge Test mode per i pagamenti di test, le note PayMongo dell'ordine e lo storico dei rimborsi.
Rimborsi
Nel blocco PayMongo payment inserisci l'importo (viene precompilato quello non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via PayMongo. Conferma la domanda Refund this amount through PayMongo? This cannot be undone. Sono supportati rimborsi totali e parziali, con al massimo due decimali. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine dei moduli. I rimborsi sono limitati all'importo effettivamente addebitato da PayMongo, quindi dopo una discrepanza di importo puoi rimborsare fino a quanto ha pagato il cliente, non il totale dell'ordine. Il rimborso viene inviato con la chiave segreta della modalità in cui è stato effettuato il pagamento (test o live), quindi quella chiave deve essere impostata. Il motivo che inserisci viene inviato a PayMongo come nota di rimborso. Se PayMongo 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 l'ID e lo stato del rimborso PayMongo. 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 rimandano denaro tramite PayMongo. I rimborsi effettuati nella dashboard di PayMongo non vengono copiati in PrestaShop. Rimborsa dal blocco dell'ordine, oppure aggiorna l'ordine manualmente.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox PayMongo Payment Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di ciò 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 verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto si trovano la riga Product: presta-payment-paymongo 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 una modifica dell'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. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, PayMongo 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 è 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 un 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 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
PayMongo non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità attuale abbia una chiave segreta (Test secret key in modalità test, Live secret key in modalità live), che il carrello sia in PHP e che il totale sia di almeno ₱100,00. 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: il webhook non funziona e il cliente non è tornato nel negozio. Nella dashboard di PayMongo verifica che esista un webhook nella modalità che usi, che il suo URL sia esattamente quello mostrato in Webhook URL e che siano selezionati i tre eventi. Verifica che il suo segreto di firma sia nel campo giusto (Test webhook secret o Live webhook secret).
Il webhook risponde Invalid signature: il segreto di firma di quella modalità manca oppure appartiene a un altro webhook. Incolla il segreto di firma del webhook nel campo della sua modalità.
Il webhook risponde Mode mismatch: un evento di test è stato firmato come live o viceversa. Verifica che ogni webhook appartenga alla modalità giusta.
Il webhook risponde Temporary error: il pagamento non è stato possibile verificarlo tramite l'API di PayMongo, per esempio perché manca la chiave segreta della modalità del pagamento. PayMongo ripete automaticamente il webhook.
Il webhook risponde Busy, retry: l'ordine era in conferma da un'altra richiesta nello stesso momento, oppure l'ordine non è potuto essere creato (per esempio perché il modulo è disattivato). PayMongo ripete automaticamente il webhook. Il motivo è nel Log.
Il webhook risponde Ignored: l'evento appartiene a un pagamento non avviato in questo negozio, oppure a un'altra modalità. Non cambia nulla.
L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste da PayMongo.
Il valore non è stato salvato: una chiave è stata incollata nel campo sbagliato. Le chiavi segrete iniziano con sk_test_ o sk_live_, i segreti dei webhook con whsk_.
Il cliente vede un errore quando sceglie PayMongo: controlla il campo Log nella pagina del modulo. Una chiave segreta errata dà il messaggio che il metodo di pagamento è temporaneamente non disponibile. Un metodo di pagamento non attivato nel tuo account PayMongo fa rifiutare il checkout a PayMongo; rimuovilo da Payment methods.
Pagamenti di test su un negozio live: un pagamento di test arrivato mentre il negozio è in modalità live mette l'ordine in PayMongo payment on hold con una nota che indica che non è stato ricevuto denaro. I pagamenti reali vengono sempre riconosciuti, anche dopo il ritorno alla modalità test, e vengono rimborsati con la chiave live.
Ordine in PayMongo payment on hold dopo il pagamento: leggi le note nel blocco PayMongo payment (vedi Stati dell'ordine), poi gestisci l'ordine oppure rimborsa il pagamento.
Il rimborso fallisce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e la chiave segreta di quella modalità non è impostata. Inseriscila e riprova.
Gli sviluppatori possono modificare i dati della Checkout Session con l'hook actionPaymongoPCheckoutSessionData.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox PayMongo Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre eliminati. Se Delete data on uninstall è attivo, vengono eliminati le impostazioni e il log. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Gli ID PayMongo degli ordini, i rimborsi e gli stati dell'ordine Awaiting PayMongo payment e PayMongo payment on hold vengono sempre conservati, così gli ordini pagati prima possono essere ancora rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.
PayMongo è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da PayMongo.