VibeFox IntaSend for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

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

PHP: 8.0 o successivo.

HTTPS: IntaSend richiede HTTPS per i pagamenti live e i webhook. La pagina delle impostazioni ti avvisa quando la modalità live è attiva e l'indirizzo del negozio non è 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 una frase di verifica nella dashboard 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. 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_intasend_pay in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

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

6. Attiva Enable/Disable. Prova un pagamento con Test mode attivo, poi disattiva Test mode per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > IntaSend. 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 non sono corrette (il metodo di pagamento viene nascosto al checkout), quando la valuta del negozio non è supportata, quando non è impostata una frase di verifica del webhook e quando la modalità live è usata senza HTTPS. Nell'elenco dei metodi di pagamento IntaSend è indicato come "da configurare" finché le chiavi della modalità attuale non sono corrette. Le chiavi incollate vengono ripulite dagli spazi al salvataggio.

Generali

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: IntaSend (M-Pesa, card).

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 IntaSend, in Settings > API Keys, separatamente nella dashboard sandbox e in quella live. La modalità di test usa le chiavi sandbox e l'API sandbox, la modalità live usa le chiavi live e l'API live. Il plugin 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, quelle live contengono _live. In caso contrario il metodo di pagamento viene nascosto e il riquadro di stato ne spiega il motivo.

Test mode: Use the IntaSend sandbox (no real money is charged). Predefinito: attivo. Disattivalo per accettare pagamenti reali con le chiavi live. Finché la modalità di 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.

Webhook

Il webhook comunica al tuo negozio che un pagamento è stato effettuato, anche quando il cliente non torna nel negozio (browser chiuso, M-Pesa confermato più tardi). Nella dashboard IntaSend, sia in sandbox sia in live, apri Webhooks e aggiungi l'URL mostrato in questa sezione delle impostazioni. Ha questo aspetto: https://your-site/wc-api/intasend_pay/. Inserisci lì una frase di verifica e la stessa frase nel plugin. Usa una sola frase per la sandbox e per la live.

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

Il plugin reagisce agli stati di pagamento riportati da IntaSend. Ogni volta interroga la Payment Status API per conoscere lo stato reale prima di modificare l'ordine:

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 OK e vengono ignorate, così IntaSend non disattiva il webhook.

Avanzate

Debug log: Log checkout, return and webhook events in WooCommerce > Status > Logs, origine wcp_intasend_pay. Gli errori vengono sempre registrati. Chiavi API e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. I riferimenti IntaSend salvati sugli ordini fanno parte dello storico dei pagamenti e vengono sempre conservati. Disattivare il plugin non elimina nulla. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita IntaSend (M-Pesa, card)) e invia l'ordine. Il plugin crea un checkout IntaSend per il totale dell'ordine nella valuta dell'ordine 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 di fatturazione, il nome, l'indirizzo, il telefono e il paese vengono passati a IntaSend quando rispettano le regole dei suoi campi. I campi vuoti o non idonei vengono omessi.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando IntaSend lo conferma: il plugin interroga la Payment Status API quando il cliente torna e quando arriva il webhook. Se il pagamento non è ancora confermato, la pagina di ricezione dell'ordine 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. Se l'ordine è stato messo in sospeso, mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed.

Se il pagamento non è riuscito o il cliente è tornato senza pagare, torna al checkout (o alla pagina Pay for order) con il messaggio The payment was not successful. Please try again or choose another payment method. (con il motivo di IntaSend, se presente) oppure The payment was not completed. Please try again or choose another payment method. Il cliente può pagare di nuovo l'ordine. Ogni tentativo riceve un proprio riferimento IntaSend.

Se IntaSend non riesce ad avviare il pagamento, il cliente vede IntaSend could not start the payment: con il motivo fornito da IntaSend, oppure IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. I dettagli vengono scritti nel registro.

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

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

Ordini

Stati dell'ordine

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

Processing or Completed: il pagamento è stato confermato. WooCommerce imposta lo stato usuale per un ordine pagato. La nota dell'ordine mostra la fattura IntaSend, il metodo di pagamento presso IntaSend, l'importo, la modalità (sandbox o live) e come è stato confermato (webhook o ritorno del cliente). L'ID transazione è l'ID della fattura IntaSend.

On hold: IntaSend ha riportato un importo o una valuta diversi dal totale dell'ordine, un pagamento parziale oppure un pagamento arrivato dopo l'annullamento dell'ordine. La nota dell'ordine lo spiega. Verifica il pagamento nella dashboard IntaSend e completa l'ordine oppure rimborsa il pagamento.

Failed: l'ultimo tentativo di pagamento non è riuscito. La nota mostra il motivo fornito da IntaSend. Il cliente può riprovare.

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

Rimborsi

I rimborsi non vengono inviati a IntaSend da WooCommerce. Rimborsa il pagamento nella dashboard IntaSend e registra il rimborso manualmente in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > IntaSend. 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 controllare di nuovo 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 vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera lo slot del 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. I gestori del negozio che hanno effettuato l'accesso 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. Nella pagina Plugins e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

IntaSend non compare 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à di test, chiavi live (con _live) in modalità live. La valuta del negozio deve essere supportata. Il riquadro di stato in cima alla pagina delle impostazioni mostra cosa non va.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: le conferme di M-Pesa possono richiedere un momento. Il webhook conferma l'ordine quando IntaSend riporta lo stato finale. Verifica che l'URL del webhook nella dashboard IntaSend (sandbox o live, la modalità che usi) sia esattamente quello mostrato nelle impostazioni e che la frase di verifica lì sia uguale a Webhook challenge.

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

Il webhook risponde Invalid challenge: la frase di verifica in IntaSend e nel plugin non coincide.

Il webhook risponde Verification unavailable, retry later oppure Busy, retry later: in quel momento IntaSend non era raggiungibile, oppure l'ordine era in fase di conferma da un'altra richiesta. IntaSend riprova il webhook.

Il webhook risponde Invoice not verified oppure Invoice does not match the reference: IntaSend non ha confermato che questa fattura appartiene all'ordine. L'ordine non viene modificato.

L'ordine è On hold: leggi la nota dell'ordine. L'importo o la valuta pagati non corrispondevano all'ordine, il pagamento era parziale o è arrivato dopo l'annullamento dell'ordine. Verifica il pagamento nella dashboard IntaSend.

Il cliente vede un errore quando invia l'ordine: attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_intasend_pay. Il totale dell'ordine deve essere maggiore di zero. Se il registro dice che l'URL di ritorno contiene caratteri che IntaSend non accetta, la causa è l'indirizzo del negozio o un parametro di lingua al suo interno.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot 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 mantiene tutti i dati. 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 e i registri vengono rimossi solo se era attiva l'opzione Delete data on uninstall. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.

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