VibeFox Pesapal 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: il carrello deve essere in KES, UGX, TZS, ZMW, RWF o USD. Con altre valute il metodo di pagamento non viene mostrato al checkout. Il carrello viene addebitato nella propria valuta; il modulo non converte le valute. Gli importi vengono inviati in unità principali, arrotondati alla precisione della valuta (UGX e RWF senza decimali).

Account Pesapal: ti servono la chiave e il segreto consumer di un account commerciante Pesapal. Le chiavi sandbox e live sono diverse. Le chiavi sandbox provengono da un account commerciante demo su cybqa.pesapal.com (Pesapal pubblica anche chiavi demo sul proprio portale per sviluppatori). Le chiavi live provengono dal pannello commerciante di Pesapal. Nel pannello di Pesapal non c’è altro da configurare: il modulo registra da solo il proprio URL di notifica. Il tuo negozio deve essere raggiungibile da Internet, perché Pesapal gli invia le notifiche di pagamento.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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 Pesapal Pay Gateway nell’elenco dei moduli e fai clic su Configure.

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

4. Inserisci la chiave e il segreto consumer sandbox, attiva Enable/Disable, fai clic su Save ed effettua un ordine di prova.

5. Inserisci la chiave e il segreto consumer live, disattiva Sandbox mode e fai clic su Save per accettare pagamenti reali.

All’installazione il modulo crea lo stato dell’ordine Pesapal payment on hold. PrestaShop attiva il 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 Pesapal Pay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l’intera pagina. Sopra i campi, un badge mostra la modalità: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. oppure LIVE — Real payments on pay.pesapal.com. Compare un avviso quando mancano le chiavi della modalità corrente (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., o lo stesso per live) e quando Pesapal non supporta la valuta predefinita del tuo negozio.

Pesapal

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell’ordine. Predefinito: Pesapal (M-Pesa, Airtel Money, cards). Obbligatorio: un titolo vuoto non viene salvato e resta quello precedente.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Credenziali API

La sezione spiega dove ottenere le chiavi e rimanda a cybqa.pesapal.com e pesapal.com. Inserisci le chiavi sandbox e live, ciascuna nel proprio campo.

Sandbox mode: Use the Pesapal sandbox (no real money). Quando è attivo, i nuovi pagamenti usano cybqa.pesapal.com con le chiavi sandbox. Disattivalo per accettare pagamenti reali su pay.pesapal.com con le chiavi live. Predefinito: attivo.

Sandbox consumer key: la chiave consumer del tuo account commerciante sandbox (demo). Usata solo in modalità sandbox.

Sandbox consumer secret: il segreto consumer del tuo account commerciante sandbox. Usato solo in modalità sandbox.

Live consumer key: la chiave consumer dal pannello commerciante di Pesapal. Usata quando la modalità sandbox è disattivata.

Live consumer secret: il segreto consumer dal pannello commerciante di Pesapal. Usato quando la modalità sandbox è disattivata.

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

Clear saved consumer keys and secrets: spunta la casella e fai clic su Save per rimuovere tutte e quattro le chiavi e i segreti salvati.

Salvare le impostazioni elimina i token di accesso Pesapal in cache. Cambiare modalità o chiavi non riutilizza mai un token di accesso o un ID di notifica dell’altra modalità o di altre chiavi. Un pagamento avviato in una modalità viene sempre verificato in quella modalità, anche dopo il cambio.

Notifiche di pagamento (IPN)

IPN URL: mostra l’URL di notifica del tuo negozio. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_pesapal_pay/webhook, eventualmente con un codice lingua come /en/. L’URL viene registrato automaticamente presso Pesapal al primo pagamento, separatamente per sandbox e live e per ogni coppia di chiavi, quindi non c’è nulla da configurare. Dopo il primo pagamento la sezione mostra Registered IPN ID: con l’ID restituito da Pesapal; prima dice Not registered yet for the current mode and keys. L’URL deve essere raggiungibile da Internet: nessun firewall o protezione con password davanti. Continua a funzionare mentre il negozio è in manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Avanzate

