VibeFox Peach Payments for WooCommerce — Guida
Requisiti
WordPress: 6.2 o successivo.
WooCommerce: 8.0 o successivo, installato e attivo. Senza di esso il plugin non si attiva.
PHP: 8.0 o successivo.
Currency: la valuta del negozio deve essere ZAR, KES o MUR. Con altre valute il metodo di pagamento viene nascosto e la pagina delle impostazioni lo segnala.
Peach Payments account: servono le credenziali Card API del tuo account Peach Payments: Entity ID e Access Token. Quelle di test provengono dal pannello sandbox Peach Payments, quelle live dal pannello Peach Payments; sono diverse. Per i webhook serve anche una chiave di decrittazione che Peach Payments ti invia quando abilita i webhook Card per il negozio (vedi Configurazione). Il sito deve essere raggiungibile da Internet per ricevere i webhook.
VibeFox license key: acquistata su vibefox.net. Una chiave funziona su un dominio.
Installazione
1. In WordPress vai a Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_peach_pay in /wp-content/plugins/ tramite FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Peach Payments > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina dei plugin.
4. Inserisci la chiave di licenza VibeFox nel blocco della licenza in cima alla pagina e fai clic su Activate.
5. Inserisci Entity ID e Access Token di test dal pannello sandbox Peach Payments e chiedi a Peach Payments di abilitare i webhook Card per l'URL indicato nelle impostazioni (vedi Configurazione).
6. Attiva Enable/Disable e salva. Lascia Test mode attivo ed effettua un pagamento con una carta di test della sandbox Peach Payments. Poi deseleziona Test mode, inserisci le credenziali live e la chiave webhook live e salva.
Le impostazioni della versione 1.0 vengono trasferite automaticamente nei nuovi campi dopo l'aggiornamento.
Configurazione
Tutte le impostazioni sono in una pagina: WooCommerce > Settings > Payments > Peach Payments. Sopra i campi appaiono avvisi: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; un avviso se manca Entity ID o Access Token della modalità corrente (fino ad allora il metodo non appare al checkout); un avviso se manca la chiave di decrittazione webhook della modalità corrente (i pagamenti vengono allora confermati solo al ritorno del cliente); e un avviso se la valuta non è supportata. Nell'elenco dei metodi di pagamento, Peach Payments risulta da configurare finché la modalità corrente non ha Entity ID e Access Token. Al salvataggio vengono rimossi gli spazi dalle credenziali; una chiave webhook non esadecimale di 64 caratteri genera un errore.
Enable/Disable: Enable Peach Payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo mostrato al cliente al checkout. Predefinito: Credit / Debit Card (Peach Payments).
Description: il testo sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
Credenziali API
Access Token ed Entity ID della Card API sono nel pannello Peach Payments (credenziali di test: pannello sandbox). La sezione contiene collegamenti a entrambi i pannelli e alla documentazione per sviluppatori Peach Payments.
Test mode: Enable test mode invia nuovi pagamenti alla sandbox Peach Payments con le credenziali di test, senza addebitare denaro reale. Deselezionalo per accettare pagamenti reali con le credenziali live. Un pagamento iniziato in una modalità viene sempre verificato in quella modalità, anche dopo un cambio. Predefinito: attivato.
Test Entity ID: l'Entity ID (canale 3-D Secure) del tuo account sandbox.
Test Access Token: il token di accesso bearer del tuo account sandbox.
Test Webhook Decryption Key: la chiave esadecimale di 64 caratteri per decrittare i webhook Card della sandbox.
Live Entity ID: l'Entity ID (canale 3-D Secure) del tuo account live.
Live Access Token: il token di accesso bearer del tuo account live.
Live Webhook Decryption Key: la chiave esadecimale di 64 caratteri per decrittare i webhook Card dell'account live.
Webhook
I webhook confermano i pagamenti anche se il cliente chiude il browser prima di tornare al negozio. La sezione mostra l'URL webhook del negozio, del tipo https://your-site/wp-json/peach-pay/v1/webhook. Copialo esattamente come appare nelle impostazioni. Chiedi a Peach Payments (support@peachpayments.com) di abilitare i webhook Card per il tuo account con questo URL, poi inserisci la chiave ricevuta nel campo Webhook Decryption Key della stessa modalità.
Peach Payments crittografa ogni webhook (AES-256-GCM). Un webhook che non può essere decrittato con la chiave test o live viene rifiutato, così solo Peach Payments può modificare gli ordini. Un webhook decrittato con la chiave di una modalità si applica solo ai pagamenti iniziati in quella modalità. Il plugin usa le notifiche di pagamento:
Le altre notifiche, ad esempio quella di test inviata all'attivazione del webhook, ricevono risposta OK e sono ignorate. Senza chiave webhook, l'ordine viene confermato solo quando il cliente torna al negozio dopo il pagamento.
Modulo di pagamento
Card brands: i circuiti mostrati nel modulo Peach Payments: Visa, Mastercard, American Express, Diners Club. Seleziona solo quelli abilitati per il tuo Entity ID. Predefinito: Visa e Mastercard.
Avanzate
Logging: Log API requests and payment results scrive informazioni di debug in WooCommerce > Status > Logs, fonte wcp_peach_pay. Errori e avvisi vengono sempre registrati. I registri non contengono dati delle carte, chiavi o dati dei clienti. Predefinito: disattivato.
Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Disattivare il plugin non elimina mai nulla. I dati Peach Payments degli ordini vengono conservati. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (predefinito Credit / Debit Card (Peach Payments)) e fa clic su Continue to payment. Viene portato alla pagina Pay for order del tuo negozio. Qui il plugin prepara un checkout Peach Payments per il totale e nella valuta dell'ordine e mostra il modulo della carta Peach Payments con i circuiti selezionati, nella lingua del sito se supportata da Peach Payments. In modalità test la pagina mostra Test mode: use a Peach Payments test card, no real payment will be made.. I dati della carta vengono inseriti nel modulo Peach Payments e lo script viene caricato con un hash Subresource Integrity.
Dopo il pagamento il cliente torna al negozio. L'ordine viene segnato come pagato solo dopo la conferma di Peach Payments: il negozio legge il risultato del checkout dell'ordine dall'API Peach Payments nella modalità di creazione e verifica che il pagamento appartenga all'ordine. Il webhook fa lo stesso indipendentemente: il primo ad arrivare applica il risultato e l'altro non cambia nulla. Il cliente che ha pagato vede la pagina Order received.
Se il pagamento non è completato, il cliente torna alla pagina Pay for order con un messaggio e può riprovare: Payment failed: seguito dal motivo di Peach Payments e Please try again or use another card., oppure The payment was not completed. Please try again.. Se il risultato non è ancora confermabile (ad esempio Peach Payments non risponde o il webhook elabora lo stesso ordine), il messaggio è We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.. Se la modalità non ha una chiave webhook, al cliente viene invece chiesto di contattarti con il numero dell'ordine.
Se il modulo non può essere preparato, il cliente vede un breve messaggio e un pulsante Try again: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (credenziali errate), un messaggio che alcuni dati di fatturazione non sono stati accettati dal fornitore di pagamento oppure The payment form could not be loaded. Please try again in a moment.. L'ordine riceve una nota con codice e descrizione Peach Payments.
Il metodo funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin non prevede un modulo della carta nella pagina del checkout stessa, carte salvate, abbonamenti, preautorizzazione e acquisizione, né EFT, BNPL, QR o altri metodi senza carta.
Ordini
Stati degli ordini
Pending payment: il cliente non ha ancora pagato o il pagamento non è completato. Può pagare di nuovo lo stesso ordine.
Processing: il pagamento è confermato e importo e valuta corrispondono all'ordine. La nota mostra codice risultato, descrizione e ID pagamento Peach Payments; quest'ultimo è l'ID transazione dell'ordine. Se Peach Payments richiede una verifica manuale, la nota ti chiede di controllare il pagamento nel pannello Peach Payments prima della spedizione.
On hold: il pagamento attende conferma da Peach Payments (il webhook lo completa più tardi o lo segna come fallito); importo o valuta differiscono dall'ordine (nota amount/currency mismatch — manual review required); oppure il pagamento è arrivato dopo l'annullamento. La nota spiega cosa controllare.
Failed: Peach Payments ha rifiutato il pagamento di un ordine In attesa di pagamento o il pagamento atteso da un ordine In sospeso. Un tentativo rifiutato non modifica mai un ordine pagato, in sospeso per altri motivi o annullato. Il cliente può pagare di nuovo.
Se un secondo pagamento di un ordine già pagato riesce, l'ordine non cambia. Una nota indica il pagamento duplicato e ti chiede di rimborsarlo nel pannello Peach Payments. Un pagamento per un ordine rimborsato viene solo annotato.
Rimborsi
I rimborsi dalla schermata dell'ordine WooCommerce non sono disponibili. Rimborsa dal pannello Peach Payments e registra un rimborso manuale in WooCommerce. Con il webhook configurato, rimborsi, annullamenti e contestazioni in Peach Payments vengono aggiunti come note con importo e ID; lo stato dell'ordine non cambia.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Peach Payments. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio scadenza della licenza e dominio. Usa Check now per ricontrollare, Change key per inserire un'altra chiave e Remove key per rimuoverla dal sito. Il collegamento Manage licenses and domains in your account apre il tuo account vibefox.net.
Una chiave funziona su un dominio. Rimuoverla dal sito non libera il posto del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Peach Payments non viene mostrato ai clienti al checkout. Se viene comunque avviato un pagamento, il cliente vede This payment method is not available. Please choose another one.. I gestori del negozio autenticati vedono ancora il metodo, contrassegnato (unlicensed — visible to admins only), per permetterti di configurare e provare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina dei plugin e nelle pagine WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già iniziati vengono ancora confermati dal ritorno del cliente e dal webhook.
Alla scadenza della licenza il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
Peach Payments non appare al checkout: verifica che la licenza sia attiva, Enable/Disable abilitato, Entity ID e Access Token della modalità corrente inseriti (Test Entity ID e Test Access Token in test, Live Entity ID e Live Access Token in live) e la valuta ZAR, KES o MUR. Gli avvisi in cima alle impostazioni indicano il problema. Gli sviluppatori possono cambiare le valute con il filtro peach_p_supported_currencies; aggiungi solo quelle elaborate dal tuo account Peach Payments.
Il pagamento è riuscito ma l'ordine resta Pending payment: il cliente non è tornato e il webhook non è arrivato. Verifica che Peach Payments abbia abilitato i webhook Card per l'URL esatto delle impostazioni, che Webhook Decryption Key della modalità usata sia inserita e che manutenzione, firewall o password non blocchino l'URL. Cerca i webhook rifiutati in WooCommerce > Status > Logs, fonte wcp_peach_pay.
Il webhook risponde Decryption failed: non è stato decrittato con la chiave test o live. La chiave è errata o appartiene a un altro account o modalità. Inserisci quella inviata da Peach Payments per questo URL.
Il webhook risponde Webhook key not configured: nessuna chiave webhook è impostata o valida. Inserisci la chiave di 64 caratteri. Peach Payments invierà di nuovo il webhook più tardi.
Il webhook risponde Order busy, retry later: l'ordine veniva aggiornato contemporaneamente dal ritorno del cliente. Nulla è cambiato e Peach Payments invia di nuovo il webhook.
Il webhook risponde Missing or malformed data: la richiesta non aveva un corpo crittografato o le intestazioni X-Initialization-Vector / X-Authentication-Tag, ad esempio per una modifica del proxy. Nulla è cambiato.
Il webhook risponde ignored: la notifica è autentica ma non appartiene a un checkout del negozio (altro negozio sullo stesso Entity ID, ordine eliminato), o proviene da una modalità diversa dal pagamento. Nulla è cambiato.
Il cliente vede The payment form is not available right now: Access Token o Entity ID della modalità corrente è errato. Controlla credenziali e modalità e leggi il codice Peach Payments nella nota dell'ordine.
L'ordine è On hold dopo il pagamento: leggi la nota. Importo o valuta differivano, il pagamento è arrivato dopo l'annullamento o Peach Payments attende ancora conferma. Controlla il pagamento nel pannello Peach Payments, poi elabora l'ordine o rimborsa.
Al salvataggio viene richiesta una chiave webhook esadecimale di 64 caratteri: il valore non è la chiave Peach Payments. I webhook non possono essere decrittati finché non viene corretto.
Il blocco licenza mostra un errore: segui il messaggio. Se la chiave è usata su un altro dominio, libera un posto nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivarla sul nuovo dominio. Se il server licenze è irraggiungibile, il plugin continua con l'ultimo stato noto.
Disinstallazione
Disattivando il plugin tutti i dati restano. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. Chiave e stato della licenza vengono sempre rimossi. Impostazioni e registri (file e voci nel database della fonte wcp_peach_pay) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano note di pagamento, ID transazione e dati del checkout Peach Payments.
Peach Payments è un marchio del rispettivo titolare. Questo plugin non è affiliato a Peach Payments né approvato da questa società.