VibeFox Conekta for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza WooCommerce.
PHP: 8.0 o successivo.
Valuta: la valuta del negozio deve essere MXN o USD. Per le altre valute il metodo di pagamento viene nascosto.
Account Conekta: ti servono le Private Key del tuo account Conekta (test e live) e un webhook nel pannello Conekta (vedi Configurazione). Vengono usate solo le Private Key. La Public Key non serve, perché il pagamento avviene nel checkout ospitato da Conekta.
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_conekta_gateway in /wp-content/plugins/ tramite FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Conekta > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in alto nella pagina e fai clic su Activate.
5. Inserisci le tue Private Key di test e live, scegli la modalità e aggiungi il webhook nel pannello Conekta (vedi Configurazione).
6. Attiva Enable / Disable e salva. Esegui un pagamento di prova in modalità test, poi deseleziona la casella Test mode.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Conekta. Sopra i campi, la pagina ti avvisa quando Conekta è attivo ma la Private Key della modalità corrente è vuota (in tal caso il metodo di pagamento viene nascosto nel checkout) e quando la valuta del negozio non è MXN o USD. Mentre la modalità test è attiva, mostra Test mode is on: payments are simulated with the test private key. Quando salvi un gateway attivo senza la chiave della modalità corrente, un messaggio di errore ti chiede di inserirla.
Generale
Enable / Disable: Enable Conekta payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che il cliente vede nel checkout. Predefinito: Conekta.
Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.
Payment methods: i metodi offerti nella pagina di pagamento Conekta. Predefinito: carta, contanti e bonifico bancario. Contanti, SPEI e BNPL sono disponibili solo per gli ordini in MXN (gli ordini in USD accettano solo carte) e devono essere attivati nel tuo account Conekta. Se non è selezionato nulla, viene usata la carta.
Chiavi API
Copia le tue Private Key dal pannello Conekta, in Developers > API keys. Le chiavi di test e quelle live sono diverse.
Test mode: Enable test mode usa la Private Key di test. Non viene addebitato denaro reale e nel checkout compare un badge TEST MODE. I rimborsi usano sempre la chiave della modalità in cui è stato effettuato il pagamento. Predefinito: attivo.
Test private key: la Private Key dell'API della modalità test del tuo account Conekta.
Live private key: la Private Key dell'API della modalità live del tuo account Conekta. Tienila riservata.
Ogni ordine Conekta ricorda la propria modalità: le notifiche e i rimborsi usano la chiave corrispondente. Tieni compilate entrambe le chiavi finché restano aperti vecchi ordini di test.
Webhook
Il webhook informa il tuo negozio dei pagamenti effettuati dopo che il cliente ha lasciato la pagina di Conekta, per esempio i pagamenti OXXO o SPEI. Nel pannello Conekta vai su Developers > Webhooks e aggiungi l'URL mostrato in questa sezione sia per la modalità test sia per quella live. Ha questo aspetto: https://your-site/wc-api/webhook_wc_conekta/.
Seleziona questi eventi:
Il corpo del webhook indica solo al plugin quale ordine Conekta è cambiato. Ogni notifica viene verificata rileggendo l'ordine dall'API di Conekta con la Private Key della sua modalità; l'intestazione di firma Digest del webhook non viene usata. Le notifiche relative a ordini Conekta che questo negozio non ha creato per quell'ordine vengono accettate e ignorate. Senza il webhook, un ordine viene confermato solo quando il cliente torna nel negozio dopo aver pagato, oppure al successivo tentativo di pagamento dello stesso ordine.
Avanzate
Debug log: Log API calls and notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_conekta_gateway. Gli errori vengono sempre registrati. I log non contengono mai chiavi API né dati di contatto dei clienti. Predefinito: disattivato.
Delete data on uninstall: Remove the settings, Conekta order references and logs when the plugin is deleted. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Conekta) e completa l'ordine. Il plugin crea un ordine Conekta per il totale dell'ordine nella valuta dell'ordine, con gli articoli, la spedizione, le tasse e gli sconti, e invia il cliente alla pagina di pagamento ospitata da Conekta. Lì il cliente paga con uno dei metodi consentiti.
Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Conekta: il plugin legge l'ordine dall'API di Conekta quando arriva il webhook e quando il cliente torna. Se il pagamento non può ancora essere confermato, la pagina «Ordine ricevuto» mostra We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again. Quando il cliente ha scelto OXXO o SPEI e ha ricevuto un riferimento di pagamento, l'ordine passa a «In sospeso» e la pagina mostra Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received.
Se il pagamento viene rifiutato, l'ordine passa a «Fallito» e il cliente torna alla pagina Pay for order con The Conekta payment was not completed. Please try again or choose another payment method. Se il checkout è scaduto o è stato annullato, il cliente vede The Conekta payment has expired or was cancelled. Please place the order again. Quando il cliente paga di nuovo un ordine, un checkout Conekta aperto con lo stesso importo viene riutilizzato; altrimenti quello precedente viene annullato in Conekta prima di crearne uno nuovo, così un vecchio link non può essere pagato due volte. Se il checkout precedente era già stato pagato, il pagamento viene registrato invece di addebitare di nuovo.
Se Conekta non riesce ad avviare il pagamento, il cliente vede un messaggio breve, per esempio The payment could not be started. Please try again in a moment or choose another payment method. Il motivo tecnico viene scritto nel log.
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). I testi sono tradotti in spagnolo (Messico).
Il plugin accetta pagamenti solo nella pagina di Conekta. Non include un modulo di carta nel checkout, né carte salvate, abbonamenti, pre-autorizzazione e acquisizione o pagamenti rateali mensili (MSI).
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Conekta e non ha ancora pagato. La nota dell'ordine mostra l'ordine Conekta e la modalità.
Processing: Conekta ha confermato il pagamento con lo stesso importo e la stessa valuta (gli ordini con solo prodotti virtuali scaricabili passano a «Completato», il valore predefinito di WooCommerce). La nota dell'ordine mostra il metodo di pagamento (per esempio il marchio della carta e le ultime quattro cifre, OXXO / contanti o bonifico SPEI), l'ordine Conekta e l'addebito. L'ID transazione dell'ordine è l'ID dell'addebito Conekta (charge ID).
On hold, waiting for OXXO or SPEI: il cliente ha ricevuto un riferimento di pagamento. L'ordine passa a «In lavorazione» quando Conekta segnala il pagamento.
On hold after payment: l'importo o la valuta ricevuti da Conekta non corrispondono all'ordine, è arrivato un pagamento in modalità test mentre il negozio era in modalità live (non è stato incassato denaro reale), oppure il pagamento è arrivato per un ordine già annullato. La nota dell'ordine lo spiega. Controlla il pagamento, poi completa l'ordine o rimborsalo. Un ordine che in Conekta è solo pre-autorizzato viene anch'esso messo in «In sospeso», con una nota per acquisirlo o annullarlo nel pannello Conekta.
Failed: il pagamento è stato rifiutato. La nota mostra il motivo. Il cliente può pagare di nuovo.
Cancelled: il checkout Conekta attuale è scaduto o è stato annullato.
Un ordine pagato o rimborsato non viene mai retrocesso né riaperto. Se per un ordine già pagato arriva un altro pagamento Conekta, una nota WARNING ti chiede di rimborsarlo nel pannello Conekta.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Conekta (il pulsante mostra il titolo del metodo di pagamento). Sono supportati rimborsi totali e parziali. Il rimborso va all'ordine Conekta che contiene il pagamento e usa la chiave della modalità in cui il pagamento è stato effettuato, quindi quella chiave deve essere impostata. Se Conekta non accetta il rimborso, WooCommerce mostra l'errore e il rimborso non viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con importo, modalità, ordine Conekta, ID del rimborso e motivo.
I rimborsi effettuati nel pannello Conekta arrivano tramite il webhook e vengono aggiunti come nota con l'importo rimborsato in Conekta e in WooCommerce. Non vengono registrati automaticamente come rimborsi di WooCommerce. Registrali manualmente senza usare Refund via Conekta. Anche un chargeback segnalato da Conekta viene aggiunto come nota.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco della licenza si trova in alto in WooCommerce > Settings > Payments > Conekta. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare 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. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Conekta non viene mostrato ai clienti nel 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 con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Nella pagina Plugin e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono ancora confermati e i rimborsi funzionano.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente in background.
Risoluzione dei problemi
Conekta non compare nel checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che la Private Key della modalità corrente sia compilata (Test private key in modalità test, Live private key in modalità live) e che la valuta del negozio sia MXN o USD. La pagina delle impostazioni mostra un avviso per ciascuna di queste condizioni.
Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: il webhook non funziona. Nel pannello Conekta verifica che il webhook esista per la modalità che usi (test o live), che il suo URL sia esattamente quello mostrato nelle impostazioni e che gli eventi siano selezionati. Verifica che la Private Key di quella modalità sia impostata, perché ogni notifica viene verificata con essa. L'ordine viene confermato anche quando il cliente torna nel negozio o quando tenta di pagare di nuovo lo stesso ordine.
Il webhook risponde Temporarily unavailable: non è stato possibile raggiungere l'API di Conekta, manca la Private Key della modalità dell'ordine, oppure l'ordine era in elaborazione da un'altra richiesta. Conekta ripete il webhook.
Il webhook risponde Verification failed, Invalid payload o Invalid order id: l'API di Conekta non ha confermato l'ordine, oppure la notifica non era un evento valido di ordine Conekta.
Il webhook risponde Ignored: la notifica appartiene a un ordine Conekta che questo negozio non ha creato per quell'ordine (per esempio un altro negozio o un link di pagamento sullo stesso account), oppure a un oggetto diverso da un ordine.
Il cliente vede il messaggio We could not check the status of your previous payment attempt: non è stato possibile leggere il checkout Conekta precedente dell'ordine, quindi non ne viene creato uno nuovo per evitare un doppio pagamento. Riprova tra poco.
Il cliente vede il messaggio Payment gateway is not configured: manca la Private Key della modalità corrente.
L'ordine è On hold: leggi le note dell'ordine. Il cliente non ha ancora pagato il riferimento OXXO o SPEI, l'importo o la valuta non corrispondevano, oppure è arrivato un pagamento in modalità test mentre il negozio era in modalità live.
Il rimborso non riesce con un messaggio sulla modalità test o live: il pagamento è stato effettuato in quella modalità e la sua Private Key non è impostata. Inseriscila e riprova.
Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Per 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.
Per gli sviluppatori, il readme elenca il filtro wc_ckt_supported_currencies per l'elenco delle valute.
Disinstallazione
Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, i riferimenti Conekta salvati sugli ordini e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una reinstallazione futura. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.
Conekta è un marchio del rispettivo titolare. Questo plugin non è affiliato a Conekta né approvato da Conekta.