VibeFox PayFast for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

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

PHP: 8.0 o successivo.

Valuta: rand sudafricano (ZAR), da impostare in WooCommerce > Settings > General. PayFast regola solo in rand. L'importo minimo dell'ordine è 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 è impostata in PayFast, la stessa passphrase deve essere inserita nel plugin. Per i test ti servono le credenziali della sandbox di PayFast.

Sito raggiungibile: l'URL di notifica dei pagamenti deve essere raggiungibile da Internet, senza modalità manutenzione, autenticazione di base o blocchi del firewall.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona per 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. Puoi anche caricare la cartella wcp_payfast_pay in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Imposta la valuta del negozio su rand sudafricano in WooCommerce > Settings > General.

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

5. Inserisci la tua chiave di licenza VibeFox nel blocco di licenza in alto nella pagina e fai clic su Activate.

6. Inserisci il Merchant ID, la Merchant Key e la passphrase. Per i test, lascia attivo Test mode e inserisci le tue credenziali sandbox.

7. Attiva Enable/Disable e salva. Esegui un pagamento di prova, poi disattiva la modalità di test per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > PayFast. Sopra i campi la pagina ti avvisa quando le credenziali della modalità attuale sono vuote (PayFast viene quindi nascosto al checkout), quando la valuta del negozio non è ZAR, quando la modalità live usa il Merchant ID sandbox pubblico 10000100 e quando non è impostata alcuna passphrase; mostra inoltre Test mode is on: orders are paid in the PayFast sandbox, no real money is charged. mentre la modalità di test è attiva. Nell'elenco dei metodi di pagamento PayFast risulta da configurare finché non vengono inseriti Merchant ID e Merchant Key della modalità attuale.

Generale

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. Predefinito: PayFast.

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)

Trovi il tuo Merchant ID e la tua Merchant Key nella dashboard di PayFast, in Settings > Developer Settings. Se vi hai impostato una passphrase, inseriscila qui esattamente uguale.

Merchant ID: il tuo Merchant ID live di PayFast.

Merchant Key: la tua Merchant Key live di PayFast. Viene inviata a PayFast con ogni modulo di pagamento.

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

Sandbox (modalità di prova)

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

Test mode: Use the PayFast sandbox and the sandbox credentials below. Al checkout il cliente vede TEST MODE: payments go to the PayFast sandbox, no real money is charged. 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.

Quando aggiorni dalla versione 1.0 in modalità di prova, le credenziali esistenti vengono copiate nei campi sandbox. Verifica le credenziali live prima di disattivare la modalità di prova.

Notifiche di pagamento (ITN)

PayFast conferma ogni pagamento con una notifica server-to-server inviata all'URL mostrato in questa sezione. Ha questo aspetto: https://your-site/wc-api/payfast_pay/. L'indirizzo viene inviato con ogni pagamento, quindi non c'è nulla da configurare in PayFast, ma deve essere raggiungibile da Internet.

Controllo dell'origine: Accept live notifications only from PayFast servers. Gli indirizzi provengono dai record DNS di PayFast. Disattivalo solo se il sito si trova dietro un proxy o una CDN che nasconde l'indirizzo del visitatore. Firma e conferma server vengono sempre verificate. Le notifiche sandbox non vengono controllate per indirizzo. Predefinito: attivo.

Avanzate

Debug log: Log payment steps scrive i passaggi in WooCommerce > Status > Logs, origine wcp_payfast_pay. Gli errori vengono sempre registrati. Non vengono scritte passphrase né dati dei clienti. Predefinito: disattivato.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita PayFast) e completa l'ordine. Il cliente arriva alla pagina Pay for order dell'ordine, che mostra Thank you for your order. You are being redirected to PayFast to complete the payment. e invia automaticamente a PayFast il modulo di pagamento firmato. Se il browser non prosegue da solo, il cliente fa clic su Pay with PayFast; Cancel order annulla l'ordine. Il modulo contiene il totale dell'ordine in ZAR, Order # con il numero dell'ordine, nome e e-mail del cliente e la chiave dell'ordine. Viene generato di nuovo ogni volta che la pagina viene aperta, così il cliente può riaprirlo dopo essere tornato da PayFast.

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 quando la notifica supera tutti i controlli:

Il ritorno del cliente alla pagina Ordine ricevuto non modifica l'ordine. Finché la notifica non arriva, la pagina dice PayFast is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se l'ordine è in attesa, dice Your payment is being reviewed. We will contact you if anything else is needed.

