VibeFox Conekta for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

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

Valuta: la valuta del carrello deve essere MXN o USD. Per le altre valute il metodo di pagamento viene nascosto.

Account Conekta: ti servono le chiavi API private del tuo account Conekta (test e live) e un webhook nel pannello Conekta (vedi Configurazione). Vengono usate solo le chiavi private. La chiave pubblica non serve, perché il pagamento avviene sulla pagina di pagamento ospitata da Conekta.

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

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

4. Inserisci le chiavi private di test e live, scegli la modalità e aggiungi il webhook nel pannello Conekta (vedi Configurazione).

5. Attiva Enable / Disable e fai clic su Save. Prova un pagamento in modalità test, poi disattiva Test mode.

All'installazione il modulo crea due stati dell'ordine, Awaiting Conekta payment e Conekta payment on hold. PrestaShop propone un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Conekta Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando Conekta è attivo ma la chiave privata della modalità corrente è vuota (in tal caso il metodo di pagamento viene nascosto nel checkout) e quando la valuta predefinita del negozio non è MXN o USD. Finché la modalità test è attiva, mostra La modalità test è attiva: i pagamenti vengono simulati con la chiave privata di test. Se salvi un gateway attivo senza la chiave della modalità corrente, un avviso ti chiede di inserirla.

Conekta

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. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Conekta. Obbligatorio.

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: card, cash and bank transfer. Contanti, SPEI e BNPL sono disponibili solo per gli ordini in MXN (gli ordini in USD accettano solo carte) e devono essere abilitati nel tuo account Conekta. Se non è selezionato nulla, viene usata la carta e la pagina ti avvisa al salvataggio.

Chiavi API

Copia le chiavi private dal pannello Conekta alla voce Developers > API keys. Le chiavi di test e quelle live sono diverse.

Test mode: usa la chiave privata di test. Non viene addebitato denaro reale e sotto il metodo di pagamento nel checkout compare un badge TEST MODE con Non verrà effettuato alcun addebito reale. I rimborsi usano sempre la chiave della modalità in cui è stato effettuato il pagamento. Predefinito: attivo.

Test private key: la chiave privata API della modalità test del tuo account Conekta.

Live private key: la chiave privata API della modalità live del tuo account Conekta. Tienila riservata.

Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Salvata — lascia vuoto per mantenerla. Inserisci un nuovo valore solo se vuoi cambiarla.

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

Ogni ordine Conekta ricorda la sua modalità: notifiche e rimborsi usano la chiave corrispondente. Tieni compilate entrambe le chiavi finché restano aperti vecchi ordini di test.

Webhook

Il webhook informa il negozio sui pagamenti, ad esempio i pagamenti OXXO o SPEI effettuati dopo che il cliente ha lasciato la pagina Conekta. Nel pannello Conekta vai su Developers > Webhooks e aggiungi l'URL mostrato nel campo Webhook della sezione API keys, sia per la modalità test sia per quella live. Con gli URL semplificati ha questo aspetto: https://your-shop/module/wcp_conekta_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni.

Seleziona questi eventi (sono elencati anche nelle impostazioni):

Il corpo del webhook indica solo al modulo quale ordine Conekta è cambiato. Ogni notifica viene verificata rileggendo l'ordine dall'API di Conekta con la chiave privata della sua modalità; l'intestazione di firma Digest del webhook non viene usata. Le notifiche per ordini Conekta che non sono stati creati da questo negozio per quel carrello vengono confermate e ignorate. Senza il webhook, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato, oppure al successivo tentativo di pagamento per lo stesso carrello.

Avanzate

Debug log: registra le chiamate API e le notifiche in logs/wc_ckt_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando questo interruttore è disattivato. I log non contengono mai chiavi API né dati di contatto dei clienti. Predefinito: disattivato.

Log: mostra la dimensione del log e le voci più recenti. Fai clic su Clear log per svuotarlo.

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni e il log. Le transazioni e i rimborsi Conekta, gli stati degli ordini e gli ordini vengono sempre conservati, così i vecchi ordini possono ancora essere confermati e rimborsati dopo una reinstallazione. Predefinito: disattivato.

Checkout