Debug log: Log Pesapal requests and notifications. Scrive i dettagli in logs/pesapal_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche con l’interruttore disattivato. Chiavi, token e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Delete data: Delete the module settings and logs when the module is uninstalled. I dati Pesapal salvati sugli ordini (ID di tracciamento, note) fanno parte dello storico dei pagamenti e vengono sempre conservati. Disattivare il modulo non cancella nulla. Predefinito: disattivato.

Checkout

Al momento del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Pesapal (M-Pesa, Airtel Money, cards)) e ne vede la descrizione. Dopo la conferma, il modulo crea una richiesta di pagamento Pesapal per il totale del carrello nella valuta del carrello, con i dati di fatturazione dell’indirizzo di fatturazione, e invia il cliente alla pagina di pagamento Pesapal. La descrizione del pagamento inviata a Pesapal è Cart, il numero del carrello e il nome del negozio. Lì il cliente paga con uno dei metodi offerti da Pesapal, come M-Pesa, Airtel Money, MTN, carta o bonifico. A questo punto non esiste ancora alcun ordine.

L’ordine viene segnato come pagato solo dopo la conferma di Pesapal. Le notifiche di Pesapal e il ritorno del cliente non contengono dati di pagamento né firma, quindi il modulo non si fida: per ciascuno chiede a Pesapal lo stato della transazione con una richiesta autenticata tra server, nella modalità in cui il pagamento è stato avviato. Verifica inoltre che la transazione appartenga a questo carrello e che l’importo e la valuta pagati corrispondano al carrello. Poi l’ordine viene creato e il cliente vede la pagina standard di conferma dell’ordine.

I pagamenti con denaro mobile possono richiedere un momento. Se al ritorno del cliente Pesapal non ha ancora confermato il pagamento, una pagina Payment confirmation mostra Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. con i pulsanti Check again e Back to checkout. La notifica di Pesapal crea l’ordine non appena il pagamento è confermato. Se l’ordine è stato messo in sospeso, la pagina di conferma mostra Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Se il cliente annulla sulla pagina Pesapal, torna al checkout con il messaggio The Pesapal payment was cancelled. You can try again or choose another payment method. Se il pagamento non riesce, il messaggio è The Pesapal payment was not successful. Please try again or choose another payment method. Il carrello viene conservato e il cliente può pagare di nuovo. Ogni tentativo di pagamento del carrello viene ricordato, quindi anche un pagamento effettuato più tardi su una pagina Pesapal precedente del carrello viene accettato.

Se Pesapal non può avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (chiavi errate) oppure Pesapal could not start the payment: seguito dal motivo fornito da Pesapal. Il motivo tecnico viene scritto nel registro. Il totale dell’ordine deve essere maggiore di zero.

Il modulo non ha moduli di pagamento sul tuo sito (il cliente paga sempre nella pagina Pesapal), né carte salvate, né abbonamenti o pagamenti ricorrenti, né conversione di valuta.

Ordini e rimborsi

Stati dell’ordine

Nessun ordine ancora: il cliente è stato inviato a Pesapal e non ha pagato, il pagamento non è riuscito, oppure Pesapal non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: Pesapal indica il pagamento come completato e importo e valuta corrispondono. Il pagamento viene registrato con l’ID di tracciamento Pesapal come ID della transazione, e una nota mostra l’importo, il metodo di pagamento, il codice di conferma Pesapal e l’ID di tracciamento. Ogni pagamento viene applicato una sola volta.

Pesapal payment on hold: l’importo o la valuta pagati differiscono dal carrello (nota Pesapal amount/currency mismatch — held for review), oppure è arrivato denaro per un ordine che era stato annullato. L’importo effettivamente pagato viene registrato sull’ordine quando è nella valuta dell’ordine. Verifica il pagamento nel pannello di Pesapal, poi completa l’ordine o rimborsa il pagamento.

Refunded: Pesapal segnala che il pagamento che ha saldato l’ordine è stato stornato. Lo storno di un altro tentativo viene solo annotato sull’ordine.

Se anche un secondo tentativo di pagamento di un carrello già pagato va a buon fine, l’ordine non cambia. Una nota ti chiede di rimborsare il secondo pagamento nel pannello di Pesapal. Gli ordini annullati e rimborsati non vengono mai riaperti automaticamente.

Blocco pagamento Pesapal

