VibeFox Wompi 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: peso colombiano (COP). Wompi Colombia addebita in COP, e il metodo di pagamento viene nascosto per i carrelli in altre valute. La pagina di configurazione ti avvisa quando la valuta predefinita del negozio non è COP.

Account Wompi: un account commerciante Wompi Colombia. Ogni ambiente (sandbox e produzione) ha quattro chiavi: chiave pubblica, chiave privata, segreto degli eventi e segreto di integrità. Le trovi nella dashboard del commerciante Wompi (comercios.wompi.co), nella sezione sviluppatori. Wompi El Salvador e Panama usano API diverse e non sono supportati.

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 clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure cerca più tardi VibeFox Wompi Payment nell'elenco dei moduli e clicca su Configure.

3. Incolla la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Incolla le chiavi sandbox e produzione dalla dashboard del commerciante Wompi e imposta l'URL degli eventi in Wompi (vedi Configurazione).

5. Attiva Enable/Disable e clicca su Save. Prova un pagamento in modalità sandbox, poi disattiva Sandbox mode per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine, Awaiting Wompi payment e Wompi payment on hold. PrestaShop offre un nuovo modulo di pagamento per le valute, i paesi e i gruppi di clienti esistenti in quel momento. Verifica che COP sia consentito in Payment > Preferences. Un paese aggiunto in seguito deve essere spuntato lì prima che i clienti di quel paese vedano Wompi.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Wompi Payment > Configure. Ogni sezione con campi ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, un riquadro di stato mostra la modalità attuale, SANDBOX o PRODUCTION. Quando manca una chiave di questa modalità, il riquadro la elenca e indica che il metodo di pagamento è nascosto al checkout finché non sono impostate tutte le chiavi di questo ambiente. Quando tutte le chiavi sono impostate, indica se verranno addebitati pagamenti reali. Al salvataggio il modulo ti avvisa se una chiave non inizia con il prefisso della sua sezione e se Wompi è attivo ma nascosto al checkout perché mancano chiavi.

Wompi

Enable/Disable: Enable Wompi attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Wompi. Se lo lasci vuoto, viene usato il nome del modulo.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Account Wompi

Copia le chiavi dalla dashboard del commerciante Wompi (comercios.wompi.co), sezione sviluppatori. Ogni ambiente ha la propria chiave pubblica, chiave privata, segreto degli eventi e segreto di integrità.

Sandbox mode: usa la sandbox di Wompi (chiavi sandbox, nessun denaro reale). Cambia sia le chiavi sia l'API di Wompi (sandbox.wompi.co o production.wompi.co). I tentativi di pagamento mantengono l'ambiente in cui sono stati effettuati. Predefinito: on. Disattivalo per accettare pagamenti reali. Quando è attivo, i clienti vedono Modalità sandbox: nessun pagamento reale viene effettuato. sotto il metodo di pagamento.

Chiavi sandbox

Le quattro chiavi della sandbox di Wompi. Iniziano con pub_test_, prv_test_, test_events_ e test_integrity_.

Public key: la chiave pubblica sandbox (pub_test_...). Identifica il tuo account in Wompi Web Checkout.

Private key: la chiave privata sandbox (prv_test_...). Serve a leggere le transazioni dalle API di Wompi.

Events secret: il segreto degli eventi sandbox (test_events_...). Verifica la firma degli eventi Wompi.

Integrity secret: il segreto di integrità sandbox (test_integrity_...). Firma la richiesta di pagamento inviata al Web Checkout.

Chiavi di produzione

Le quattro chiavi dell'ambiente di produzione di Wompi. Iniziano con pub_prod_, prv_prod_, prod_events_ e prod_integrity_.

Public key: la chiave pubblica di produzione (pub_prod_...).

Private key: la chiave privata di produzione (prv_prod_...).

Events secret: il segreto degli eventi di produzione (prod_events_...).

Integrity secret: il segreto di integrità di produzione (prod_integrity_...).

Le chiavi pubbliche sono mostrate nei rispettivi campi. Le chiavi private e i segreti salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Salvato: lascia vuoto per mantenerlo. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: spunta una chiave privata o un segreto di uno dei due ambienti e clicca su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

URL degli eventi (webhook)

Gli eventi Wompi informano il tuo negozio che una transazione è cambiata. Nella dashboard del commerciante Wompi, sezione sviluppatori, imposta l'URL degli eventi mostrato in questa sezione, per la sandbox e per la produzione. Con URL semplificati ha questo aspetto https://your-shop/module/wcp_wompi_payment/webhook, eventualmente con un codice lingua come /es/. Copia l'URL esattamente come lo mostrano le impostazioni.

Il modulo usa questo evento:

Gli altri eventi ricevono la risposta Ignored. Ogni evento viene verificato con il segreto degli eventi del suo ambiente (sandbox o produzione). I webhook senza firma valida vengono rifiutati. Dopo la verifica, la transazione viene letta dalle API di Wompi con la chiave privata di quell'ambiente, e vengono usati solo quei dati. Senza l'URL degli eventi, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Avanzate

