VibeFox Hubtel for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

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

PHP: 8.0 o successivo.

Valuta: solo cedi ghanese (GHS). Il metodo di pagamento viene nascosto al checkout per le altre valute. Mantieni il numero di decimali di WooCommerce su 2, perché Hubtel addebita pesewa interi.

Account Hubtel: un account aziendale Hubtel con chiavi API (API ID e API Key) e il numero di account commerciante (POS Sales ID). Le chiavi si trovano nella dashboard aziendale di Hubtel su bo.hubtel.com in Programmable keys.

Whitelisting degli IP: Hubtel risponde alla sua Transaction Status API solo da indirizzi IP di server inseriti nella whitelist. Chiedi a Hubtel (al tuo account manager o a support@hubtel.com) di inserire nella whitelist l'indirizzo IP pubblico del tuo server web. Fino ad allora i pagamenti non potranno essere confermati e gli ordini rimarranno In attesa di pagamento.

Nessun ambiente di test: Hubtel non ha una sandbox pubblica. Tutti i pagamenti sono reali.

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. Puoi anche caricare la cartella wcp_hubtel_pay in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

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

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

5. Inserisci l'API ID, l'API Key e il numero di account commerciante (POS Sales ID).

6. Chiedi al supporto di Hubtel di inserire l'IP del tuo server nella whitelist per la Transaction Status API.

7. Attiva Enable/Disable. L'URL di callback viene inviato a Hubtel con ogni pagamento, quindi non è necessario configurare nulla nella dashboard di Hubtel.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > Hubtel. Sopra i campi la pagina ti avvisa quando mancano l'API ID, l'API Key o il numero di account commerciante e quando la valuta del negozio non è GHS. In entrambi i casi Hubtel viene nascosto al checkout. Ti avvisa inoltre se il negozio utilizza più di 2 decimali. Nell'elenco dei metodi di pagamento il gateway viene contrassegnato come da configurare finché le credenziali non vengono inserite.

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Mobile Money or card (Hubtel).

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Credenziali API di Hubtel

Copia l'API ID e l'API Key dalla tua dashboard aziendale di Hubtel: bo.hubtel.com > Programmable keys. Il numero di account commerciante è il POS Sales ID del tuo account Hubtel. La sezione ripete anche l'avviso relativo al whitelisting degli IP.

API ID (Client ID): l'API ID delle tue chiavi programmabili di Hubtel.

API Key (Client Secret): l'API Key delle tue chiavi programmabili di Hubtel. Conservala al sicuro.

Merchant account number (POS Sales ID): i pagamenti vengono riscossi in questo account Hubtel e verificati rispetto ad esso.

Conferma del pagamento

Il callback comunica al tuo negozio che è stato effettuato un pagamento. L'URL di callback mostrato in questa sezione viene inviato a Hubtel con ogni pagamento, quindi non occorre configurare nulla nella dashboard di Hubtel. Ha un formato simile a https://your-site/wc-api/hubtel_pay/. Deve essere raggiungibile da Internet: nessuna modalità di manutenzione, protezione con password o firewall che blocchi Hubtel.

I callback di Hubtel non sono firmati. Il plugin estrae dal callback solo il riferimento di pagamento; tale riferimento deve appartenere a un ordine del tuo negozio. Lo stato, l'importo e l'ID della transazione provengono sempre dalla Transaction Status API di Hubtel. L'ordine viene contrassegnato come pagato solo dopo che tale API ha confermato il pagamento e il relativo importo. Se non è possibile raggiungere Hubtel, il pagamento viene ricontrollato automaticamente in background, e puoi verificarlo dalla schermata dell'ordine con Order actions > Check Hubtel payment status.

Avanzate

Debug log: Log API calls and callbacks in WooCommerce > Status > Logs, origine wcp_hubtel_pay, senza chiavi o dati dei clienti. Gli errori vengono sempre registrati. Predefinito: disattivato.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Mobile Money or card (Hubtel)) ed effettua l'ordine. Il plugin crea un checkout Hubtel per l'importo totale dell'ordine in GHS e indirizza il cliente alla pagina di pagamento di Hubtel. Il pagamento compare lì come Order #, seguito dal numero dell'ordine e dal nome del tuo sito. Sulla pagina di Hubtel il cliente paga con MTN MoMo, Telecel Cash, AirtelTigo Money, una carta Visa o Mastercard o GhQR. Ogni clic su Place order o Pay genera un nuovo tentativo di pagamento con un proprio riferimento, e le pagine Hubtel precedenti dello stesso ordine rimangono pagabili.

Dopo il pagamento il cliente torna alla pagina di conferma dell'ordine. L'ordine viene contrassegnato come pagato solo dopo che Hubtel lo ha confermato tramite la Transaction Status API: tramite il callback, tramite la verifica eseguita al rientro del cliente, tramite un controllo in background o tramite l'azione dell'ordine. Un callback e un ritorno che arrivano nello stesso momento vengono elaborati l'uno dopo l'altro, quindi l'ordine non viene mai completato due volte. Se Hubtel non ha ancora confermato il pagamento, la pagina mostra We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se l'ordine è stato messo in sospeso, mostra Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Se il cliente preme Cancel sulla pagina di Hubtel, il plugin verifica prima se il pagamento è stato comunque effettuato. In caso negativo, il cliente torna alla pagina Pay for order con il messaggio The Hubtel payment was cancelled. You can try again or choose another payment method.

Se Hubtel non riesce ad avviare il pagamento, il cliente visualizza un breve messaggio, ad esempio Could not connect to Hubtel. Please try again in a moment., Hubtel could not start the payment. Please try again or choose another payment method. o, in caso di credenziali errate, Hubtel payments are not available at the moment. Please choose another payment method. I dettagli vengono registrati nel log.

