VibeFox Paystack for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

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

PHP: 8.0 o successivo.

Valuta: l'ordine deve essere in una valuta accettata da Paystack: NGN, USD, GHS, ZAR, KES, XOF, EGP o RWF, come attivato nel tuo account Paystack. Nelle altre valute il metodo di pagamento viene nascosto. In XOF e RWF Paystack accetta solo importi interi.

Account Paystack: ti servono le chiavi segrete del tuo account Paystack: la chiave segreta di test (sk_test_...) e/o la chiave segreta live (sk_live_...). Le chiavi pubbliche (pk_...) non sono necessarie, perché il pagamento avviene nella pagina ospitata da Paystack. Nella dashboard di Paystack imposti anche l'URL del webhook del tuo negozio (vedi Configurazione). Il tuo sito deve essere raggiungibile da internet per ricevere i webhook.

Chiave di licenza VibeFox: 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. In alternativa puoi caricare la cartella wcp_paystack_payment in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Paystack > 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 segrete dalla dashboard di Paystack e imposta l'URL del webhook nella dashboard di Paystack (vedi Configurazione).

6. Attiva Enable/Disable e salva. Tieni Test Mode attivo finché non hai effettuato un pagamento di prova, poi deselezionalo per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Paystack. Sopra i campi un riquadro di stato mostra la modalità: Modalità test: non viene addebitato denaro reale. oppure Modalità live: vengono accettati pagamenti reali. Avvisa anche quando la chiave segreta della modalità corrente è vuota, quando una chiave pubblica (pk_...) è stata inserita in un campo per la chiave segreta, quando la modalità live ha una chiave di test (sk_test_...) o la modalità test ha una chiave live (sk_live_...), e quando Paystack non accetta la valuta del tuo negozio. Finché esiste un problema con le chiavi, il metodo di pagamento viene nascosto al checkout. Nell'elenco dei metodi di pagamento, Paystack è segnalato come da configurare finché la modalità corrente non ha una chiave segreta.

Checkout

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Paystack.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely using your debit card, credit card, or bank account via Paystack.

Chiavi API

Copia le chiavi segrete dalla dashboard di Paystack, pagina Settings > API Keys & Webhooks. La sezione contiene un collegamento a quella pagina.

Test Mode: Enable Test Mode usa la chiave segreta di test per i nuovi pagamenti, e non viene addebitato denaro reale. Deselezionalo per accettare pagamenti reali con la chiave segreta live. I pagamenti effettuati nell'altra modalità continuano a usare la chiave della propria modalità per la verifica e i rimborsi. Predefinito: attivo.

Test Secret Key: la tua chiave segreta di test di Paystack. Inizia con sk_test_.

Live Secret Key: la tua chiave segreta live di Paystack. Inizia con sk_live_.

Webhook

Il webhook comunica al tuo negozio che un pagamento è stato effettuato, anche quando il cliente non torna nel negozio. Nella dashboard di Paystack, pagina Settings > API Keys & Webhooks, imposta l'URL mostrato in questa sezione sia come Test Webhook URL sia come Live Webhook URL. Ha questo aspetto: https://your-site/wc-api/paystack_p_webhook/. Copia l'URL esattamente come lo mostrano le impostazioni.

Paystack firma ogni webhook con la tua chiave segreta, quindi non c'è altro da configurare. I webhook di test vengono verificati con la chiave segreta di test, quelli live con la chiave segreta live. I webhook senza una firma valida vengono rifiutati. Il plugin usa l'evento charge.success:

Gli altri eventi ricevono la risposta OK e vengono ignorati. Senza il webhook, un ordine viene confermato solo quando il cliente torna nel negozio dopo aver pagato. I bonifici bancari e i pagamenti USSD completati più tardi vengono confermati solo dal webhook.

Ordini

Autocomplete Order: Automatically mark orders as completed after successful payment. Se selezionato, gli ordini pagati diventano Completato invece di Processing, con un solo cambio di stato e un'unica e-mail al cliente. Predefinito: disattivato.

Avanzate

Debug log: Log Paystack events and API calls for debugging scrive i dettagli in WooCommerce > Status > Logs, origine wcp_paystack_payment. Gli errori vengono sempre registrati. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. La disattivazione del plugin non cancella mai nulla. I dati di pagamento salvati negli ordini vengono sempre conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Paystack) e invia l'ordine. In modalità test il checkout mostra MODALITÀ TEST ATTIVA. Non verrà effettuato alcun addebito reale. Il plugin avvia una transazione Paystack per il totale dell'ordine nella valuta dell'ordine, con l'e-mail di fatturazione dell'ordine, e invia il cliente alla pagina di checkout ospitata da Paystack. Lì il cliente paga con uno dei canali attivati nel tuo account Paystack.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene contrassegnato come pagato solo dopo che Paystack lo conferma: quando il cliente torna e quando arriva il webhook, il plugin legge la transazione dall'API di Paystack con la chiave segreta della modalità in cui il pagamento è stato avviato, e verifica il riferimento, lo stato, l'importo e la valuta. Se il pagamento è ancora in elaborazione, ad esempio un bonifico bancario, la pagina di ordine ricevuto mostra Il tuo pagamento è in fase di conferma da parte di Paystack. Riceverai un'e-mail non appena sarà confermato. Il webhook completerà l'ordine più tardi.

Se il cliente annulla nella pagina di Paystack o la abbandona senza pagare, l'ordine resta in attesa di pagamento. Il cliente torna al checkout o alla pagina Pay for order con un messaggio, ad esempio Il pagamento è stato annullato. Puoi riprovare o scegliere un altro metodo di pagamento., Il pagamento non è stato completato. Puoi riprovare o scegliere un altro metodo di pagamento. oppure Il tuo pagamento è stato rifiutato. Puoi riprovare o scegliere un altro metodo di pagamento. Il cliente può pagare di nuovo lo stesso ordine. Una pagina di pagamento precedente dell'ordine resta valida: se viene pagata più tardi, il pagamento viene comunque accettato.

