VibeFox PayFast for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

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

Valuta: rand sudafricano (ZAR). PayFast regola i pagamenti solo in rand, quindi il carrello deve essere in ZAR. Aggiungi la valuta in International > Localization > Currencies se il tuo negozio non la ha ancora. Il totale minimo dell'ordine è di R5,00.

Account PayFast: il Merchant ID e la Merchant Key del tuo account PayFast, da Settings > Developer Settings nella dashboard di PayFast. Una passphrase è fortemente consigliata; se ne è impostata una in PayFast, la stessa passphrase va inserita nel modulo. Per i test ti servono le credenziali del sandbox di PayFast.

Negozio raggiungibile: l'URL di notifica dei pagamenti deve essere raggiungibile da Internet, senza basic auth né blocchi del firewall.

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 più tardi VibeFox PayFast 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 Merchant ID, Merchant Key e passphrase. Per i test lascia attivo Test mode e inserisci le tue credenziali sandbox.

5. Attiva Enable/Disable e fai clic su Save. Effettua un pagamento di prova, poi disattiva Test mode per accettare pagamenti reali.

All'installazione il modulo crea due stati d'ordine: Awaiting PayFast payment e PayFast payment on hold. PrestaShop propone un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences; assicurati che il modulo resti consentito per il rand.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando le credenziali della modalità attuale sono vuote (PayFast viene allora nascosto al checkout), quando la valuta predefinita del negozio non è ZAR, quando la modalità live usa il Merchant ID pubblico del sandbox 10000100 e quando non è impostata alcuna passphrase. Mentre la modalità test è attiva e il modulo abilitato, viene mostrato: La modalità test è attiva: gli ordini vengono pagati nel sandbox PayFast, non viene addebitato denaro reale. Un campo Title vuoto viene rifiutato con Inserisci un titolo per il metodo di pagamento.

PayFast

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

Title: il nome del metodo di pagamento mostrato al cliente al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: PayFast. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

Account PayFast (live)

Trova il tuo Merchant ID e la tua Merchant Key nella dashboard di PayFast, in Settings > Developer Settings. Se hai impostato una passphrase lì, inserisci qui esattamente la stessa.

Merchant ID: il tuo Merchant ID PayFast live.

Merchant Key: la tua Merchant Key PayFast live. Viene inviata a PayFast con ogni modulo di pagamento, quindi è un normale campo di testo.

Passphrase: la passphrase di salt di PayFast, in Settings > Developer Settings. Fortemente consigliata: firma pagamenti e notifiche.

Sandbox (modalità test)

In modalità test i pagamenti vanno al sandbox di PayFast e non viene addebitato denaro reale. Le credenziali del sandbox vengono mostrate dopo l'accesso al sandbox di PayFast (il commerciante di prova pubblico è 10000100 / 46f0cd694581a).

Test mode: Use the PayFast sandbox and the sandbox credentials below. Quando è attivo, il cliente vede sotto il metodo di pagamento: MODALITÀ TEST: i pagamenti vanno al sandbox PayFast, non viene addebitato denaro reale. Predefinito: attivo.

Sandbox Merchant ID: il Merchant ID del tuo account sandbox.

Sandbox Merchant Key: la Merchant Key del tuo account sandbox.

Sandbox Passphrase: solo se nel tuo account sandbox è impostata una passphrase.

Le passphrase salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarla.

Clear saved passphrases: spunta Passphrase o Sandbox Passphrase e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notifiche di pagamento (ITN)

Notification URL: PayFast conferma ogni pagamento con una notifica server-to-server all'URL mostrato qui. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_payfast_pay/itn, eventualmente con il codice della lingua predefinita. L'indirizzo viene inviato con ogni pagamento, quindi in PayFast non va configurato nulla, ma deve essere raggiungibile da Internet. Gli ordini vengono creati solo da queste notifiche verificate; il cliente che torna nel negozio non crea né paga un ordine.

Source check: accetta le notifiche live solo dai server di PayFast. Gli indirizzi provengono dai record DNS di PayFast (in cache per 6 ore) e dagli intervalli di indirizzi documentati da PayFast. Disattivalo solo se il negozio è dietro un proxy o una CDN che nasconde l'indirizzo del visitatore. Firma e conferma server vengono sempre verificate. Le notifiche sandbox non vengono verificate per indirizzo. Predefinito: attivo.

Avanzate

Debug log: registra i passaggi del pagamento in logs/payfast_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche con l'interruttore disattivato. Non vengono scritte passphrase né dati dei clienti. Predefinito: disattivato.

