VibeFox ePayco for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza WooCommerce.
PHP: 8.0 o successivo.
Valuta del negozio: peso colombiano (COP) o dollaro statunitense (USD). Per le altre valute il metodo di pagamento non viene mostrato al checkout.
Account ePayco: ti servono le quattro chiavi del tuo account ePayco: P_CUST_ID_CLIENTE, P_KEY, PUBLIC_KEY e PRIVATE_KEY. Si trovano nella dashboard di ePayco, in Integrations, API keys. Le stesse chiavi funzionano in modalità di test e in modalità live. I metodi di pagamento che il cliente può usare (carte, PSE, reti di pagamento in contanti, portafogli) sono quelli attivati sul tuo account ePayco.
Sito pubblico: l'URL di conferma del tuo negozio deve essere raggiungibile da internet, senza essere bloccato dalla modalità manutenzione, da un firewall o dall'autenticazione di base.
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. In alternativa puoi caricare la cartella wcp_epayco_payment in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > ePayco > 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 cima alla pagina e fai clic su Activate.
5. Inserisci le quattro chiavi ePayco e scegli il tipo di checkout (vedi Configurazione).
6. Attiva Enable/Disable. Prova un pagamento in Test Mode con le carte di test di ePayco, poi deseleziona Test Mode.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > ePayco. Sopra i campi la pagina ti avvisa quando non sono state inserite tutte e quattro le chiavi (in tal caso il metodo di pagamento non viene mostrato al checkout), quando la valuta del negozio non è COP o USD, e mostra Test mode is on: customers pay with ePayco test cards and no real money is charged. finché la modalità di test è attiva. Nell'elenco dei metodi di pagamento, ePayco risulta da configurare finché non vengono inserite tutte e quattro le chiavi.
Generale
Enable/Disable: Enable ePayco Payment attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: ePayco.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with ePayco.
Chiavi dell'account ePayco
Trova le quattro chiavi nella dashboard di ePayco, in Integrations, API keys. P_CUST_ID_CLIENTE e P_KEY verificano le conferme di pagamento; PUBLIC_KEY e PRIVATE_KEY creano le sessioni di checkout. Le stesse chiavi funzionano in modalità di test e in modalità live.
Customer ID (P_CUST_ID_CLIENTE): il tuo ID cliente ePayco (numerico).
Secret Key (P_KEY): serve a verificare la firma delle conferme di pagamento di ePayco. Tienila segreta.
Public Key (PUBLIC_KEY): la tua chiave API pubblica di ePayco.
Private Key (PRIVATE_KEY): la tua chiave API privata di ePayco. Tienila segreta.
Test Mode: Enable test mode crea le sessioni di checkout come transazioni di test. I clienti pagano con le carte di test di ePayco e non viene addebitato denaro reale. Le transazioni di test non pagano mai gli ordini creati in modalità live. Predefinito: disattivato.
Checkout
Checkout Type: come si apre il checkout di ePayco.
URL di conferma
L'URL di conferma comunica al tuo negozio il risultato di un pagamento. Viene inviato automaticamente a ePayco con ogni pagamento, quindi non c'è nulla da configurare nella dashboard di ePayco. La sezione mostra l'URL. Ha questo aspetto: https://your-site/wc-api/epc_p/. Deve essere raggiungibile da internet, senza essere bloccato dalla modalità manutenzione, da un firewall o dall'autenticazione di base.
Ogni conferma deve contenere una firma valida creata con il tuo P_CUST_ID_CLIENTE e il tuo P_KEY. Le conferme senza firma valida vengono rifiutate e non modificano l'ordine. Senza la conferma, un ordine viene aggiornato solo quando il cliente torna nel negozio dopo aver pagato.
Avanzate
Logging: Enable logging scrive gli errori delle API e le conferme di pagamento in WooCommerce > Status > Logs, origine wcp_epayco_payment. Chiavi e dati dei clienti non vengono registrati. Predefinito: disattivato.
Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Disattivare il plugin non cancella mai nulla. I dati ePayco salvati negli ordini vengono conservati. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita ePayco) e conferma l'ordine. Il plugin crea una sessione di checkout di ePayco per il totale dell'ordine nella valuta dell'ordine, con le tasse, il numero dell'ordine e il nome, l'indirizzo, l'e-mail e il telefono di fatturazione. La lingua del checkout è lo spagnolo o l'inglese, in base alla lingua del sito. Il cliente arriva poi alla pagina di pagamento dell'ordine, che mostra Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. Il checkout di ePayco si apre come popup o come reindirizzamento, in base a Checkout Type. La pagina contiene anche il pulsante Pay with ePayco e il link Choose another payment method. In modalità di test la pagina e il checkout mostrano TEST MODE — use ePayco test cards, no real money is charged.
Nel checkout di ePayco il cliente paga con uno dei metodi attivati sul tuo account ePayco. Poi ePayco invia la conferma al tuo negozio e riporta il cliente indietro. L'ordine viene segnato come pagato solo dopo la conferma di ePayco: con la conferma firmata oppure con una richiesta lato server a ePayco quando il cliente torna. Il solo ritorno del cliente non paga mai un ordine.
Se il pagamento non è ancora confermato, la pagina di ordine ricevuto mostra We are waiting for ePayco to confirm your payment. This page does not need to stay open. Per un pagamento in sospeso (ad esempio PSE o contanti) mostra Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved.
Se il pagamento è stato rifiutato, il cliente torna alla pagina Pay for order con il messaggio Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. Se il cliente torna senza aver pagato, il messaggio è The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again.
Se ePayco non riesce ad avviare il pagamento, il cliente vede un breve messaggio, ad esempio We could not connect to ePayco. Please try again in a moment or choose another payment method. Il motivo viene aggiunto alle note dell'ordine e al registro.
Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS). I testi visibili al cliente sono tradotti in spagnolo.
Il plugin accetta solo pagamenti una tantum. Non sono previsti rimborsi da WooCommerce, carte salvate, abbonamenti o pagamenti suddivisi, e il plugin non interroga ePayco sulle transazioni in sospeso: gli ordini vengono aggiornati dalla conferma di ePayco e dal ritorno del cliente.
Ordini
Stati dell'ordine
Pending payment: il cliente è stato inviato a ePayco e non ha ancora pagato, oppure ePayco non ha ancora confermato il pagamento.
Processing: il pagamento è stato accettato (gli ordini con soli prodotti virtuali scaricabili diventano Completato, il valore predefinito di WooCommerce). La nota dell'ordine mostra il riferimento ePayco, lo stato, l'importo, il metodo di pagamento e il codice di approvazione. L'ID transazione dell'ordine è il riferimento ePayco (ref_payco).
On hold, payment pending: ePayco ha segnalato il pagamento come in attesa o trattenuto, ad esempio un bonifico PSE o un pagamento in contanti. L'ordine cambia automaticamente quando ePayco lo conferma o lo rifiuta.
On hold, amount/currency mismatch: ePayco ha approvato un pagamento il cui importo o la cui valuta non corrisponde all'ordine. Non spedire prima di aver verificato la transazione nella dashboard di ePayco.
On hold, payment for a cancelled order: ePayco ha approvato un pagamento dopo che l'ordine era stato annullato. Ripristina l'ordine oppure rimborsa il pagamento in ePayco.
Failed: il pagamento è stato rifiutato, non è riuscito, è scaduto, è stato abbandonato, annullato o bloccato dall'antifrode. La nota mostra il motivo indicato da ePayco. Il cliente può riprovare. Un fallimento tardivo non modifica mai un ordine pagato.
Refunded: ePayco ha rimborsato il pagamento di questo ordine.
Se ePayco segnala un altro pagamento approvato per un ordine già pagato, lo stato non cambia. Una nota ti chiede di verificare un eventuale doppio addebito e di rimborsarlo in ePayco, se necessario. Una transazione di test per un ordine effettuato in modalità live e una transazione già associata a un altro ordine vengono ignorate con una nota.
Rimborsi: i rimborsi da WooCommerce non sono supportati. Rimborsa il pagamento nella dashboard di ePayco, poi registra il rimborso in WooCommerce con Refund manually.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > ePayco. 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 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. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, ePayco 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 da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
Risoluzione dei problemi
ePayco non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che tutte e quattro le chiavi siano inserite e che la valuta del negozio sia COP o USD. Nella pagina Pay for order viene verificata la valuta dell'ordine. La pagina delle impostazioni mostra un avviso quando manca qualcosa.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: la conferma di ePayco non raggiunge il tuo negozio. Verifica che l'URL di conferma mostrato nelle impostazioni sia raggiungibile da internet e non sia bloccato da modalità manutenzione, firewall, plugin di sicurezza o autenticazione di base. Attiva Logging e controlla WooCommerce > Status > Logs, origine wcp_epayco_payment. L'ordine viene aggiornato anche quando il cliente torna nel negozio dopo aver pagato.
La conferma risponde Invalid signature: Customer ID (P_CUST_ID_CLIENTE) o Secret Key (P_KEY) non corrisponde all'account ePayco che ha ricevuto il pagamento. Copiali di nuovo dalla dashboard di ePayco.
La conferma risponde Gateway not configured: P_CUST_ID_CLIENTE o P_KEY è vuoto. Inseriscili nelle impostazioni.
La conferma risponde Busy, retry later: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. ePayco ripete la conferma.
Il cliente vede We could not connect to ePayco: ePayco ha rifiutato PUBLIC_KEY e PRIVATE_KEY. La nota dell'ordine mostra la risposta di ePayco. Copia di nuovo entrambe le chiavi.
Il cliente vede ePayco could not start the payment: ePayco non ha creato la sessione di checkout. Leggi la nota dell'ordine per l'errore di ePayco.
Il checkout di ePayco non si apre: il cliente vede The ePayco checkout could not be loaded. Please reload the page or choose another payment method. Lo script del checkout di ePayco non è stato caricato nella pagina di pagamento dell'ordine. Il cliente può ricaricare la pagina oppure usare Choose another payment method.
Un pagamento di test non ha pagato l'ordine: le transazioni di test non pagano mai gli ordini effettuati in modalità live. Effettua l'ordine di test mentre Test Mode è attivo.
L'ordine è On hold: leggi la nota dell'ordine. ePayco ha segnalato il pagamento come in sospeso, l'importo o la valuta approvati non corrispondevano all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Verifica la transazione nella dashboard di ePayco prima della spedizione.
Il blocco 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.
Per gli sviluppatori, la documentazione del plugin elenca i filtri epc_p_supported_currencies (valute per cui viene offerto il metodo di pagamento), epc_p_session_payload (dati inviati a ePayco) e epc_p_icon (icona del checkout).
Disinstallazione
Disattivare il plugin conserva 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 e i log vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano disponibili per una futura reinstallazione. I dati ePayco salvati negli ordini vengono sempre conservati. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID delle transazioni.
ePayco è un marchio del rispettivo proprietario. Questo plugin non è affiliato a ePayco né approvato da ePayco.