VibeFox IntaSend 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 su versioni precedenti di PHP o senza cURL.

HTTPS: IntaSend richiede HTTPS per i pagamenti live e per i webhook. La pagina delle impostazioni ti avvisa quando la modalità live è attiva e il negozio non usa HTTPS.

Account IntaSend: ti servono la chiave pubblica (ISPubKey_...) e la chiave segreta (ISSecretKey_...) del tuo account IntaSend, per la sandbox, per la modalità live o per entrambe, e un webhook con frase di verifica nella dashboard di IntaSend (vedi Configurazione). La chiave pubblica crea il checkout. La chiave segreta viene usata solo sul tuo server per chiedere a IntaSend lo stato del pagamento.

Valuta del negozio: KES, USD, EUR, GBP, UGX, TZS, NGN, GHS, XAF o XOF. Per le altre valute il metodo di pagamento viene nascosto.

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 fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova VibeFox IntaSend Pay Gateway più tardi nell'elenco dei moduli e fai clic su Configure.

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

4. Incolla le chiavi IntaSend di sandbox e/o live, aggiungi il webhook nella dashboard di IntaSend e inserisci la stessa frase di verifica nel modulo (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Prova un pagamento con Test mode attivo, poi disattiva Test mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine IntaSend 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 IntaSend Pay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, un riquadro di stato mostra Test mode: IntaSend sandbox, no real money is charged. oppure Live mode: real payments are accepted. Avvisa anche quando le chiavi della modalità attuale mancano o sono errate (il metodo di pagamento viene allora nascosto al checkout), quando la valuta predefinita del negozio non è supportata, quando non è impostata una frase di verifica del webhook e quando la modalità live è usata senza HTTPS. Le chiavi incollate vengono ripulite dagli spazi al salvataggio.

IntaSend

Enable/Disable: Enable IntaSend 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: IntaSend (M-Pesa, card). Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

Chiavi API

Le chiavi si trovano nella dashboard di IntaSend, in Settings > API Keys, separatamente nella dashboard sandbox e in quella live (la sezione contiene i link a entrambe). La modalità test usa le chiavi sandbox e l'API sandbox, la modalità live usa le chiavi live e l'API live. Il modulo verifica che la chiave pubblica inizi con ISPubKey_, che la chiave segreta inizi con ISSecretKey_, e che le chiavi appartengano alla modalità attuale: le chiavi sandbox contengono _test, le chiavi live contengono _live. In caso contrario il metodo di pagamento viene nascosto e il riquadro di stato spiega il motivo.

Test mode: usa la sandbox di IntaSend, non viene addebitato denaro reale. Predefinito: attivo. Disattivalo per accettare pagamenti reali con le chiavi live. Finché la modalità test è attiva, il checkout mostra TEST MODE - IntaSend sandbox, no real money is charged. sotto il metodo di pagamento.

Sandbox publishable key: inizia con ISPubKey_test. Identifica la tua attività quando viene creato un checkout.

Sandbox secret key: inizia con ISSecretKey_test. Usata solo sul tuo server per confermare i pagamenti con la Payment Status API.

Live publishable key: inizia con ISPubKey_live.

Live secret key: inizia con ISSecretKey_live. Usata solo sul tuo server per confermare i pagamenti.

Le chiavi segrete salvate e la frase di verifica del webhook non vengono più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Webhook

Il webhook comunica al tuo negozio che un pagamento è stato effettuato, anche quando il cliente non torna al negozio (browser chiuso, M-Pesa confermato più tardi). Nella dashboard di IntaSend, sia in sandbox sia in live, apri Webhooks e aggiungi l'URL mostrato in Webhook URL in questa sezione. Con gli URL semplificati ha l'aspetto di https://your-shop/module/wcp_intasend_pay/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni. Inserisci lì una frase di verifica e la stessa frase nel modulo. Usa una sola frase di verifica per sandbox e live.

Webhook challenge: la stessa frase di verifica della dashboard di IntaSend. I webhook con un'altra frase vengono rifiutati. Finché questo campo è vuoto, i webhook non vengono elaborati e i pagamenti vengono confermati solo quando il cliente torna al negozio. Questi webhook ricevono la risposta Ignored, non un errore, così IntaSend non disattiva il webhook prima che tu inserisca la frase.

Cancella i segreti salvati: seleziona Sandbox secret key, Live secret key o Webhook challenge e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Il modulo reagisce a questi stati di pagamento comunicati da IntaSend. Ogni volta chiede alla Payment Status API lo stato reale prima di cambiare qualsiasi cosa:

Le notifiche che non sono pagamenti di checkout di questo negozio, per esempio link di pagamento o eventi di invio denaro dello stesso account IntaSend, ricevono la risposta Ignored, così IntaSend non disattiva il webhook.

Avanzate

Debug log: registra gli eventi di checkout, ritorno e webhook in logs/intasend_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Chiavi API 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 on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. I riferimenti IntaSend salvati per gli ordini sono lo storico dei pagamenti e vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita IntaSend (M-Pesa, card)) e conferma. Il modulo crea un checkout IntaSend per il totale del carrello nella valuta del carrello e invia il cliente al checkout ospitato da IntaSend. Lì il cliente paga con M-Pesa, carta o un altro metodo attivo sul tuo account IntaSend. L'e-mail del cliente, insieme a nome, indirizzo, telefono e paese dell'indirizzo di fatturazione, viene passata a IntaSend quando rispetta le regole dei campi di IntaSend. I campi vuoti o non idonei vengono omessi. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo quando IntaSend lo conferma: il modulo interroga la Payment Status API quando il cliente torna e quando arriva il webhook. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine. Se l'ordine è stato messo in sospeso, la pagina mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed. Se il pagamento non è ancora confermato, o IntaSend non è raggiungibile in quel momento, una pagina Payment confirmation mostra Your payment is being confirmed by IntaSend (M-Pesa confirmations can take a minute). You will receive an e-mail as soon as it is confirmed. con i pulsanti Check again e Back to checkout. Il webhook crea l'ordine non appena IntaSend conferma il pagamento.