Se il cliente annulla sulla pagina di PayFast, l'ordine viene annullato nel modo standard di WooCommerce. Se il cliente se ne va senza pagare, l'ordine resta non pagato e può essere pagato di nuovo dalla pagina Pay for order.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È nascosto quando mancano le credenziali della modalità attuale, quando la valuta del negozio o dell'ordine non è ZAR, o quando il totale è inferiore a R5.00. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).

Il plugin accetta solo pagamenti unici in ZAR. Non prevede rimborsi da WooCommerce, abbonamenti, carte salvate (tokenizzate), pre-ordini o pagamenti frazionati.

Ordini

Stati dell'ordine

Pending payment: il cliente è stato inviato a PayFast e la notifica di pagamento non è ancora arrivata.

Processing: PayFast ha confermato il pagamento. È lo stato standard di WooCommerce dopo il pagamento; gli ordini con solo prodotti virtuali scaricabili diventano Completato. La nota dell'ordine mostra l'ID del pagamento PayFast, che è anche l'ID transazione dell'ordine. Un pagamento in sandbox riceve la nota che non è stato addebitato denaro reale. La commissione PayFast e l'importo netto vengono salvati nell'ordine.

On hold: PayFast ha segnalato il pagamento come in attesa; oppure l'importo pagato differisce dal totale dell'ordine, o l'ordine non è in ZAR; oppure è arrivato un pagamento per un ordine già annullato. La nota dell'ordine lo spiega. Controlla l'ordine e la dashboard di PayFast, poi spedisci l'ordine o rimborsa il pagamento in PayFast.

Failed: PayFast ha segnalato il pagamento come non riuscito mentre l'ordine era non pagato. Il cliente può pagare di nuovo.

Cancelled: il cliente ha annullato sulla pagina di PayFast, oppure l'ordine è stato annullato da te o dal timeout di riserva delle scorte di WooCommerce.

Una notifica ripetuta per lo stesso pagamento non cambia nulla. Se arriva un altro pagamento completato per un ordine già pagato, una nota ti chiede di rimborsare il duplicato in PayFast. Un pagamento per un ordine rimborsato aggiunge solo una nota. Un pagamento in sandbox ricevuto mentre il gateway è in modalità live aggiunge una nota e non segna l'ordine come pagato.

Rimborsi

I rimborsi da WooCommerce non sono supportati. Rimborsa il pagamento nella dashboard di PayFast, poi crea un rimborso manuale in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco di licenza si trova in alto in WooCommerce > Settings > Payments > PayFast. 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 per 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, PayFast 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. Gli amministratori del negozio connessi vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle 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 verificato di nuovo automaticamente in background.

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 la valuta del negozio sia ZAR e che il totale dell'ordine sia di almeno R5.00. La pagina delle impostazioni mostra un avviso quando manca qualcosa.

Il pagamento è andato a buon fine, ma l'ordine resta in attesa di pagamento: PayFast non è riuscito a consegnare la notifica di pagamento, oppure è stata rifiutata. Attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_payfast_pay. Motivi tipici: il sito non è raggiungibile da Internet (modalità manutenzione, autenticazione di base, firewall), una passphrase diversa in PayFast e nel plugin, oppure, in modalità live dietro un proxy o una CDN, il controllo dell'origine. In quel caso disattiva Source check.

La notifica risponde Invalid signature: la passphrase nel plugin non è quella impostata in PayFast per questa modalità.

La notifica risponde Invalid source: la notifica non proveniva da un indirizzo di PayFast, oppure un proxy o una CDN nasconde l'indirizzo reale. Disattiva Source check se il sito si trova 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 ordine. Non viene modificato nulla.

La notifica risponde Confirmation unavailable o Busy: PayFast non è raggiungibile per la conferma server, oppure un'altra notifica per lo stesso ordine era in elaborazione nello stesso momento. PayFast riprova la notifica.

La notifica risponde Not configured: mancano le credenziali della modalità in cui è stato pagato l'ordine.

Il cliente vede PayFast accepts payments from R5.00: il totale dell'ordine è inferiore al minimo di PayFast.

L'ordine è On hold: PayFast ha confermato un pagamento che non corrisponde all'ordine (importo diverso, oppure valuta diversa da ZAR), oppure il pagamento è arrivato per un ordine già annullato. Controlla le note dell'ordine e la dashboard di PayFast.

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

Il blocco di 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 conserva 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, le altre opzioni del plugin, gli indirizzi PayFast in cache e i suoi log vengono rimossi solo se Delete the gateway settings and logs when the plugin is deleted era attivo. Altrimenti restano disponibili per una successiva reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

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