Debug log: scrive l'attività di pagamento e dei webhook in logs/wompi_p_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, segreti e dati dei clienti non vengono mai registrati. Predefinito: off.

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

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo e il log. I tentativi di pagamento Wompi e gli stati dell'ordine del modulo restano sempre, quindi gli ordini esistenti conservano i loro dati Wompi. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Wompi) e conferma. Il modulo crea un tentativo di pagamento con un proprio riferimento (PS-, il numero del carrello e una marca temporale), lo firma con il segreto di integrità e invia il cliente a Wompi Web Checkout con il totale del carrello in COP. L'e-mail del cliente e il nome dell'indirizzo di fatturazione vengono passati a Wompi. A questo punto non esiste ancora alcun ordine.

Sulla pagina di Wompi il cliente paga con un qualsiasi metodo di pagamento attivo nel tuo account Wompi. Poi Wompi riporta il cliente nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Wompi: tramite un evento firmato oppure tramite una richiesta lato server alle API di Wompi quando il cliente torna. Il numero di transazione nell'indirizzo di ritorno non è considerato affidabile, e vengono accettate solo le transazioni create per quel carrello nell'ambiente del tentativo. Ricaricando la pagina, la transazione viene verificata di nuovo al massimo una volta ogni 20 secondi.

Quando la transazione viene approvata, l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine. Per un pagamento in attesa (ad esempio PSE, Nequi o un pagamento in contanti) la pagina mostra Il tuo pagamento Wompi è in attesa di conferma (ad esempio PSE, Nequi o un pagamento in contanti). Elaboreremo l'ordine non appena Wompi confermerà il pagamento. Per un ordine in attesa mostra Abbiamo ricevuto il tuo pagamento Wompi e lo stiamo verificando. Ti contatteremo se serve qualcosa. Se un pagamento in attesa viene rifiutato in seguito, la pagina mostra Il tuo pagamento Wompi non è stato approvato. Contattaci. Se viene annullato, la pagina mostra Il tuo pagamento Wompi è stato annullato e questo ordine è stato cancellato. Contattaci.

Se Wompi non ha ancora confermato la transazione quando il cliente torna, compare una pagina con Stiamo aspettando che Wompi confermi il tuo pagamento. Riceverai un'e-mail non appena sarà confermato. e un pulsante Check again. L'evento Wompi crea l'ordine appena arriva.

Se il pagamento viene rifiutato, non viene creato alcun ordine e il carrello viene conservato. Il cliente torna al checkout con Il tuo pagamento Wompi non è stato approvato (...). Puoi riprovare o scegliere un altro metodo di pagamento., con il motivo indicato da Wompi. Un pagamento annullato mostra Il tuo pagamento Wompi è stato annullato. Puoi riprovare o scegliere un altro metodo di pagamento. Se il cliente lascia Web Checkout senza pagare, il messaggio è Il tuo pagamento Wompi non è stato completato. Puoi riprovare o scegliere un altro metodo di pagamento. Ogni nuovo tentativo riceve un nuovo riferimento. Una volta che il carrello ha un ordine (pagato, in attesa, Errore di pagamento o Annullato), non può più essere pagato: il cliente viene portato alla pagina di conferma dell'ordine.

Il metodo di pagamento viene mostrato solo quando la licenza è attiva, tutte e quattro le chiavi della modalità attuale sono impostate, la valuta del carrello è COP ed è consentita per il modulo, e il totale è di almeno COP 1.500. Se il pagamento non può iniziare, il cliente resta al checkout con un breve messaggio:

L'URL degli eventi funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo non effettua rimborsi da PrestaShop. Non prevede carte salvate, abbonamenti né campi per le carte sul tuo sito: tutti i dati di pagamento vengono inseriti su Wompi.

Ordini

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Wompi e non ha pagato, il pagamento è stato rifiutato, oppure Wompi non ha ancora confermato la transazione. Esiste solo il carrello.

Awaiting Wompi payment: Wompi segnala la transazione come in attesa, ad esempio pagamenti PSE, Nequi o in contanti che attendono conferma. L'ordine resta in attesa finché Wompi non lo approva o lo rifiuta. Quando viene approvato, il pagamento viene registrato e l'ordine passa a Payment accepted.

Payment accepted: la transazione è stata approvata per l'importo del carrello in COP. Il pagamento viene registrato con l'ID di transazione Wompi, e una nota mostra la transazione, il tipo di metodo di pagamento (ad esempio CARD, PSE o NEQUI), il riferimento, l'importo e l'ambiente.

Wompi payment on hold: Wompi ha approvato un importo o una valuta diversi dal totale dell'ordine (ad esempio, il carrello è stato modificato dopo l'avvio del pagamento), oppure il pagamento è stato approvato dopo che l'ordine era stato annullato. L'ordine non viene segnato come pagato. La nota lo spiega. Verifica il pagamento nella dashboard di Wompi e poi evadi l'ordine oppure rimborsa il pagamento.