Se il pagamento non è riuscito, il cliente torna al checkout con il messaggio The payment was not successful. Please try again or choose another payment method. (con il motivo fornito da IntaSend, se presente). Se il cliente è tornato senza pagare, il messaggio è The payment was not completed. Please try again or choose another payment method. Il carrello viene conservato e il cliente può pagare di nuovo. Ogni tentativo riceve un proprio riferimento IntaSend.

Se IntaSend non riesce ad avviare il pagamento, il cliente resta al checkout con IntaSend could not start the payment: e il motivo fornito da IntaSend, oppure con IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. I dettagli vengono scritti nel registro. Un carrello con totale zero non può essere pagato con IntaSend.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del negozio. Quando gli URL semplificati sono disattivati, il cliente torna tramite la home page del negozio, perché IntaSend non accetta alcuni caratteri nell'indirizzo di ritorno.

Il modulo accetta solo pagamenti singoli. I rimborsi non vengono inviati a IntaSend dal negozio, e il modulo non prevede carte salvate, abbonamenti né un modulo di pagamento integrato (popup). I vecchi link di checkout dello stesso carrello non possono essere annullati presso IntaSend.

Ordini

Stati dell'ordine

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

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID della fattura IntaSend come ID transazione, e una nota mostra la fattura, il metodo di pagamento in IntaSend, l'importo, la modalità (sandbox o live) e come è stato confermato (webhook o ritorno del cliente).