Nel passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Conekta) e conferma. Il modulo crea un ordine Conekta per il totale del carrello nella valuta del carrello, con i prodotti, la confezione regalo, gli sconti, le tasse e la spedizione, e invia il cliente alla pagina di pagamento ospitata da Conekta. Il pagamento compare sulla pagina Conekta come Order # e il numero del carrello. Lì il cliente paga con uno dei metodi consentiti. 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 che Conekta lo conferma: il modulo legge l'ordine dall'API di Conekta quando arriva il webhook e quando il cliente torna. Solo allora l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Il tuo pagamento con Conekta è stato ricevuto. Se il cliente ha scelto OXXO o SPEI e ha ricevuto un riferimento di pagamento, l'ordine viene creato come Awaiting Conekta payment e la pagina mostra Il riferimento di pagamento Conekta è stato emesso. L'ordine sarà confermato non appena il pagamento sarà ricevuto. Se il riferimento scade in seguito, l'ordine viene annullato e la sua pagina di conferma mostra Il tuo pagamento con Conekta non è stato completato. Contattaci per questo ordine.

Se al ritorno del cliente il pagamento non può ancora essere confermato, una pagina Conferma pagamento mostra Stiamo confermando il tuo pagamento con Conekta. L'ordine verrà aggiornato automaticamente: non pagare di nuovo. e un pulsante Check again. Il webhook crea l'ordine non appena arriva.

Se il pagamento viene rifiutato, non viene creato alcun ordine e il cliente torna al checkout con Il pagamento Conekta non è stato completato. Riprova o scegli un altro metodo di pagamento. Se il checkout è scaduto o è stato annullato, il messaggio è Il pagamento Conekta è scaduto o è stato annullato. Riprova. Il carrello viene conservato. Quando il cliente paga di nuovo, viene riutilizzato un checkout Conekta aperto con lo stesso importo; 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, viene creato l'ordine invece di addebitare di nuovo.

Se Conekta non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, ad esempio Non è stato possibile avviare il pagamento. Riprova tra poco o scegli un altro metodo di pagamento. I messaggi di convalida inviati da Conekta, come un importo minimo, vengono mostrati così come li invia Conekta. Il motivo tecnico viene scritto nel log.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo accetta pagamenti solo nella pagina di Conekta. Non include un modulo di carta nel checkout, né carte salvate, abbonamenti, pre-autorizzazione e cattura o pagamenti rateali mensili (MSI).

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Conekta e non ha pagato, il pagamento è stato rifiutato o Conekta non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: Conekta ha confermato il pagamento con lo stesso importo e la stessa valuta. Il pagamento viene registrato con l'ID dell'addebito Conekta come ID transazione, e una nota mostra il metodo di pagamento (ad esempio il marchio della carta e le ultime quattro cifre, OXXO / contanti o bonifico SPEI), l'ordine Conekta e l'addebito.

Awaiting Conekta payment: il cliente ha ricevuto un riferimento di pagamento OXXO o SPEI. L'ordine passa a Payment accepted quando Conekta segnala il pagamento.

Conekta payment on hold: l'importo o la valuta ricevuti da Conekta non corrispondono al carrello (ad esempio il carrello è stato modificato dopo l'avvio del pagamento), un pagamento in modalità test è arrivato mentre il negozio era in modalità live (non è stato incassato denaro reale), oppure il pagamento è arrivato per un ordine già annullato. La nota lo spiega e il pagamento viene registrato con l'importo effettivamente pagato. Controlla l'ordine, poi evadilo o rimborsa il pagamento. Un ordine solo pre-autorizzato in Conekta viene anch'esso messo in attesa, con una nota per catturarlo o annullarlo nel pannello Conekta.

Canceled: il riferimento OXXO o SPEI di un ordine in attesa è scaduto, oppure il suo ordine Conekta è stato annullato.

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

Un ordine pagato o rimborsato non viene mai retrocesso né riaperto. Se arriva un altro pagamento Conekta per un ordine già pagato, una nota WARNING ti chiede di rimborsarlo nel pannello Conekta.

Blocco pagamento Conekta

La pagina dell'ordine mostra un blocco Conekta payment con l'ordine Conekta, l'addebito, lo stato del pagamento, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di test, lo storico dei rimborsi e le Conekta notes dell'ordine.

