VibeFox Hubtel for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione cURL. Il modulo non si installa senza di esse.

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

Account Hubtel: un account aziendale Hubtel con le 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.

Whitelist IP: Hubtel risponde alla sua Transaction Status API solo dagli indirizzi IP dei server inseriti nella whitelist. Chiedi a Hubtel (il tuo account manager o support@hubtel.com) di inserire nella whitelist l'indirizzo IP pubblico del tuo server web. Fino ad allora i pagamenti non possono essere confermati e non viene creato alcun ordine.

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

Cron: si consiglia un cron job del server che richiami ogni 5 minuti l'URL cron del modulo per i controlli dei pagamenti in background (vedi Configurazione).

Chiave di licenza VibeFox: acquistabile 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 Hubtel 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 API ID, API Key e numero di account commerciante (POS Sales ID).

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

6. Aggiungi al cron del tuo server l'URL cron mostrato nella pagina Configure.

7. Attiva Enable/Disable e fai clic su Save. L'URL di callback viene inviato a Hubtel con ogni pagamento, quindi non serve configurare nulla nella dashboard di Hubtel.

All'installazione il modulo crea lo stato dell'ordine Hubtel payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa se mancano API ID, API Key o numero di account commerciante e se la valuta predefinita del negozio non è GHS. In entrambi i casi Hubtel viene nascosto nel checkout. Avvisa anche se la valuta GHS usa più di 2 decimali.

Hubtel

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 nel checkout. È anche il nome del metodo di pagamento memorizzato nell'ordine. Predefinito: Mobile Money or card (Hubtel). Obbligatorio: un titolo vuoto genera l'errore Enter a title for the payment method.

Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. Verrai reindirizzato a Hubtel per completare il pagamento.

Credenziali API di Hubtel

Copia API ID e 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 sulla whitelist IP.

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

API Key (Client Secret): l'API Key delle tue chiavi programmabili Hubtel. Tienila riservata. La chiave salvata non viene mai mostrata di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarla.

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

Clear saved API Key: spunta la casella e fai clic su Save per rimuovere l'API Key salvata. Un campo vuoto mantiene il valore salvato.

Conferma del pagamento

Callback URL: il callback comunica al tuo negozio che è stato effettuato un pagamento. Questo URL viene inviato a Hubtel con ogni pagamento, quindi non serve configurare nulla nella dashboard di Hubtel. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_hubtel_pay/callback, eventualmente con un codice lingua. Deve essere raggiungibile da Internet: niente protezione con password né firewall che blocchi Hubtel. Il callback funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del negozio.

I callback di Hubtel non sono firmati. Il modulo prende dal callback solo il riferimento del pagamento; il riferimento deve appartenere a un pagamento del tuo negozio. Stato, importo e ID transazione provengono sempre dalla Transaction Status API di Hubtel. L'ordine viene creato come pagato solo dopo che questa API ha confermato il pagamento e il suo importo.

Controlli dei pagamenti in background (cron): l'URL cron con un token segreto. Richiamalo ogni 5 minuti dal cron del tuo server, per esempio con curl. I pagamenti senza conferma vengono quindi ricontrollati automaticamente con Hubtel: 20 minuti dopo che il cliente è stato inviato a Hubtel, di nuovo dopo un'ora se il pagamento risulta ancora non pagato, e fino a 5 volte con intervalli crescenti quando Hubtel non è stato raggiungibile. Tieni riservato l'URL.

Avanzate

Debug log: registra le chiamate API e i callback in logs/hubtel_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Chiavi e dati dei clienti non vengono registrati. Errori e avvisi vengono sempre registrati, anche quando questa opzione è disattivata. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni e il registro di questo modulo. I dati Hubtel salvati per gli ordini e lo stato dell'ordine Hubtel payment on hold restano sempre. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Mobile Money or card (Hubtel)) e conferma. Il modulo crea un checkout Hubtel per il totale del carrello in GHS e invia il cliente alla pagina di pagamento di Hubtel. Il pagamento vi compare come Cart #, il numero del carrello e il nome del tuo negozio. Sulla pagina di Hubtel il cliente paga con MTN MoMo, Telecel Cash, AirtelTigo Money, una carta Visa o Mastercard o GhQR. In questa fase non esiste ancora alcun ordine. Ogni conferma nel passaggio di pagamento crea un nuovo tentativo di pagamento con un proprio riferimento, e le pagine Hubtel precedenti dello stesso carrello restano pagabili.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene contrassegnato come pagato solo quando Hubtel lo conferma tramite la Transaction Status API: con il callback, con il controllo effettuato al ritorno del cliente, con un controllo in background o con il pulsante nella pagina dell'ordine. Un callback e un ritorno che arrivano nello stesso momento vengono gestiti uno dopo l'altro, quindi l'ordine non viene mai creato due volte. Il cliente vede poi la normale pagina di conferma dell'ordine. Se l'ordine è stato messo in sospeso, la pagina mostra Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Se Hubtel non ha ancora confermato il pagamento quando il cliente torna, compare una pagina Payment confirmation con il messaggio 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. e i pulsanti Check again e Back to checkout. L'ordine viene creato appena Hubtel conferma il pagamento. Se Hubtel ha già segnalato questo tentativo di pagamento come fallito, il cliente torna al checkout con The Hubtel payment was not completed. You can try again or choose another payment method. Il carrello viene conservato.