IntaSend payment on hold: IntaSend ha riportato un importo o una valuta diversi dal totale del carrello, un pagamento parziale oppure un pagamento arrivato dopo l'annullamento dell'ordine. La nota lo spiega, e l'importo prelevato da IntaSend viene registrato come pagamento quando è nella valuta dell'ordine. Controlla il pagamento nella dashboard di IntaSend e evadi l'ordine oppure rimborsa il pagamento. Se in seguito arriva il pagamento corretto, l'ordine passa a Payment accepted.

Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsarlo nella dashboard di IntaSend se si tratta di un duplicato. Un pagamento per un ordine rimborsato aggiunge una nota e non riapre l'ordine.

Blocco pagamento IntaSend

La pagina dell'ordine mostra un blocco IntaSend payment con ogni tentativo di checkout del carrello dell'ordine (data, riferimento, checkout IntaSend, ambiente, importo, fattura e risultato, con il motivo dell'errore) e le Invoices processed (fattura, stato in IntaSend, importo e risultato). Il blocco è di sola lettura.

Rimborsi

I rimborsi non vengono inviati a IntaSend dal negozio. Rimborsa il pagamento nella dashboard di IntaSend e registra il rimborso manualmente in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox IntaSend Pay Gateway è il primo blocco di Modules > Module Manager > VibeFox IntaSend Pay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo di che 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-intasend 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 cambiare 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 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 solo dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, IntaSend 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. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non 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.

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. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

IntaSend non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che le chiavi della modalità attuale siano compilate e appartengano a quella modalità: chiavi sandbox (con _test) in modalità test, chiavi live (con _live) in modalità live. La valuta del carrello deve essere supportata. Il riquadro di stato in alto nella pagina delle impostazioni mostra cosa non va. 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: le conferme di M-Pesa possono richiedere un momento. Il webhook crea l'ordine quando IntaSend comunica lo stato finale. Verifica che l'URL del webhook nella dashboard di IntaSend (sandbox o live, la modalità che usi) sia esattamente quello mostrato in Webhook URL e che la frase di verifica lì indicata sia la stessa di Webhook challenge. L'ordine viene creato anche quando il cliente torna al negozio o fa clic su Check again.

Il webhook risponde Ignored: webhook challenge not configured: Webhook challenge è vuoto. Inserisci la frase di verifica dalla dashboard di IntaSend.

Il webhook risponde Invalid challenge: la frase di verifica in IntaSend e nel modulo non coincide, oppure il webhook non ha una frase di verifica.

Il webhook risponde Verification unavailable, retry later oppure Busy, retry later: IntaSend non era raggiungibile in quel momento, il carrello era in conferma da un'altra richiesta, oppure l'ordine non ha potuto essere creato (per esempio perché il modulo è disattivato). IntaSend riprova il webhook. Il motivo è nel registro.

Il webhook risponde Invoice not verified oppure Invoice does not match the reference: IntaSend non ha confermato che questa fattura appartiene al carrello. Non cambia nulla.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste provenienti da IntaSend.

L'ordine è in IntaSend payment on hold: leggi le note dell'ordine. L'importo o la valuta pagati erano diversi dal carrello, il pagamento era parziale, oppure è arrivato dopo l'annullamento dell'ordine. Controlla il pagamento nella dashboard di IntaSend.

Il cliente vede un errore quando sceglie IntaSend: controlla il campo Log nella pagina del modulo (attiva Debug log per più dettagli). Se le chiavi della modalità attuale sono errate, il cliente vede IntaSend is not available at the moment. Please choose another payment method or contact the store. Se il registro dice che l'URL di ritorno contiene caratteri che IntaSend non accetta, la causa è l'indirizzo del negozio.

Il cliente vede We could not match this payment to an order: il link di ritorno è stato modificato o appartiene a un altro carrello. Se il cliente ha pagato, il webhook crea comunque l'ordine.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox IntaSend 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 del gateway e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I tentativi di checkout e le fatture IntaSend degli ordini e lo stato ordine IntaSend payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID transazione.

IntaSend è un marchio del rispettivo proprietario. Questo modulo non è affiliato né approvato da IntaSend.