Il metodo di pagamento funziona sul checkout classico, sul blocco Checkout e sulla pagina Pay for order. È compatibile con l'High-Performance Order Storage (HPOS) di WooCommerce.

Il plugin non supporta rimborsi da WooCommerce, abbonamenti, carte salvate né la scelta del canale di pagamento all'interno di WooCommerce.

Ordini

Stati dell'ordine

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

Processing: il pagamento è stato confermato. Gli ordini contenenti solo prodotti virtuali scaricabili passano a Completato, l'impostazione predefinita di WooCommerce. La nota dell'ordine mostra l'importo, la transazione Hubtel, il metodo di pagamento e il riferimento. L'ID della transazione corrisponde all'ID della transazione Hubtel.

On hold: Hubtel ha segnalato un importo pagato che differisce dal totale dell'ordine, oppure l'ordine non è in GHS (nota Hubtel amount/currency mismatch); oppure è arrivato un pagamento per un ordine che era stato annullato. L'ordine non è stato contrassegnato come pagato. Verifica il pagamento nella dashboard di Hubtel e completa o rimborsa l'ordine manualmente.

Failed: Hubtel ha segnalato che l'ultimo tentativo di pagamento di un ordine in attesa di pagamento è fallito, e la Transaction Status API conferma che non è pagato. Il cliente può riprovare dall'ordine. Un errore segnalato solo da un callback non fa mai fallire un ordine.

Se un altro tentativo di un ordine già pagato viene a sua volta pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nella tua dashboard di Hubtel. Un ordine annullato o rimborsato non viene mai riaperto automaticamente. Quando Hubtel segnala un pagamento come rimborsato, all'ordine viene aggiunta una nota.

Verifiche del pagamento

Circa 20 minuti dopo che il cliente è stato indirizzato su Hubtel, un controllo in background (WooCommerce Action Scheduler) richiede a Hubtel lo stato del pagamento, nel caso in cui il callback sia andato perso e il cliente non sia tornato. Un tentativo non pagato viene controllato ancora una volta dopo un'ora. Quando non è possibile raggiungere l'API di Hubtel, il controllo viene ripetuto fino a 5 volte con intervalli crescenti.

L'azione dell'ordine Check Hubtel payment status controlla gli ultimi tentativi dell'ordine (fino a 5, dal più recente), applica il risultato e aggiunge una nota con lo stato di ciascun tentativo.

Rimborsi

I rimborsi da WooCommerce non sono supportati. Rimborsa il pagamento nella dashboard di Hubtel, quindi crea un rimborso manuale in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova nella parte superiore di WooCommerce > Settings > Payments > Hubtel. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino a cui la licenza è attiva e il tuo dominio. Usa Check now per controllare nuovamente 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 su vibefox.net.

Una chiave funziona su un solo dominio. La rimozione della chiave da un sito non libera il posto del dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Hubtel non viene mostrato ai clienti al checkout. Se viene comunque avviato un pagamento, il cliente visualizza 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 come (unlicensed — visible to admins only), in modo da poter configurare e testare il plugin prima di acquistare una chiave. Un promemoria viene mostrato nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati continuano a essere confermati.

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

Risoluzione dei problemi

Hubtel non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che l'API ID, l'API Key e il numero di account commerciante siano compilati e che la valuta sia GHS. Nella pagina Pay for order fa fede la valuta dell'ordine. La pagina delle impostazioni mostra un avviso se le credenziali o la valuta sono errate.

Il pagamento è andato a buon fine, ma l'ordine rimane In attesa di pagamento: non è stato possibile confermare il pagamento. Apri WooCommerce > Status > Logs, origine wcp_hubtel_pay. Un codice HTTP 401 o 403 nel controllo dello stato indica che le chiavi API sono errate o che l'IP del server non è nella whitelist di Hubtel. Verifica anche che l'URL di callback sia raggiungibile da Internet. Dopo aver risolto, apri l'ordine ed esegui Order actions > Check Hubtel payment status. Anche i controlli in background confermano l'ordine non appena Hubtel risponde.

Il callback risponde Unknown reference: il riferimento di pagamento non appartiene a un ordine di questo negozio.

Il callback risponde Payment status unavailable: non è stato possibile raggiungere la Transaction Status API o la richiesta è stata rifiutata. Il pagamento viene ricontrollato in background.

L'ordine è in sospeso con una nota di mancata corrispondenza di importo o valuta: Hubtel ha segnalato un importo pagato che differisce dal totale dell'ordine, oppure l'ordine non è in GHS. Verifica il pagamento nella dashboard di Hubtel e completa o rimborsa l'ordine manualmente.

Il cliente visualizza un errore al momento dell'ordine: attiva Debug log e controlla il registro. Chiavi API errate generano Hubtel payments are not available at the moment. Un problema di connessione genera Could not connect to Hubtel.

Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Ad esempio, se la chiave è già utilizzata 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.

Per gli sviluppatori: il filtro hubtel_p_icon modifica l'icona del metodo di pagamento, e hubtel_p_payment_description modifica la descrizione del pagamento sulla pagina di Hubtel (fino a 100 caratteri).

Disinstallazione

Disattivando il plugin, tutti i dati vengono mantenuti; vengono annullati solo i controlli di pagamento in background in sospeso. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le opzioni proprie del plugin, i controlli in background in sospeso e i registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti rimangono per una successiva reinstallazione. I dati di Hubtel salvati negli ordini costituiscono la cronologia dei pagamenti e vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

Hubtel è un marchio del rispettivo titolare. Questo plugin non è affiliato a Hubtel né approvato da Hubtel.