Se il cliente preme Cancel nella pagina di Hubtel, il modulo verifica prima se il pagamento è stato comunque effettuato. In caso contrario, il cliente torna al checkout con The Hubtel payment was cancelled. You can try again or choose another payment method. Il carrello viene conservato. Un pagamento successivo dalla pagina Hubtel annullata viene comunque accettato.

Se Hubtel non riesce ad avviare il pagamento, il cliente resta nel checkout con un breve messaggio, per 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. oppure, con credenziali errate, Hubtel payments are not available at the moment. Please choose another payment method. I dettagli finiscono nel registro.

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

Ordini

Stati dell'ordine

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

Payment accepted: il pagamento è stato confermato per l'esatto totale del carrello in GHS. Il pagamento viene registrato con l'ID della transazione Hubtel e una nota mostra l'importo, la transazione Hubtel, il metodo di pagamento e il riferimento.

Hubtel payment on hold: Hubtel ha segnalato un importo pagato diverso dal totale del carrello, oppure il carrello non è in GHS. L'ordine non è stato contrassegnato come pagato; l'importo effettivamente incassato da Hubtel viene registrato come pagamento e una nota spiega la discrepanza. Verifica il pagamento nella dashboard di Hubtel ed evadi l'ordine oppure rimborsalo manualmente. Se un altro tentativo dello stesso carrello viene pagato più tardi per l'importo corretto, l'ordine passa a Payment accepted.

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

Blocco pagamento Hubtel

La pagina dell'ordine mostra un blocco Hubtel payment con tutti i tentativi di pagamento del carrello dell'ordine: data, riferimento, pagina di pagamento Hubtel, importo, stato Hubtel, transazione e risultato. Sotto i tentativi elenca le Hubtel notes dell'ordine, dalla più recente.

Il pulsante Check Hubtel payment status controlla gli ultimi tentativi dell'ordine (fino a 5, dal più recente, fermandosi appena l'ordine è pagato), applica il risultato e aggiunge una nota con lo stato di ciascun tentativo. Il risultato viene mostrato nel blocco. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine dei moduli. Il pulsante è disponibile quando l'ordine esiste. Un carrello pagato senza ordine viene confermato dal callback, dal ritorno del cliente o dal cron.

Rimborsi

I rimborsi da PrestaShop non sono supportati. Rimborsa il pagamento nella dashboard di Hubtel, poi registra il rimborso in PrestaShop. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Hubtel.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Hubtel Pay Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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-hubtel 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 incluse le lingue inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo aver cambiato l'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: quello 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, Hubtel non viene mostrato ai clienti nel checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo nel checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati anche dai controlli dei pagamenti in background.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato 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. Per il controllo della licenza non serve alcun cron job. La disinstallazione o il ripristino del modulo rimuovono sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Hubtel non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che API ID, API Key e numero di account commerciante siano compilati e che la valuta del carrello sia GHS. In Payment > Preferences verifica che il modulo sia consentito per GHS, per il paese del cliente e per il gruppo del cliente. La pagina delle impostazioni mostra un avviso quando le credenziali o la valuta sono errate.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il pagamento non è stato confermato. Attiva Debug log e controlla il campo Log nella pagina del modulo. HTTP 401 o 403 nel controllo dello stato indica che le chiavi API sono errate oppure che l'IP del server non è nella whitelist di Hubtel. Verifica anche che l'URL di callback sia raggiungibile da Internet e che venga richiamato l'URL cron. Appena Hubtel risponde, il callback successivo, il controllo in background o il ritorno del cliente creerà l'ordine.

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

Il callback risponde Payment status unavailable: la Transaction Status API non era raggiungibile o ha rifiutato la richiesta, oppure il carrello era in fase di conferma da un'altra richiesta nello stesso momento. Il pagamento viene ricontrollato in background dopo 5 minuti.

Il callback risponde Gateway not configured: mancano API ID, API Key o numero di account commerciante. Compilali; il pagamento viene ricontrollato in background.

Il callback risponde Invalid request o Invalid ClientReference: la richiesta non conteneva un callback Hubtel valido.

L'URL di callback nel browser mostra Method not allowed: è normale. L'URL accetta solo richieste da Hubtel.

L'URL cron risponde Forbidden: il token nell'URL è errato. Copia l'URL cron esattamente come appare nelle impostazioni.

L'ordine è Hubtel payment on hold: leggi le note nel blocco Hubtel payment (vedi Stati dell'ordine), verifica il pagamento nella dashboard di Hubtel ed evadi l'ordine oppure rimborsalo manualmente.

Il cliente vede un errore scegliendo Hubtel: attiva Debug log e controlla il registro. Chiavi API errate danno Hubtel payments are not available at the moment. Un problema di connessione dà Could not connect to Hubtel. Un carrello in un'altra valuta dà Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.

Per gli sviluppatori: l'hook actionWcpHubtelPayIcon modifica l'icona del metodo di pagamento, e actionWcpHubtelPayPaymentDescription modifica la descrizione del pagamento nella pagina di Hubtel (fino a 100 caratteri).

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Hubtel Pay Gateway 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 e il registro di questo modulo. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati Hubtel salvati per gli ordini e lo stato dell'ordine Hubtel payment on hold restano sempre. Gli ordini esistenti conservano le proprie note di pagamento e gli ID delle transazioni.

Hubtel è un marchio del suo rispettivo proprietario. Questo modulo non è affiliato a Hubtel né approvato da Hubtel.