Rimborsi

Nel blocco Conekta payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Conekta. Conferma la domanda Rimborsare questo importo tramite Conekta? L'operazione non può essere annullata. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi sono limitati all'importo e alla valuta effettivamente addebitati da Conekta, quindi dopo una differenza di importo puoi rimborsare fino a quanto ha pagato il cliente, non il totale dell'ordine. Il rimborso va all'ordine Conekta che contiene il pagamento e usa la chiave della modalità in cui è stato effettuato il pagamento, quindi quella chiave deve essere impostata. Se Conekta 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, modalità, ordine Conekta, ID del rimborso e motivo. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non modifica lo stato. I rimborsi sono disponibili dopo che Conekta ha segnalato il pagamento.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Conekta.

I rimborsi effettuati nel pannello Conekta arrivano tramite il webhook e vengono aggiunti come nota con l'importo rimborsato in Conekta e in PrestaShop. Non vengono registrati automaticamente. Aggiorna l'ordine manualmente senza usare Refund via Conekta. Anche un chargeback segnalato da Conekta viene aggiunto come nota.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Conekta Gateway è il primo blocco di Modules > Module Manager > VibeFox Conekta Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Poi 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto compaiono la riga Product: presta-payment-conekta e il link Gestisci licenze e domini nel tuo 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, ad 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 solo 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, Conekta non viene mostrato ai clienti nel checkout. Se un pagamento viene avviato comunque, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. La vetrina 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 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

Conekta non compare nel checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che la chiave privata della modalità corrente sia compilata (Test private key in modalità test, Live private key in modalità live) e che la valuta del carrello sia MXN o USD. La pagina delle impostazioni mostra un avviso quando la chiave manca o 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: 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 chiave privata di quella modalità sia impostata, perché ogni notifica viene verificata con essa. L'ordine viene creato anche quando il cliente torna nel negozio o quando tenta di pagare di nuovo lo stesso carrello.

Il webhook risponde Temporarily unavailable: non è stato possibile raggiungere l'API di Conekta, manca la chiave privata della modalità dell'ordine, un'altra richiesta stava elaborando il carrello, oppure l'ordine non è stato creato (ad esempio perché il modulo è disattivato). Conekta riprova il webhook. Controlla il campo Log per il motivo.

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 non è stato creato da questo negozio per quel carrello (ad esempio un altro negozio o un link di pagamento sullo stesso account), oppure a un oggetto diverso da un ordine.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste provenienti da Conekta.

Il cliente vede Non siamo riusciti a verificare lo stato del tuo precedente tentativo di pagamento: il precedente checkout Conekta del carrello non è stato leggibile, quindi non viene creato un nuovo checkout per evitare un doppio pagamento. Riprova tra poco.

Il cliente vede Il gateway di pagamento non è configurato: manca la chiave privata della modalità corrente.

Il cliente vede La verifica del pagamento non è riuscita: il link di ritorno da Conekta non corrispondeva al carrello. Controlla l'ordine nel pannello Conekta; il webhook conferma comunque un pagamento reale.

L'ordine è in Awaiting Conekta payment o Conekta payment on hold: leggi le Conekta notes nel blocco dell'ordine. Il cliente non ha ancora pagato il riferimento OXXO o SPEI, l'importo o la valuta non corrispondevano, è arrivato un pagamento in modalità test mentre il negozio era in modalità live, oppure il pagamento è solo pre-autorizzato.

Il rimborso non riesce con un messaggio su modalità test o live: il pagamento è stato effettuato in quella modalità e la sua chiave privata non è impostata. Inseriscila e riprova.

Per gli sviluppatori, il README elenca gli hook actionWcpConektaSupportedCurrencies, actionWcpConektaOrderRequest, actionWcpConektaAllowedPaymentMethods e actionWcpConektaRefundReason.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Conekta 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 e il log. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi Conekta e gli stati dell'ordine Awaiting Conekta payment e Conekta payment on hold vengono sempre conservati, così gli ordini pagati in precedenza possono essere ancora rimborsati dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID delle transazioni.

Conekta è un marchio registrato del rispettivo proprietario. Questo modulo non è affiliato a Conekta né approvato da Conekta.