Log: mostra la dimensione e le voci più recenti del log. Fai clic su Clear log per svuotarlo.

Uninstall: Delete the gateway settings when the module is uninstalled (impostazioni, indirizzi PayFast in cache e log). I record dei pagamenti PayFast, gli ordini e gli stati d'ordine vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita PayFast) e conferma. Una pagina con Grazie per il tuo ordine. Stai per essere reindirizzato a PayFast per completare il pagamento. invia automaticamente il modulo di pagamento firmato a PayFast. Se il browser non prosegue da solo, il cliente fa clic su Pay with PayFast; Cancel torna al checkout. Il modulo contiene il totale del carrello in ZAR, Cart # con il numero del carrello, nome e e-mail del cliente, il riferimento del pagamento (numero del carrello e tentativo) e un token casuale del tentativo. A questo punto non esiste ancora alcun ordine. Ogni nuovo tentativo riceve un nuovo riferimento e un nuovo token.

Sulla pagina di PayFast il cliente paga con carta, Instant EFT o un altro metodo del tuo account PayFast. PayFast invia poi la notifica di pagamento (ITN) al tuo negozio. L'ordine viene segnato come pagato solo dopo che PayFast lo ha confermato con una notifica che supera tutti i controlli:

Le notifiche relative allo stesso carrello vengono elaborate una alla volta. Se un'altra notifica dello stesso carrello è in elaborazione, PayFast riceve una risposta di errore e invia di nuovo la notifica. L'URL di notifica funziona anche mentre il negozio è in manutenzione e non viene bloccato dalla restrizione per paese del negozio.

Quando il cliente torna e l'ordine esiste, viene mostrata la normale pagina di conferma dell'ordine. Se PayFast ha segnalato il pagamento come in attesa, compare: PayFast sta confermando il tuo pagamento. Riceverai un'e-mail appena sarà confermato — non c'è bisogno di pagare di nuovo. Se l'ordine è in attesa di verifica, compare: Il tuo pagamento è in fase di verifica. Ti contatteremo se serve altro. Se un pagamento in attesa è fallito in seguito, compare: Il tuo pagamento PayFast non è stato completato. Contattaci per questo ordine. Se la notifica non è ancora arrivata, una pagina Payment confirmation spiega che PayFast sta confermando il pagamento e che l'ordine verrà creato non appena PayFast lo confermerà, con i pulsanti Check again e Back to checkout.

Se il cliente annulla nella pagina di PayFast, torna al checkout con Il pagamento PayFast è stato annullato. Puoi riprovare o scegliere un altro metodo di pagamento. Se PayFast ha segnalato il pagamento come non riuscito, il messaggio è Il pagamento non è stato completato. Puoi riprovare o scegliere un altro metodo di pagamento. Il carrello viene conservato e può essere pagato di nuovo.

Il metodo di pagamento viene nascosto quando mancano le credenziali della modalità attuale, quando la valuta del carrello non è ZAR o non è consentita per il modulo, o quando il totale è inferiore a R5,00. Se il cliente arriva comunque al pagamento, un breve messaggio lo spiega, ad esempio PayFast accetta pagamenti da R5,00. Scegli un altro metodo di pagamento.

Il modulo accetta solo pagamenti unici in ZAR. Non ha rimborsi dalla pagina dell'ordine, né abbonamenti, né carte salvate (tokenizzate), né pagamenti frazionati.

Ordini

Stati d'ordine

No order yet: il cliente è stato inviato a PayFast e la notifica di pagamento non è ancora arrivata, oppure PayFast ha segnalato il pagamento come non riuscito. Esiste solo il carrello.

Payment accepted: PayFast ha confermato il pagamento. Il pagamento viene registrato con l'ID pagamento PayFast come ID transazione, e una nota mostra l'ID pagamento. Un pagamento sandbox riceve la nota che non è stato addebitato denaro reale.

Awaiting PayFast payment: PayFast ha segnalato il pagamento come in attesa. L'ordine passa a Payment accepted quando PayFast lo completa.

Payment error: un pagamento in attesa è fallito. Se PayFast lo completa più tardi, l'ordine diventa Payment accepted.

PayFast payment on hold: l'importo pagato è diverso dal totale del carrello, oppure il carrello non è in ZAR; è arrivato un pagamento per un ordine annullato o il cui metodo di pagamento non è più PayFast; oppure è arrivato un pagamento sandbox mentre il gateway è in modalità live. L'importo ricevuto da PayFast viene registrato nell'ordine (non per un pagamento sandbox), e la nota lo spiega. Controlla l'ordine e la dashboard di PayFast, poi imposta l'ordine su Payment accepted oppure annullalo e rimborsa il pagamento in PayFast.