La pagina di ordine ricevuto si apre solo per il cliente dell'ordine: tramite il link di ritorno firmato, la sessione di checkout che ha creato l'ordine o l'account del cliente. Chiunque altro viene inviato al checkout con un messaggio neutro, e la pagina dell'ordine non viene mostrata.

Se Paystack non riesce ad avviare il pagamento, il cliente vede un breve messaggio, ad esempio Paystack non è riuscito ad avviare il pagamento: seguito dal motivo indicato da Paystack, oppure Paystack è temporaneamente non disponibile. Riprova tra poco o scegli un altro metodo di pagamento. Il totale dell'ordine deve essere maggiore di zero, e l'ordine deve avere un indirizzo e-mail valido.

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

Il plugin non ha un modulo di pagamento integrato o a comparsa, né carte salvate, abbonamenti, pagamenti divisi o subaccount, né la scelta dei canali di pagamento in WooCommerce.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Paystack e non ha ancora pagato, ha lasciato la pagina di Paystack senza pagare, oppure il pagamento è ancora in elaborazione da parte di Paystack. Quando il cliente torna senza aver pagato, una nota indica che l'ordine è ancora in attesa di pagamento.

Processing or Completed: il pagamento è stato confermato. Lo stato è Completato quando Autocomplete Order è attivo. La nota dell'ordine mostra l'importo, il riferimento Paystack, il numero della transazione, la modalità (test o live), il canale di pagamento, il tipo di carta e le ultime cifre per i pagamenti con carta, oltre alle commissioni Paystack pagate dal cliente. L'ID transazione dell'ordine è il riferimento Paystack (order_...).

On hold: l'importo o la valuta pagati differiscono dall'ordine (nota Paystack amount or currency mismatch), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota dell'ordine spiega cosa controllare. Evadi l'ordine o rimborsa il pagamento.

Failed: Paystack segnala che l'ultimo tentativo di pagamento di un ordine in attesa è fallito o è stato stornato. Il fallimento di un tentativo precedente non cambia l'ordine. Il cliente può pagare di nuovo.

Se un secondo tentativo di pagamento per un ordine già pagato va a buon fine, l'ordine non viene modificato. Una nota ti chiede di rimborsare il pagamento duplicato nella dashboard di Paystack. Un pagamento che arriva per un ordine in un altro stato, ad esempio Refunded, viene solo annotato sull'ordine.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Paystack. Sono supportati rimborsi totali e parziali. Il pulsante di rimborso viene offerto solo per gli ordini pagati tramite una transazione Paystack verificata. Il rimborso va alla transazione che ha pagato l'ordine, con la chiave segreta della modalità (test o live) in cui è stata effettuata, quindi quella chiave deve essere impostata. In XOF e RWF i rimborsi devono essere importi interi. Paystack mette in coda i rimborsi: la nota dell'ordine mostra lo stato restituito da Paystack, ad esempio pending, e l'ID del rimborso. Se Paystack non accetta il rimborso, WooCommerce mostra Paystack refund failed: con il motivo, e nessun rimborso viene registrato.

I rimborsi effettuati nella dashboard di Paystack e lo stato finale dei rimborsi messi in coda da Paystack non vengono sincronizzati con WooCommerce. Se necessario, registrali manualmente.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Paystack. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad 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 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 suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Paystack 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. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati, e i rimborsi funzionano.

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

Risoluzione dei problemi

Paystack non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia una chiave segreta corretta (Test Secret Key con sk_test_... in modalità test, Live Secret Key con sk_live_... in modalità live) e che la valuta dell'ordine sia accettata da Paystack. Il riquadro di stato in cima alle impostazioni indica il problema.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: il webhook non è arrivato al tuo negozio e il cliente non è tornato. Nella dashboard di Paystack verifica che la Test Webhook URL e la Live Webhook URL corrispondano esattamente all'URL mostrato nelle impostazioni, e che nessuna modalità manutenzione, firewall o protezione con password lo blocchi. Controlla WooCommerce > Status > Logs, origine wcp_paystack_payment, per i webhook rifiutati.

Il webhook risponde Invalid signature: il webhook non è firmato con la chiave segreta di test o live inserita nelle impostazioni, ad esempio perché le chiavi appartengono a un altro account Paystack. Inserisci le chiavi dell'account che invia il webhook.

Il webhook risponde Secret key not configured: nessuna chiave segreta è impostata. Inserisci le chiavi segrete nelle impostazioni.

Il webhook risponde Verification failed o Busy, retry later: in quel momento la transazione non è stata letta dall'API di Paystack, oppure l'ordine era in aggiornamento per il ritorno del cliente. L'ordine non viene modificato e Paystack invia di nuovo il webhook.

Il webhook risponde OK - unknown reference: il pagamento non riguardava un ordine di questo negozio, ad esempio una pagina di pagamento Paystack o un'altra integrazione sullo stesso account. Viene ignorato.

Il cliente vede Payment gateway is not properly configured: la chiave segreta della modalità corrente manca o è errata. Correggila seguendo il riquadro di stato in cima alle impostazioni.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati differivano dall'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. Evadi l'ordine o rimborsa il pagamento.

Il rimborso fallisce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e la chiave segreta di quella modalità non è impostata. Inseriscila e riprova. Il messaggio No verified Paystack payment was found for this order significa che l'ordine non è stato pagato tramite una transazione Paystack verificata. Rimborsalo nella dashboard di Paystack.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad 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 sul nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

La disattivazione del plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le note di pagamento, gli ID transazione e i riferimenti Paystack.

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