VibeFox Pesapal for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin rifiuta l’attivazione in sua assenza.

PHP: 8.0 o successivo.

Currency: l’ordine deve essere in KES, UGX, TZS, ZMW, RWF o USD. Per altre valute il metodo di pagamento è nascosto nel checkout. L’ordine viene addebitato nella propria valuta; il plugin non converte valute. Gli importi vengono inviati in unità principali, arrotondati alla precisione della valuta (UGX e RWF senza decimali).

Pesapal account: 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 portale sviluppatori). Le chiavi live provengono dal tuo pannello commerciante Pesapal. Non occorre configurare altro nel pannello Pesapal: il plugin registra da solo il proprio URL di notifica. Il sito deve essere raggiungibile da Internet perché Pesapal vi invia le notifiche di pagamento.

VibeFox license key: acquistata su vibefox.net. Una chiave funziona su un 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_pesapal_pay in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Pesapal > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina dei plugin.

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

5. Inserisci chiave e segreto consumer sandbox, attiva Enable/Disable, salva ed effettua un ordine di prova.

6. Inserisci chiave e segreto consumer live, deseleziona Sandbox mode e salva per accettare pagamenti reali.

Configurazione

Tutte le impostazioni sono in una pagina: WooCommerce > Settings > Payments > Pesapal. Sopra i campi un indicatore mostra la modalità: SANDBOX con Test payments on cybqa.pesapal.com — no real money is charged. oppure LIVE con Real payments on pay.pesapal.com. Compare un avviso se mancano le chiavi della modalità corrente (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., o l’equivalente per live) e quando Pesapal non supporta la valuta del negozio. Nell’elenco dei metodi di pagamento, Pesapal è indicato come modalità di prova mentre sandbox è attivo.

Notifiche di pagamento (IPN)

Questo blocco mostra l’URL di notifica del negozio. Ha un aspetto simile a https://your-site/wc-api/pesapal_pay/. L’URL viene registrato automaticamente presso Pesapal al primo pagamento, separatamente per sandbox e live e per ciascuna coppia di chiavi, quindi non c’è nulla da configurare. Dopo il primo pagamento il blocco mostra Registered IPN ID: con l’ID restituito da Pesapal; prima indica Not registered yet for the current mode and keys. L’URL deve essere raggiungibile da Internet: senza modalità manutenzione, firewall o protezione con password che ne impediscano l’accesso.

Checkout

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

Title: il nome del metodo di pagamento che i clienti vedono nel checkout. Predefinito: Pesapal (M-Pesa, Airtel Money, cards).

Description: il testo mostrato sotto il metodo di pagamento nel 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 contiene collegamenti a cybqa.pesapal.com e pesapal.com. Inserisci le chiavi sandbox e live ciascuna nel proprio campo. Tutti i campi delle chiavi sono campi password.

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

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 del tuo pannello commerciante Pesapal. Usata quando la modalità sandbox è disattivata.

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

Il cambio di modalità o delle 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.

Avanzate

Debug log: Log Pesapal requests and notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_pesapal_pay. Errori e avvisi vengono sempre registrati. Chiavi, token e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data: Delete the plugin settings and logs when the plugin is deleted. I dati Pesapal salvati negli ordini (ID di tracciamento, note) sono la cronologia dei pagamenti e vengono sempre conservati. La disattivazione del plugin non elimina mai nulla. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Pesapal (M-Pesa, Airtel Money, cards)) ed effettua l’ordine. In modalità sandbox il blocco Checkout mostra Sandbox mode: no real money will be charged. Il plugin crea una richiesta di pagamento Pesapal per il totale dell’ordine nella valuta dell’ordine, con i dati di fatturazione dell’ordine, e aggiunge una nota con modalità, importo e ID di tracciamento Pesapal. Il cliente viene indirizzato alla pagina di pagamento Pesapal e paga con uno dei metodi offerti da Pesapal, come M-Pesa, Airtel Money, MTN, carta o banca.

L’ordine viene segnato come pagato solo dopo la conferma di Pesapal. Le notifiche Pesapal e il ritorno del cliente non contengono dati di pagamento né firma, quindi il plugin non si fida di essi: per ciascuno richiede a Pesapal lo stato della transazione con una richiesta autenticata tra server, nella modalità in cui è stato avviato il pagamento. Verifica anche che la transazione appartenga a questo ordine e che importo pagato e valuta corrispondano all’ordine.

Dopo il pagamento il cliente torna alla pagina dell’ordine ricevuto. I pagamenti con denaro mobile possono richiedere un momento. Se il pagamento non è ancora confermato, la pagina 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. La notifica di Pesapal completa l’ordine in seguito. Se l’ordine è stato messo in sospeso, la pagina 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 alla pagina Pay for order con 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 cliente può pagare di nuovo lo stesso ordine. Ogni tentativo di pagamento dell’ordine viene ricordato, quindi viene accettato anche un pagamento effettuato più tardi su una vecchia pagina Pesapal dell’ordine.

