VibeFox PayMongo for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Valuta: peso filippino (PHP). Il metodo di pagamento viene nascosto quando la valuta del negozio, o la valuta dell'ordine nella pagina Pay for order, non è PHP.

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 sono necessarie, 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 solo dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_paymongo_payment_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > PayMongo > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Incolla le tue chiavi segrete PayMongo, crea i webhook e incolla i loro segreti di firma (vedi Configurazione).

6. Seleziona i metodi di pagamento, attiva Enable/Disable e salva. Prova un pagamento con Test mode attivo, poi disattivalo.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > PayMongo. Sopra i campi, la pagina ti avvisa quando la valuta del negozio non è PHP, quando la modalità corrente non ha una chiave segreta (in tal caso PayMongo non viene mostrato al checkout) o nessun segreto del webhook (in tal caso i pagamenti vengono confermati solo al ritorno del cliente), e mostra Test mode is on: no real payments are made. finché la modalità test è attiva. Nell'elenco dei metodi di pagamento, PayMongo è contrassegnato come da configurare finché la modalità corrente non ha una chiave segreta.

Generale

Enable/Disable: Enable PayMongo attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: PayMongo (Card, GCash, GrabPay, Maya).

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 PayMongo. Seleziona solo i metodi attivati per il tuo account PayMongo, altrimenti PayMongo rifiuta il checkout. Predefinito: Cards, GCash, GrabPay and Maya.

Chiavi API

Copia le chiavi segrete da PayMongo Dashboard > Developers > API keys. Le chiavi pubbliche non sono necessarie. Ogni chiave deve iniziare con il prefisso previsto. Un valore con un prefisso sbagliato 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 le verifiche di stato e i rimborsi usano la chiave corrispondente. Predefinito: attivo. Disattivala 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_.

Webhook

Il webhook informa il tuo negozio che un pagamento è stato effettuato, anche quando il cliente chiude il browser dopo aver pagato. Crea un webhook nella dashboard di PayMongo (oppure tramite l'API di PayMongo) per ciascuna modalità, test e live, con l'URL mostrato in questa sezione delle impostazioni. Ha questo formato: https://your-site/?wc-api=paymongo_p_webhook.

Seleziona questi eventi:

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, e la modalità dell'evento deve corrispondere a quella della firma. Ogni evento viene verificato di nuovo tramite l'API di PayMongo prima che l'ordine venga modificato. PayMongo invia gli eventi dell'intero account a ogni webhook; gli eventi di pagamenti non creati da questo negozio vengono ignorati. Senza il webhook, i pagamenti vengono confermati solo quando il cliente torna nel tuo negozio.

Ordini

Stato dell'ordine dopo il pagamento: lo stato dell'ordine impostato dopo un pagamento riuscito. Lo stato viene impostato subito, senza un secondo cambio di stato.

Avanzate

Debug log: Log API calls and webhook events le scrive in WooCommerce > Status > Logs, origine wcp_paymongo_payment_gateway. Gli errori vengono sempre registrati. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. Gli ID PayMongo salvati sugli ordini vengono conservati, perché servono per i rimborsi e la contabilità. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita PayMongo (Card, GCash, GrabPay, Maya)) e inoltra l'ordine. In modalità test il checkout mostra Test mode: no real payment will be made. Il plugin crea una sessione di checkout PayMongo per il totale dell'ordine in PHP, con una riga Order # e il numero dell'ordine, e invia il cliente alla pagina di checkout PayMongo. Nome, e-mail, telefono e indirizzo di fatturazione del cliente vengono trasmessi a PayMongo. Lì il cliente sceglie uno dei metodi selezionati e paga.

Il metodo di pagamento viene mostrato solo per ordini di almeno ₱100,00. Un totale inferiore non può essere pagato con PayMongo.

Dopo il pagamento, il cliente torna alla pagina di ordine ricevuto del tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di PayMongo: il plugin interroga l'API di PayMongo sul pagamento quando il cliente torna e quando arriva il webhook. Se PayMongo sta ancora elaborando il pagamento o non è raggiungibile, il cliente arriva comunque alla pagina di ordine ricevuto, e il webhook completa l'ordine più tardi.

