VibeFox Paystack for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 alla 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Valuta: il carrello deve essere in una valuta che Paystack accetta: NGN, USD, GHS, ZAR, KES, XOF, EGP o RWF, come attivata nel tuo account Paystack. Con 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 servono, perché il pagamento avviene sulla pagina ospitata da Paystack. Nella dashboard di Paystack imposti anche l'URL del webhook del tuo negozio (vedi Configurazione). Il tuo negozio deve essere raggiungibile da Internet per ricevere i webhook.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova più tardi VibeFox Paystack Payment nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Incolla le chiavi segrete dalla dashboard di Paystack e imposta l'URL del webhook nella dashboard di Paystack (vedi Configurazione).

5. Attiva Enable/Disable e clicca su Save. Tieni attivo Test Mode finché non hai effettuato un pagamento di prova, poi disattivalo per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine, Awaiting Paystack payment e Paystack 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 Paystack Payment > Configure. Ogni sezione con campi ha il proprio pulsante Save, che salva l'intera pagina. 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à attuale è vuota, quando in un campo per la chiave segreta è stata inserita una chiave pubblica (pk_...), 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 predefinita del tuo negozio. Finché c'è un problema con le chiavi, il metodo di pagamento è nascosto al checkout.

Paystack

La prima sezione si intitola Paystack e riporta un badge TEST o LIVE della modalità attuale.

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. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Paystack. Obbligatorio.

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 link a quella pagina.

Test Mode: usa la chiave segreta di test per i nuovi pagamenti, e non viene addebitato denaro reale. Disattivalo 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. Finché è attivo, i clienti vedono sotto il metodo di pagamento MODALITÀ TEST ATTIVA. Non verrà effettuato alcun addebito reale.

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_.

Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Salvata — lasciala vuota per mantenerla. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear saved secrets: seleziona una chiave e clicca su Save per eliminarla. Un campo vuoto mantiene il valore salvato.

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 Webhook URL in questa sezione sia come Test Webhook URL sia come Live Webhook URL. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_paystack_payment/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni.

Paystack firma ogni webhook con la tua chiave segreta, quindi non serve configurare altro. I webhook senza una firma valida vengono rifiutati. Il modulo 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 il pagamento. I bonifici bancari e i pagamenti USSD completati più tardi vengono confermati solo dal webhook.

Ordini

Autocomplete Order: se attivo, gli ordini pagati ricevono lo stato Delivered invece di Payment accepted, con un solo cambio di stato. Predefinito: disattivo.

Avanzate

Debug log: registra gli eventi di Paystack e le chiamate API in logs/paystack_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: disattivo.

Log: mostra la dimensione e le ultime voci del log. Clicca su Clear log per svuotarlo.

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni del modulo e il log. I dati di pagamento salvati sugli ordini vengono sempre conservati. Predefinito: disattivo.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Paystack) e conferma l'ordine. Il modulo avvia una transazione Paystack per il totale del carrello nella valuta del carrello, con l'e-mail del cliente, e invia il cliente alla pagina di pagamento ospitata da Paystack. Lì il cliente paga con uno dei canali attivati nel tuo account Paystack. Il pagamento mostra il numero del carrello e il nome del cliente. In questo momento l'ordine non esiste ancora.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Paystack: quando il cliente torna e quando arriva il webhook, il modulo legge la transazione dall'API di Paystack e verifica il riferimento, lo stato, l'importo e la valuta. A quel punto l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine.

Se il pagamento è ancora in elaborazione, per esempio un bonifico bancario, l'ordine viene creato in Awaiting Paystack payment quando il cliente torna, e la pagina di conferma mostra Il tuo pagamento è in fase di conferma da parte di Paystack. Riceverai un'e-mail non appena sarà confermato. Il webhook completa l'ordine più tardi. Se Paystack non è raggiungibile quando il cliente torna, una pagina Payment confirmation chiede al cliente di non pagare di nuovo e propone Check again e Back to checkout; il webhook crea l'ordine appena arriva. Per un ordine in attesa di verifica, la pagina di conferma mostra Il tuo pagamento è stato ricevuto e il tuo ordine è in fase di verifica. Ti contatteremo se serve qualcosa.

Se il cliente annulla nella pagina di Paystack o la abbandona senza pagare, non viene creato alcun ordine e il carrello viene conservato. Il cliente torna al checkout con un messaggio, per 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. Ogni nuovo tentativo avvia una nuova transazione Paystack. Una pagina di pagamento precedente del carrello resta valida: se viene pagata più tardi, il pagamento viene comunque accettato.

La pagina di conferma dell'ordine si apre solo nel browser del cliente. Se il link di ritorno viene aperto altrove, il pagamento viene comunque verificato, ma l'ordine non viene mostrato: il visitatore vede un messaggio neutro al checkout.

Se Paystack non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio Paystack non è riuscito ad avviare il pagamento: seguito dal motivo indicato da Paystack, oppure Paystack non è disponibile al momento. Riprova tra poco o scegli un altro metodo di pagamento. Il totale del carrello deve essere maggiore di zero, e il cliente deve avere un indirizzo e-mail valido.

Il webhook funziona anche mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

In PrestaShop il modulo 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.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Paystack e non ha pagato, ha lasciato la pagina di Paystack, oppure Paystack non ha ancora confermato il pagamento. Esiste solo il carrello.