Se Pesapal non può avviare il pagamento, il cliente vede 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. I dettagli tecnici finiscono nelle note dell’ordine e nel registro. Il totale dell’ordine deve essere maggiore di zero.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con l’archiviazione degli ordini ad alte prestazioni di WooCommerce (HPOS).

Il plugin non prevede un modulo di pagamento nella pagina del checkout stessa (il cliente paga sempre sulla pagina Pesapal), carte salvate, abbonamenti o pagamenti ricorrenti né conversione di valute.

Ordini e rimborsi

Stati degli ordini

Pending payment: il cliente è stato indirizzato a Pesapal e non ha ancora pagato, oppure Pesapal non ha ancora confermato il pagamento.

Processing: Pesapal segnala il pagamento come completato e importo e valuta corrispondono. La nota dell’ordine mostra l’importo, il metodo di pagamento, il codice di conferma Pesapal e l’ID di tracciamento. L’ID della transazione dell’ordine è l’ID di tracciamento Pesapal. Ogni pagamento viene applicato una volta.

On hold: l’importo pagato o la valuta differisce dall’ordine (nota Pesapal amount/currency mismatch — held for review), oppure è arrivato denaro per un ordine annullato prima del pagamento. Controlla il pagamento nel pannello Pesapal, poi completa l’ordine o rimborsa il pagamento.

Failed: Pesapal segnala l’ultimo tentativo di pagamento come fallito. La nota riporta il motivo fornito da Pesapal. Se il cliente riprova dalla pagina Pay for order e anche quel tentativo fallisce, viene aggiunta un’altra nota con il motivo. Il fallimento di un tentativo precedente non modifica l’ordine. Il cliente può pagare di nuovo.

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

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

Rimborsi

Il plugin non invia rimborsi a Pesapal. Rimborsa il pagamento nel pannello Pesapal, poi registra manualmente il rimborso in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza è in cima a WooCommerce > Settings > Payments > Pesapal. 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 ricontrollare lo stato, Change key per inserire un’altra chiave e Remove key per rimuoverla da questo sito. Il collegamento Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera il relativo posto per il dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Pesapal non viene mostrato ai clienti nel checkout. Se viene comunque avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio autenticati 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. Compare un promemoria nella pagina dei plugin e nelle pagine WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono ancora confermati dalla notifica Pesapal e dal ritorno del cliente.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Pesapal non compare nel checkout: controlla che la licenza sia attiva, Enable/Disable sia attivato, chiave e segreto consumer della modalità corrente siano inseriti (Sandbox consumer key e Sandbox consumer secret in sandbox, Live consumer key e Live consumer secret in live) e la valuta dell’ordine sia KES, UGX, TZS, ZMW, RWF o USD. Gli avvisi in cima alle impostazioni indicano il problema. Gli sviluppatori possono cambiare l’elenco delle valute con il filtro pesapal_p_supported_currencies.

Il pagamento è riuscito, ma l’ordine rimane In attesa di pagamento: la notifica Pesapal non ha raggiunto il negozio e il cliente non è tornato. Controlla che l’URL mostrato in Payment notifications (IPN) sia raggiungibile da Internet (senza modalità manutenzione, firewall o protezione con password davanti a /wc-api/pesapal_pay/). Consulta WooCommerce > Status > Logs, origine wcp_pesapal_pay.

Come il negozio risponde alle notifiche: una notifica elaborata riceve una risposta HTTP 200. Quando il plugin non può elaborarla, risponde con un errore e Pesapal invia nuovamente la notifica in seguito: 400 (ID di tracciamento assente o malformato), 404 (nessun ordine di questo negozio ha questo ID di tracciamento), 409 (la transazione appartiene a un altro riferimento commerciante; l’ordine non cambia), 502 (l’API Pesapal non era raggiungibile in quel momento) e 503 (l’ordine veniva aggiornato contemporaneamente dal ritorno del cliente).

Il cliente vede Pesapal is not available at the moment: Pesapal ha rifiutato la chiave o il segreto consumer della modalità corrente. Controlla che le chiavi corrispondano alla modalità: quelle sandbox funzionano solo in sandbox, quelle live solo in live. La nota dell’ordine mostra l’errore Pesapal.

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

L’ordine è In sospeso dopo il pagamento: leggi la nota dell’ordine. L’importo pagato o la valuta differiva dall’ordine, oppure il pagamento è arrivato dopo l’annullamento dell’ordine. Controlla il pagamento nel pannello Pesapal, poi elabora l’ordine o rimborsa il pagamento.

Il blocco della 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

Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave e lo stato della licenza di questo plugin, i token di accesso Pesapal in cache e gli ID di notifica registrati vengono sempre rimossi. Le impostazioni e i registri del plugin (file di registro, inclusi quelli ruotati, e voci di registro nel database dell’origine wcp_pesapal_pay) vengono rimossi solo se Delete data era attivato. Altrimenti rimangono per una futura reinstallazione. Gli ordini esistenti conservano note di pagamento, ID di transazione e ID di tracciamento Pesapal.

Pesapal è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Pesapal né approvato da Pesapal.