VibeFox ePayco for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non può essere installato su versioni precedenti di PHP.

Valuta: peso colombiano (COP) o dollaro statunitense (USD). Per i carrelli in altre valute il metodo di pagamento viene nascosto 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 di produzione. 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 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. 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 trova più tardi VibeFox ePayco Payment nell'elenco dei moduli e clicca su Configure.

3. Inserisci la chiave di licenza VibeFox in License key, nel blocco licenza in alto nella pagina Configure, e clicca su Activate (vedi Chiave di licenza).

4. Inserisci le quattro chiavi ePayco e scegli il tipo di checkout (vedi Configurazione).

5. Attiva Enable/Disable e clicca su Save. Prova un pagamento con Test Mode attivo e con le carte di test di ePayco, poi disattiva Test Mode.

All'installazione il modulo crea due stati dell'ordine, Awaiting ePayco payment e ePayco payment on hold. PrestaShop attiva 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 ePayco Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando non sono inserite tutte e quattro le chiavi (il metodo di pagamento viene allora nascosto al checkout) e quando la valuta predefinita 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.

ePayco

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

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 pubblica API di ePayco.

Private Key (PRIVATE_KEY): la tua chiave privata API di ePayco. Tienila segreta.

Le chiavi segrete salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Cancellare le chiavi segrete salvate: spunta Secret Key (P_KEY) o Private Key (PRIVATE_KEY) e clicca su Save per rimuovere la chiave. Un campo vuoto mantiene il valore salvato.

Test Mode: le sessioni di checkout vengono create 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à di produzione. Predefinito: disattivato. Quando è attiva, i clienti vedono TEST MODE — use ePayco test cards, no real money is charged. sotto il metodo di pagamento e nella pagina di pagamento.

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. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_epayco_payment/confirmation, eventualmente con un codice lingua come /en/. Deve essere raggiungibile da internet, senza essere bloccato da un firewall o dall'autenticazione di base. Funziona anche quando il negozio è in manutenzione e non viene bloccato dalla restrizione per paese del negozio.

Ogni conferma deve avere 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 nulla. Senza la conferma, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Avanzate

Logging: scrive gli errori API e le conferme di pagamento in logs/epc_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono registrati. Predefinito: disattivato. Gli errori vengono sempre registrati, anche quando è disattivato.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo e il registro. I dati ePayco salvati per gli ordini e gli stati d'ordine del modulo restano sempre, così gli ordini esistenti continuano a funzionare. Predefinito: disattivato.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita ePayco) e conferma. Il modulo crea una sessione di checkout ePayco per il totale del carrello nella valuta del carrello, con tasse, numero del carrello e nome di fatturazione, indirizzo, e-mail e telefono. Il pagamento compare in ePayco come Cart # e il numero del carrello. La lingua del checkout è lo spagnolo o l'inglese, in base alla lingua del negozio. In questo momento non esiste ancora alcun ordine.

Il cliente vede quindi la pagina ePayco payment con 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, a seconda di Checkout Type. La pagina contiene anche il pulsante Pay with ePayco e il link Choose another payment method. Ogni clic sul pulsante di pagamento crea una nuova sessione di ePayco.

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 quando ePayco lo conferma: tramite la conferma firmata oppure tramite una richiesta lato server a ePayco quando il cliente torna. Il solo ritorno del cliente non paga mai un ordine. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine.

Per un pagamento in sospeso (ad esempio PSE o contanti) l'ordine viene creato in Awaiting ePayco payment e la pagina di conferma mostra Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Se il pagamento in sospeso viene rifiutato o scade in seguito, la pagina mostra Your ePayco payment was not completed. Please contact us about this order. Se ePayco non ha ancora confermato il pagamento quando il cliente torna, compare una pagina Payment confirmation con We are waiting for ePayco to confirm your payment. This page does not need to stay open. e il pulsante Check again.

Se il pagamento è stato rifiutato, il cliente torna al checkout con 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. Il carrello viene conservato e non viene creato alcun ordine.

Se ePayco non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, ad esempio We could not connect to ePayco. Please try again in a moment or choose another payment method. Il motivo tecnico viene scritto nel registro.