Payment error: una transazione in attesa dell'ultimo tentativo di pagamento è stata rifiutata o si è conclusa con un errore. Il messaggio di Wompi viene aggiunto alla nota. I risultati dei tentativi precedenti non modificano l'ordine.

Canceled: una transazione in attesa dell'ultimo tentativo di pagamento è stata annullata in Wompi.

Se arriva un secondo pagamento approvato per un ordine già pagato, l'ordine non cambia. Una nota ti chiede di rimborsare il duplicato nella dashboard di Wompi. Se la transazione di pagamento viene annullata in Wompi, una nota ti chiede di verificare l'ordine. Un pagamento tardivo per un ordine rimborsato aggiunge solo una nota. Eventi e ritorni ripetuti non duplicano mai note, e-mail o pagamenti.

Blocco pagamento Wompi

La pagina dell'ordine mostra un blocco Wompi payment con il riferimento, l'ID di transazione, lo stato (con lo stato Wompi), l'importo richiesto, l'importo della transazione, il metodo di pagamento, il messaggio di Wompi, un badge SANDBOX per i pagamenti sandbox, i Payment attempts del carrello quando sono più di uno, e le Wompi notes dell'ordine.

Rimborsi

I rimborsi non vengono inviati da PrestaShop. Rimborsa o annulla il pagamento nella dashboard del commerciante Wompi, poi registra manualmente il rimborso in PrestaShop. Un annullamento della transazione di pagamento effettuato in Wompi viene aggiunto all'ordine come nota.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Wompi Payment è il primo blocco di Modules > Module Manager > VibeFox Wompi Payment > Configure, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino alla quale 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 compaiono la riga Product: presta-payment-wompi 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 cambiare 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 spiega 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 che l'indirizzo del negozio cambia, o dopo aver liberato uno slot di dominio nel tuo account, clicca 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, Wompi 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 hai effettuato l'accesso 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 continuano a essere confermati dagli eventi di Wompi e quando il cliente torna nel negozio.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Wompi non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che tutte e quattro le chiavi della modalità attuale siano impostate (il riquadro di stato nella pagina delle impostazioni elenca le chiavi mancanti). Verifica anche che la valuta del carrello sia COP e che il totale sia di almeno COP 1.500. In Payment > Preferences verifica che il modulo sia consentito per COP, per il paese del cliente e per il suo gruppo.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: l'URL degli eventi non funziona. Nella dashboard di Wompi verifica che l'URL degli eventi sia impostato per l'ambiente che usi (sandbox o produzione) e che sia esattamente quello mostrato nelle impostazioni. Verifica che il segreto degli eventi di quell'ambiente sia nella sezione corrispondente. L'ordine viene creato anche quando il cliente torna nel negozio dopo aver pagato.

L'URL degli eventi risponde Not configured: il segreto degli eventi dell'ambiente dell'evento è vuoto. Incollalo nelle impostazioni.

L'URL degli eventi risponde Invalid signature: il segreto degli eventi appartiene a un altro ambiente o a un altro account. Copialo di nuovo dalla dashboard di Wompi.

L'URL degli eventi risponde Transaction lookup failed: le API di Wompi non hanno restituito la transazione, ad esempio per una chiave privata errata o un problema di rete. Wompi invierà di nuovo l'evento più tardi.

L'URL degli eventi risponde Retry: l'ordine era in conferma da un'altra richiesta nello stesso momento, oppure l'ordine non ha potuto essere creato (ad esempio perché il modulo è disattivato). Wompi invierà di nuovo l'evento più tardi. Controlla il campo Log per il motivo.

L'URL degli eventi risponde Environment mismatch: una transazione sandbox è arrivata per un tentativo di pagamento in produzione, o viceversa. I pagamenti sandbox non confermano mai ordini di produzione.

L'URL degli eventi risponde Unknown reference: il riferimento della transazione non è stato emesso da questo negozio, ad esempio perché lo stesso account Wompi è usato da un altro negozio. I riferimenti di altri sistemi ricevono la risposta Ignored.

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

Avviso al salvataggio che la chiave non inizia con ...: una chiave è stata incollata nella sezione sbagliata. Le chiavi sandbox iniziano con pub_test_, prv_test_, test_events_ e test_integrity_, quelle di produzione con pub_prod_, prv_prod_, prod_events_ e prod_integrity_.

L'ordine è Wompi payment on hold: leggi le note nel blocco Wompi payment (vedi Stati dell'ordine), poi evadi l'ordine oppure rimborsa il pagamento nella dashboard di Wompi.

Altri errori: controlla il campo Log nella pagina del modulo e le Wompi notes dell'ordine. Gli errori vengono sempre registrati. Attiva Debug log per maggiori dettagli.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Wompi Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, le impostazioni del modulo e il log vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I tentativi di pagamento Wompi e gli stati dell'ordine Awaiting Wompi payment e Wompi payment on hold restano sempre, così un evento tardivo di un vecchio pagamento viene ancora riconosciuto dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID di transazione.

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