Se il cliente annulla sulla pagina PayMongo o non completa il pagamento, arriva alla pagina Pay for order con il messaggio 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. L'ordine resta non pagato. Un nuovo tentativo controlla prima quello precedente: se nel frattempo è stato pagato, l'ordine viene completato senza un nuovo pagamento; altrimenti il link di checkout PayMongo precedente scade, così il cliente non può pagare 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 vede un breve messaggio, ad 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 aggiunto alle note dell'ordine.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta pagamenti una tantum sulla pagina PayMongo. Non ha campi per la carta nella tua pagina di checkout, né carte salvate, abbonamenti o pagamenti ricorrenti, né rate, né autorizzazione e cattura separate.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a PayMongo e non ha ancora pagato, oppure PayMongo non ha ancora confermato il pagamento. Una nota registra ogni sessione di checkout PayMongo creata per l'ordine. Mentre PayMongo elabora un pagamento, una nota lo indica.

Processing o Completed: il pagamento è stato confermato. Lo stato segue Order status after payment. La nota dell'ordine mostra il pagamento PayMongo, l'importo, il metodo e la modalità. L'ID transazione è l'ID del pagamento PayMongo (pay_...). La schermata dell'ordine mostra la sessione di checkout, l'intento di pagamento e la modalità PayMongo sotto l'indirizzo di fatturazione.

On hold: l'importo o la valuta pagati non corrispondono all'ordine (nota amount/currency mismatch); oppure un pagamento è stato effettuato in modalità test mentre il negozio è in modalità live, quindi non è stato ricevuto denaro; oppure il pagamento è arrivato dopo che l'ordine era stato annullato, ad esempio per la scadenza della prenotazione di scorta. La nota dell'ordine lo spiega. Controlla l'ordine e gestiscilo oppure rimborsa il pagamento.

Failed: un webhook payment.failed firmato ha segnalato che l'ultimo tentativo di pagamento di un ordine in sospeso non è riuscito. La nota mostra il codice e il messaggio di errore di PayMongo. Il cliente può pagare di nuovo.

Se arriva un secondo pagamento per un ordine già pagato, ad 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 annullato o rimborsato che era stato pagato non viene mai riaperto.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via PayMongo (Card, GCash, GrabPay, Maya) (il pulsante mostra il titolo del tuo metodo di pagamento). Sono supportati rimborsi totali e parziali. 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. Se PayMongo non accetta il rimborso, WooCommerce mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID e lo stato del rimborso PayMongo.

I rimborsi effettuati nella dashboard di PayMongo non vengono copiati in WooCommerce. Rimborsa dall'ordine di WooCommerce oppure crea un rimborso manuale in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > PayMongo. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Liberalo dal 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. I gestori del negozio che hanno effettuato l'accesso continuano a vedere il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

PayMongo non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia una chiave segreta (Test secret key in modalità test, Live secret key in modalità live), che la valuta del negozio sia PHP e che il totale dell'ordine sia di almeno ₱100,00. Gli sviluppatori possono cambiare il minimo con il filtro paymongo_p_minimum_amount.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: 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 nelle impostazioni e che siano selezionati i tre eventi. Verifica che il suo segreto di firma sia nel campo corrispondente (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 verificato tramite l'API di PayMongo, oppure l'ordine era in elaborazione da un'altra richiesta nello stesso momento. PayMongo ripete automaticamente il webhook.

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 invia l'ordine: apri le note dell'ordine oppure consulta WooCommerce > Status > Logs, origine wcp_paymongo_payment_gateway. Una chiave segreta errata mostra il messaggio che il metodo di pagamento non è temporaneamente disponibile. Un metodo di pagamento non attivato per il tuo account PayMongo fa rifiutare il checkout da PayMongo; rimuovilo da Payment methods.

Pagamenti di test su un negozio live: un pagamento di test ricevuto mentre il negozio è in modalità live mette l'ordine in attesa 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.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati non corrispondevano all'ordine, il pagamento era un pagamento di test oppure è arrivato dopo l'annullamento dell'ordine. Gestisci l'ordine o rimborsa il pagamento.

Il rimborso non riesce 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.

Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Ad esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, i dati temporanei e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le note di pagamento, gli ID delle transazioni e gli ID PayMongo.

PayMongo è un marchio del rispettivo proprietario. Questo plugin non è affiliato a PayMongo né approvato da PayMongo.