La pagina dell’ordine mostra un blocco Pesapal payment con un badge Sandbox o Live, l’ID di tracciamento, il riferimento commerciante, lo stato Pesapal, il metodo di pagamento, il codice di conferma, l’importo richiesto e quello pagato, il motivo di una verifica, tutti i Payment attempts del carrello e le Payment notes dell’ordine. Il blocco è di sola lettura.

Rimborsi

Il modulo non invia rimborsi a Pesapal. Rimborsa il pagamento nel pannello di Pesapal, poi registra manualmente il rimborso in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Pesapal Pay Gateway è il primo blocco di Modules > Module Manager > VibeFox Pesapal Pay 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 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 compaiono la riga Product: presta-payment-pesapal 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 oppure License expired on seguito da una data. Dopo un cambio dell’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 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, Pesapal non viene mostrato ai clienti al checkout. Se viene avviato comunque un pagamento, il cliente vede This payment method is not available. Please choose another one. La vetrina di 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 puoi provarlo 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, e le notifiche di Pesapal sui pagamenti esistenti, compresi gli storni, continuano a essere applicate.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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 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

Pesapal non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la chiave e il segreto consumer della modalità corrente siano inseriti (Sandbox consumer key e Sandbox consumer secret in modalità sandbox, Live consumer key e Live consumer secret in modalità live) e che la valuta del carrello sia KES, UGX, TZS, ZMW, RWF o USD. Gli avvisi in cima alle impostazioni indicano il problema. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. Gli sviluppatori possono cambiare l’elenco delle valute con l’hook actionPesapalSupportedCurrencies.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la notifica di Pesapal non è arrivata al tuo negozio e il cliente non è tornato. Verifica che l’URL mostrato in IPN URL sia raggiungibile da Internet (nessun firewall o protezione con password davanti). Attiva Debug log e controlla il campo Log nella pagina del modulo.

Come risponde il negozio alle notifiche: una notifica elaborata riceve HTTP 200. Quando il modulo non riesce a elaborarla, risponde con un errore e Pesapal invia di nuovo la notifica più tardi: 400 (ID di tracciamento mancante o non valido), 404 (nessun carrello di questo negozio ha quell’ID di tracciamento), 409 (la transazione appartiene a un altro riferimento commerciante; non viene modificato nulla), 502 (in quel momento non è stato possibile raggiungere l’API Pesapal, oppure mancano le chiavi della modalità in cui è stato avviato il pagamento) e 503 (il carrello era in aggiornamento per il ritorno del cliente nello stesso momento, oppure non è stato possibile creare l’ordine, per esempio perché il modulo è disattivato).

Il cliente vede Pesapal is not available at the moment: Pesapal ha rifiutato la chiave o il segreto consumer della modalità corrente. Verifica che le chiavi corrispondano alla modalità: le chiavi sandbox funzionano solo con la sandbox, le chiavi live solo in modalità live. Il registro mostra l’errore di Pesapal.

Il cliente vede Pesapal is temporarily unavailable: Pesapal non era raggiungibile, oppure non è stato possibile registrare l’URL di notifica. Leggi il registro e riprova.

I pagamenti di una modalità precedente non vengono confermati dopo il cambio: un pagamento viene verificato con le chiavi della modalità in cui è stato avviato. Mantieni inserite le chiavi di quella modalità finché i suoi pagamenti non sono confermati.

L’ordine è in Pesapal payment on hold dopo il pagamento: leggi le note nel blocco Pesapal payment. L’importo o la valuta pagati non corrispondevano al carrello, oppure il pagamento è arrivato dopo che l’ordine era stato annullato. Verifica il pagamento nel pannello di Pesapal, poi elabora l’ordine o rimborsa il pagamento.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Pesapal Pay Gateway e scegli Uninstall. La chiave di licenza e lo stato di licenza di questo modulo vengono sempre rimossi. I token di accesso Pesapal in cache e gli ID di notifica registrati vengono sempre rimossi. Se Delete data è attivo, vengono rimosse anche le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una eventuale reinstallazione. I tentativi di pagamento Pesapal e lo stato dell’ordine Pesapal payment on hold vengono sempre conservati. I singoli ordini mantengono le loro note di pagamento, gli ID di transazione e gli ID di tracciamento Pesapal.

Pesapal è un marchio dei rispettivi titolari. Questo modulo non è affiliato a Pesapal né approvato da Pesapal.