Awaiting Paystack payment: il cliente è tornato mentre Paystack stava ancora elaborando il pagamento, per esempio un bonifico bancario o USSD. L'ordine passa allo stato pagato quando Paystack conferma il pagamento. Se quel pagamento non viene mai completato, l'ordine resta in questo stato finché non lo cambi.

Payment accepted o Delivered: il pagamento è stato confermato. Lo stato è Consegnato quando Autocomplete Order è attivo. Il pagamento viene registrato con il riferimento Paystack (pscart_...) come ID transazione. Una nota mostra l'importo, il riferimento, 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, se presenti.

Paystack payment on hold: l'importo o la valuta pagati non corrispondono all'ordine (nota Discrepanza di importo o valuta Paystack), per esempio perché il carrello è stato modificato dopo l'avvio del pagamento, o perché il pagamento è arrivato dopo l'annullamento dell'ordine. La nota spiega cosa controllare. Evadi l'ordine oppure rimborsa il pagamento.

Errore di pagamento: Paystack segnala che l'ultimo tentativo di pagamento di un ordine in Awaiting Paystack payment è fallito o è stato stornato. Il fallimento di un tentativo precedente non modifica l'ordine.

Se arriva un secondo pagamento per un carrello il cui ordine è già pagato, 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, per esempio Spedito, viene solo annotato sull'ordine.

Blocco Paystack payment

La pagina dell'ordine mostra un blocco Paystack payment con il riferimento, l'ID transazione, la modalità con un badge Test mode per i pagamenti di prova, lo stato del pagamento, il canale e la carta, la data del pagamento, gli importi pagati e rimborsati, lo storico dei rimborsi e le Payment notes dell'ordine.

Rimborsi

Nel blocco Paystack payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Paystack. Conferma la domanda Rimborsare questo importo tramite Paystack? Questa operazione non può essere annullata. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei moduli. 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 configurata. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Paystack: per un ordine in attesa dopo una discrepanza di importo o valuta puoi quindi rimborsare fino a quanto il cliente ha effettivamente pagato, non il totale dell'ordine. In XOF e RWF i rimborsi devono essere importi interi. Paystack accoda i rimborsi: la nota e lo storico dei rimborsi mostrano lo stato restituito da Paystack, per esempio pending, e l'ID del rimborso. Se Paystack non accetta il rimborso, il blocco mostra Rimborso Paystack non riuscito: con il motivo, e nessun rimborso viene registrato. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili una volta che Paystack ha confermato il pagamento.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Paystack.

I rimborsi effettuati nella dashboard di Paystack e lo stato finale dei rimborsi accodati da Paystack non vengono sincronizzati con PrestaShop. Se necessario, registrali manualmente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Paystack Payment è il primo blocco di Modules > Module Manager > VibeFox Paystack Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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 di essi ci sono la riga Product: presta-payment-paystack 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, clicca 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: il dominio 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, 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. Il negozio 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 testarlo 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 e i rimborsi funzionano.

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 alla 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

Paystack non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità attuale 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 del carrello sia accettata da Paystack. Il riquadro di stato in cima alle impostazioni indica il problema. 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: 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 in Webhook URL, e che nessun firewall o protezione con password lo blocchi. Attiva Debug log e controlla il campo Log per i webhook rifiutati.

Il webhook risponde Invalid signature: il webhook non è stato firmato con la chiave segreta di test o live inserita nelle impostazioni, per 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: non è impostata nessuna chiave segreta. Inserisci le chiavi segrete nelle impostazioni.

Il webhook risponde Verification failed, Busy, retry later oppure Order could not be created, retry later: in quel momento non è stato possibile leggere la transazione dall'API di Paystack, il carrello era in elaborazione contemporaneamente per il ritorno del cliente, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Paystack invia di nuovo il webhook. Il log mostra il motivo.

Il webhook risponde OK - unknown reference: il pagamento non è stato effettuato per un carrello di questo negozio, per esempio una pagina di pagamento Paystack o un'altra integrazione sullo stesso account. Viene ignorato.

L'URL del webhook mostra Empty body nel browser: è normale. L'URL accetta solo richieste da Paystack.

Il cliente vede il messaggio «Il gateway di pagamento non è configurato correttamente»: la chiave segreta della modalità attuale manca o è errata. Correggila seguendo il riquadro di stato in cima alle impostazioni.

L'ordine è in Paystack payment on hold dopo il pagamento: leggi le note di pagamento nel blocco Paystack payment (vedi Stati dell'ordine), poi evadi l'ordine oppure rimborsa il pagamento.

L'ordine resta in Awaiting Paystack payment: Paystack non ha ancora confermato il pagamento. Controlla la transazione nella dashboard di Paystack e le impostazioni del webhook. Se il cliente non ha mai completato il pagamento, cambia lo stato manualmente.

Il rimborso non riesce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e la chiave segreta di quella modalità non è configurata. Inseriscila e riprova.

Gli sviluppatori possono modificare la richiesta di transazione e l'elenco delle valute con gli hook del modulo actionWcpPaystackPaymentRequest, actionWcpPaystackSupportedCurrencies e actionWcpPaystackCurrencyDecimals.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Paystack Payment 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 modulo e il log. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I dati di pagamento Paystack degli ordini, i rimborsi e gli stati dell'ordine Awaiting Paystack payment e Paystack payment on hold vengono sempre conservati, così che gli ordini pagati in precedenza possano essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID delle transazioni.

Paystack è un marchio registrato del suo titolare. Questo modulo non è affiliato a Paystack né approvato da Paystack.