VibeFox Wompi for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

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

PHP: 8.0 o successivo.

Valuta del negozio: peso colombiano (COP). Wompi Colombia addebita in COP, e il metodo di pagamento viene nascosto per gli ordini in altre valute.

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 per sviluppatori. Wompi El Salvador e Panama usano API diverse e non sono supportati.

Chiave di licenza VibeFox: si acquista 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_wompi_payment in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Imposta la valuta del negozio su peso colombiano (COP) in WooCommerce > Settings > General.

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

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

6. Incolla le chiavi sandbox e produzione dalla dashboard del commerciante Wompi e imposta la Events URL in Wompi (vedi Configurazione).

7. Attiva Enable/Disable. Prova un pagamento in modalità sandbox, poi deseleziona Sandbox mode per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in una sola pagina: WooCommerce > Settings > Payments > Wompi. 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 vengono addebitati pagamenti reali. Al salvataggio, il plugin ti avvisa se una chiave non inizia con il prefisso della sua sezione, e se Wompi è attivo ma nascosto al checkout perché mancano chiavi. Nell'elenco dei metodi di pagamento, Wompi è segnalato come da configurare finché la modalità attuale non ha tutte e quattro le chiavi. Le chiavi della versione 1.0 vengono spostate automaticamente nella sezione Sandbox o Production corrispondente all'aggiornamento.

Generale

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Wompi.

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 per sviluppatori. Ogni ambiente ha la propria chiave pubblica, chiave privata, segreto degli eventi e segreto di integrità.

Sandbox mode: Use the Wompi sandbox (sandbox keys, no real money). Cambia sia le chiavi sia l'API di Wompi (sandbox.wompi.co o production.wompi.co). Gli ordini mantengono l'ambiente in cui sono stati pagati. Predefinito: attivo. Deselezionala per accettare pagamenti reali.

Chiavi sandbox

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

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

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

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

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

Chiavi di produzione

Le quattro chiavi dell'ambiente di produzione 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_...).

Events URL (webhook)

Gli eventi Wompi comunicano al tuo negozio che una transazione è cambiata. Nella dashboard del commerciante Wompi, sezione per sviluppatori, imposta la Events URL mostrata in questa sezione delle impostazioni, sia per la sandbox sia per la produzione. Ha questo aspetto: https://your-site/wc-api/wompi_p/. Copia l'URL esattamente come lo mostrano le impostazioni.

Il plugin usa questo evento:

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

Avanzate

Debug log: Log payment and webhook activity scrive l'attività di pagamento ed evento in WooCommerce > Status > Logs, origine wcp_wompi_payment. Gli errori vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, segreti e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. La disattivazione non elimina mai nulla. I dati degli ordini vengono sempre conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Wompi) e completa l'ordine. In modalità sandbox il checkout mostra Sandbox mode: no real payment is made. sotto la descrizione. Il plugin crea un tentativo di pagamento con un proprio riferimento (WC-, il numero dell'ordine e una marca temporale), lo firma con il segreto di integrità e invia il cliente al Wompi Web Checkout con il totale dell'ordine in COP. L'e-mail di fatturazione e il nome del cliente vengono passati a Wompi. Una nota sull'ordine registra l'ambiente, il riferimento e l'importo.

Sulla pagina di Wompi il cliente paga con un qualsiasi metodo di pagamento attivo nel tuo account Wompi. Poi Wompi riporta il cliente alla pagina di conferma ordine del tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Wompi: con un evento firmato oppure con una richiesta lato server alle API di Wompi quando il cliente arriva su quella pagina. Il numero di transazione nell'indirizzo di ritorno non è considerato affidabile. Al ricaricamento della pagina, la transazione viene verificata di nuovo al massimo una volta ogni 20 secondi.

Solo le transazioni create per quell'ordine possono pagarlo, e solo nell'ambiente del tentativo. Un cliente può pagare di nuovo un ordine non pagato, per esempio dalla pagina Pay for order. Ogni tentativo riceve un nuovo riferimento.

Il metodo di pagamento viene mostrato solo quando la licenza è attiva, tutte e quattro le chiavi della modalità attuale sono impostate, la valuta dell'ordine è COP e il totale è di almeno COP 1.500. Se il pagamento non può partire, il cliente vede un breve messaggio e può scegliere un altro metodo di pagamento:

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). Sono incluse le traduzioni spagnole per Colombia e Spagna.

Il plugin non effettua rimborsi da WooCommerce. 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

Pending payment: il cliente è stato inviato a Wompi e non ha ancora pagato, oppure Wompi non ha ancora confermato la transazione.

On hold (pending payment): Wompi segnala la transazione come in attesa, per esempio pagamenti PSE, Nequi o in contanti in attesa di conferma. L'ordine resta in attesa finché Wompi non lo approva o lo rifiuta.

Processing or Completed: la transazione è stata approvata. Si applica lo standard di WooCommerce: In lavorazione, oppure Completato per gli ordini con soli prodotti virtuali scaricabili. La nota dell'ordine mostra la transazione Wompi, il tipo di metodo di pagamento (per esempio carta, PSE o Nequi) e il riferimento. L'ID transazione dell'ordine è l'ID della transazione Wompi.

On hold after payment: Wompi ha approvato un importo o una valuta diversi dal totale dell'ordine (per esempio, l'ordine è 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 dell'ordine lo spiega. Controlla il pagamento nella dashboard di Wompi e completa l'ordine oppure rimborsa il pagamento.

Failed: la transazione 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.

Cancelled: la transazione dell'ultimo tentativo di pagamento è stata annullata in Wompi prima che l'ordine fosse pagato.

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 ripetuti e ritorni dei clienti non duplicano mai note, e-mail o variazioni di magazzino.

Rimborsi

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

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza si trova in cima a WooCommerce > Settings > Payments > Wompi. 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 posto per il dominio. Libera il posto 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati dagli eventi Wompi e dai ritorni dei clienti.

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

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 dell'ordine sia COP e che il totale sia di almeno COP 1.500.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: la Events URL non funziona. Nella dashboard di Wompi verifica che la Events URL sia impostata per l'ambiente che usi (sandbox o produzione) e che sia esattamente quella mostrata nelle impostazioni. Verifica che il segreto degli eventi di quell'ambiente sia nella sezione corrispondente. L'ordine viene confermato anche quando il cliente torna nel negozio dopo aver pagato.

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

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

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

La Events URL risponde Busy, retry: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Wompi invierà di nuovo l'evento più tardi.

La Events URL 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.

Avviso al salvataggio «The key does not start with ...»: 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 è On hold con una nota sull'importo: l'importo o la valuta approvati non coincidono con il totale dell'ordine. Controlla il pagamento nella dashboard di Wompi e completa o rimborsa l'ordine manualmente.

Altri errori: apri le note dell'ordine o WooCommerce > Status > Logs, origine wcp_wompi_payment. Gli errori vengono sempre registrati. Attiva Debug log per maggiori dettagli. Gli sviluppatori possono consentire un'altra valuta con il filtro wompi_p_supported_currencies, se il loro account Wompi la accetta.

Il blocco di licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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

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

Wompi è un marchio del suo rispettivo titolare. Questo plugin non è affiliato né approvato da Wompi.