Una notifica ripetuta per lo stesso pagamento non cambia nulla. Le notifiche tardive di pagamento fallito o in attesa non modificano mai un ordine pagato. Se per un ordine già pagato arriva un altro pagamento completato, una nota ti chiede di rimborsare il duplicato in PayFast. Un pagamento per un ordine rimborsato aggiunge solo una nota.

Blocco pagamento PayFast

La pagina dell'ordine mostra un blocco PayFast payment con il riferimento del pagamento (m_payment_id), l'ID pagamento PayFast, l'ambiente (live o sandbox), lo stato, gli importi lordo, commissione e netto in ZAR e le note del modulo. Per un ordine in attesa di verifica mostra un promemoria per controllare il pagamento.

Rimborsi

I rimborsi dalla pagina dell'ordine non sono supportati. Rimborsa il pagamento nella tua dashboard PayFast, poi aggiorna manualmente l'ordine in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza License — VibeFox PayFast Pay Gateway è il primo blocco di Modules > Module Manager > VibeFox PayFast 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 (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 ci sono la riga Product: presta-payment-payfast 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 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 un cambio dell'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: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il relativo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, PayFast non viene mostrato ai clienti al 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 puoi 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.

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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

PayFast non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che Merchant ID e Merchant Key della modalità attuale siano compilati, che il carrello sia in ZAR e che il totale dell'ordine sia di almeno R5,00. La pagina delle impostazioni mostra un avviso quando manca qualcosa. In Payment > Preferences verifica che il modulo sia consentito per il rand, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma nessun ordine è stato creato: PayFast non è riuscito a consegnare la notifica di pagamento, oppure la notifica è stata rifiutata. Controlla il campo Log nella pagina del modulo; errori e notifiche rifiutate vengono sempre registrati, e Debug log aggiunge ogni passaggio. Cause tipiche: il negozio non è raggiungibile da Internet (basic auth, firewall), una passphrase diversa in PayFast e nel modulo oppure, in modalità live dietro un proxy o una CDN, il controllo della fonte. In quel caso disattiva Source check.

La notifica risponde Invalid signature: la passphrase nel modulo non è quella impostata in PayFast per la modalità in cui è stato effettuato il pagamento.

La notifica risponde Invalid source: la notifica non proviene da un indirizzo PayFast, oppure un proxy o una CDN nasconde l'indirizzo reale. Disattiva Source check se il negozio è dietro un proxy o una CDN.

La notifica risponde Merchant mismatch o Order mismatch: il pagamento è stato effettuato su un altro account PayFast oppure non appartiene a questo tentativo di pagamento. Non viene modificato nulla.

La notifica risponde Order not found: il riferimento del pagamento non è noto a questo negozio. Non viene modificato nulla.

La notifica risponde Confirmation unavailable, Busy o Temporary error: non è stato possibile contattare PayFast per la conferma server, un'altra notifica dello stesso carrello era in elaborazione nello stesso momento, oppure l'ordine non è stato creato (ad esempio perché il modulo è disattivato). PayFast ripete la notifica. Il log indica il motivo.

La notifica risponde Not configured: mancano le credenziali della modalità in cui è stato avviato il pagamento. Inseriscile di nuovo, ad esempio le credenziali sandbox per un pagamento di prova.

Il cliente vede il messaggio PayFast accetta pagamenti solo in rand sudafricani (ZAR): il carrello è in un'altra valuta. Fai pagare il cliente in rand oppure fagli scegliere un altro metodo di pagamento.

L'ordine è in PayFast payment on hold: leggi le note nel blocco PayFast payment (vedi Stati d'ordine) e la dashboard di PayFast, poi accetta l'ordine oppure rimborsa il pagamento.

Un pagamento sandbox non ha pagato l'ordine: il gateway è in modalità live. I pagamenti sandbox non pagano mai un ordine in modalità live; una nota sull'ordine lo segnala.

Per gli sviluppatori: l'hook actionPayfastPPaymentData può modificare i campi del modulo di pagamento prima che vengano firmati. Credenziali del commerciante, URL, riferimento del pagamento, importo e token non possono essere modificati tramite esso.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox PayFast Pay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete the gateway settings when the module is uninstalled è attivo, vengono rimosse le impostazioni del gateway, gli indirizzi PayFast in cache e il log. Se è disattivato, tutte le impostazioni vengono conservate per una reinstallazione successiva. I record dei pagamenti PayFast, gli ordini e gli stati d'ordine Awaiting PayFast payment e PayFast payment on hold vengono sempre conservati. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

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