Il modulo accetta solo pagamenti una tantum. Non prevede rimborsi dal negozio, carte salvate, abbonamenti o pagamenti suddivisi, e non interroga periodicamente ePayco sulle transazioni in sospeso: gli ordini vengono aggiornati dalla conferma di ePayco e dal ritorno del cliente.

Ordini

Stati dell'ordine

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

Payment accepted: ePayco ha approvato il pagamento. Il pagamento viene registrato con il riferimento ePayco (ref_payco) come ID transazione, e una nota mostra il riferimento, lo stato, l'importo, il metodo di pagamento e il codice di approvazione.

Awaiting ePayco payment: ePayco ha segnalato il pagamento come in sospeso o trattenuto, per esempio un bonifico PSE o un pagamento in contanti. L'ordine cambia automaticamente quando ePayco approva o rifiuta il pagamento.

ePayco payment on hold: ePayco ha approvato un pagamento il cui importo o la cui valuta differisce dall'ordine (per esempio, il carrello è stato modificato dopo l'avvio del pagamento), oppure ha approvato un pagamento dopo che l'ordine era stato annullato. L'importo effettivamente pagato viene registrato sull'ordine quando la valuta corrisponde. Non spedire prima di aver verificato la transazione nella dashboard di ePayco.

Payment error: un pagamento in sospeso è stato rifiutato, non è riuscito, è scaduto o è stato annullato. La nota mostra il motivo fornito da ePayco. Un nuovo pagamento approvato per il carrello paga comunque l'ordine. Un errore tardivo non cambia mai un ordine pagato.

Refunded: ePayco ha stornato 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à di produzione, e una transazione già associata a un altro ordine, vengono ignorate con una nota.

Blocco pagamento ePayco

La pagina dell'ordine mostra un blocco ePayco payment con il riferimento ePayco (ref_payco), l'ID transazione, lo stato, il metodo di pagamento, il codice di approvazione, la data della transazione, un badge Test mode per i pagamenti di test e le ePayco notes dell'ordine. Per un ordine in ePayco payment on hold il blocco mostra un avviso di verificare la transazione prima della spedizione.

Rimborsi

I rimborsi dal negozio non sono supportati. Rimborsa il pagamento nella dashboard di ePayco, poi aggiorna manualmente l'ordine in PrestaShop se necessario. Uno storno della transazione di pagamento segnalato da ePayco imposta l'ordine su Refunded.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza License — VibeFox ePayco Payment è il primo blocco di Modules > Module Manager > VibeFox ePayco Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopo, il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale 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 di essi ci sono la riga Product: presta-payment-epayco 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 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, per 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 è cambiato, o dopo aver liberato un posto 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 solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto 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. Il negozio PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a 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 vengono comunque confermati.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene controllato di nuovo 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

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 carrello sia COP o USD. La pagina delle impostazioni mostra un avviso quando mancano delle chiavi. 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: 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 un firewall, da un modulo di sicurezza o dall'autenticazione di base. Controlla il campo Log nella pagina del modulo; attiva Logging per vedere ogni conferma. L'ordine viene creato 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 incassato 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 «Order not found»: la conferma si riferisce a un carrello senza un pagamento ePayco di questo negozio.

La conferma risponde «Busy, retry later»: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento, oppure l'ordine non è stato possibile crearlo (per esempio perché il modulo è disattivato). ePayco ripete la conferma. Il motivo è nel registro.

Il cliente vede «We could not connect to ePayco»: ePayco ha rifiutato PUBLIC_KEY e PRIVATE_KEY. Il registro mostra la risposta di ePayco. Copiali di nuovo entrambi.

Il cliente vede «ePayco could not start the payment»: ePayco non ha creato la sessione di checkout. Leggi nel registro 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. Il cliente può ricaricare la pagina o 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à di produzione. Effettua l'ordine di test mentre Test Mode è attivo.

L'ordine è in ePayco payment on hold: leggi le note nel blocco ePayco payment (vedi Stati dell'ordine) e verifica la transazione nella dashboard di ePayco prima della spedizione.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox ePayco 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, vengono rimosse le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati ePayco salvati per gli ordini e gli stati d'ordine Awaiting ePayco payment e ePayco payment on hold restano sempre. Gli ordini esistenti conservano le loro note di pagamento e gli ID transazione.

ePayco è un marchio di proprietà del rispettivo titolare. Questo modulo non è affiliato a ePayco né approvato da ePayco.