VibeFox Yoco 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 del negozio: rand sudafricano (ZAR). Yoco accetta solo ZAR. In qualsiasi altra valuta il metodo di pagamento non viene mostrato al checkout. Il totale dell'ordine deve essere di almeno R2,00.

Account Yoco: un account Yoco con pagamenti online. Ti servono le sue chiavi segrete, che trovi nello Yoco Business Portal in Selling Online > Payment Gateway. Si inseriscono solo le chiavi segrete. Il webhook viene registrato dal plugin, e il suo segreto di firma viene compilato per te.

Sito pubblico: Yoco invia webhook al tuo sito, quindi deve essere raggiungibile da Internet. L'URL del webhook deve accettare una richiesta POST senza reindirizzamenti.

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

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. In alternativa puoi caricare la cartella wcp_yoco_pay in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Yoco > Manage.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.

5. Incolla la chiave segreta di test (sk_test_...) e, quando sei pronto, la chiave segreta live (sk_live_...). Salva le impostazioni. Il webhook viene registrato per ogni modalità che ha una chiave.

6. Attiva Enable/Disable. Effettua un pagamento di prova con una carta di test Yoco mentre Test mode è attivo, poi deseleziona Test mode per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Yoco. Sopra i campi la pagina avvisa quando la valuta del negozio non è ZAR (in tal caso Yoco non viene offerto al checkout) e quando la modalità attuale non ha una chiave segreta. Nell'elenco dei metodi di pagamento, Yoco è segnalato come da configurare finché la modalità attuale non ha una chiave segreta. Al salvataggio il plugin verifica le chiavi e i segreti dei webhook e registra i webhook. I messaggi al riguardo compaiono in cima alla pagina.

Generali

Enable/Disable: Enable Yoco attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Card or Instant EFT (Yoco).

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: You will be redirected to the secure Yoco page to pay by card or Instant EFT.

Chiavi API

Copia le chiavi segrete dallo Yoco Business Portal in Selling Online > Payment Gateway. Yoco ha un'unica API per entrambe le modalità: è la chiave a decidere se un pagamento è di prova o reale. La modalità test usa solo la chiave di test, la modalità live solo la chiave live.

Test mode: Use the test secret key (no real payments). Non viene addebitato denaro reale; paga con le carte di test Yoco. Predefinito: on. Deselezionala per accettare pagamenti reali.

Test secret key: la chiave segreta della modalità test. Inizia con sk_test_.

Live secret key: la chiave segreta della modalità live. Inizia con sk_live_.

Una chiave che non inizia con il prefisso previsto non viene salvata: la pagina mostra un errore e mantiene il valore precedente. Se durante la registrazione del webhook Yoco segnala che una chiave appartiene all'altra modalità, la pagina te lo comunica.

Webhook

Yoco conferma pagamenti e rimborsi all'URL del webhook mostrato in questa sezione. Ha questo formato: https://your-site/wc-api/yoco_pay_webhook/. Non devi creare il webhook nel portale Yoco. Quando salvi le impostazioni, il plugin registra l'URL presso Yoco per ogni modalità che ha una chiave segreta ma nessun segreto del webhook, e memorizza il segreto di firma nel campo di quella modalità. Registra di nuovo l'URL quando cambia la chiave segreta di quella modalità o l'URL del webhook. Quando l'URL cambia, la vecchia registrazione viene rimossa.

Per ogni modalità la sezione mostra lo stato del webhook:

Il plugin gestisce questi eventi:

I webhook senza firma valida vengono rifiutati. Se il tuo sito usa un prefisso di lingua negli URL, mantieni l'URL esattamente come lo mostrano le impostazioni, perché il webhook deve raggiungere il negozio senza reindirizzamenti.

Test webhook secret: compilato automaticamente alla registrazione del webhook. Incolla un segreto (whsec_...) solo se hai registrato tu l'URL del webhook.

Live webhook secret: compilato automaticamente alla registrazione del webhook. Svuota il campo e salva per registrare di nuovo il webhook.

Un segreto del webhook deve avere la forma whsec_ seguito da testo in base64. Qualsiasi altro valore non viene salvato e resta quello precedente.

Avanzate

Debug log: Log Yoco requests and webhooks scrive richieste e webhook in WooCommerce > Status > Logs, origine wcp_yoco_pay. Errori e avvisi, come le richieste a Yoco non riuscite e i webhook rifiutati, vengono sempre registrati. Chiavi, segreti dei webhook e indirizzi e-mail sono mascherati. Predefinito: off.

Delete data: Delete the settings and logs of this plugin when it is deleted. La disattivazione non cancella mai nulla. I dati degli ordini (ID del checkout e del pagamento Yoco) vengono sempre conservati, perché servono per i rimborsi. Predefinito: off.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Card or Instant EFT (Yoco)) e invia l'ordine. In modalità test il checkout mostra Test mode — use a Yoco test card; no real money is charged. Il plugin crea un checkout Yoco per il totale dell'ordine in centesimi e invia il cliente alla pagina di pagamento Yoco, dove paga con carta o Instant EFT.

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Yoco: il plugin chiede a Yoco il checkout quando il cliente torna e di nuovo quando arriva il webhook firmato. Se Yoco non ha ancora confermato il pagamento, la pagina di ricezione dell'ordine mostra We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.

Se il cliente annulla nella pagina Yoco, l'ordine resta non pagato e il cliente arriva alla pagina Pay for order con il messaggio The Yoco payment was cancelled. Your order is saved — you can pay again below or choose another payment method. Se il pagamento non riesce, il messaggio è The Yoco payment was not successful. Please try again or choose another payment method. e viene aggiunta una nota all'ordine.

Il cliente può pagare di nuovo un ordine non pagato dalla pagina Pay for order. Prima di un nuovo tentativo il plugin verifica il precedente con Yoco. Se era già pagato, l'ordine viene completato senza mostrare una nuova pagina di pagamento. Se è ancora aperto per lo stesso importo ed è stato creato meno di 30 minuti fa, il cliente riceve di nuovo la stessa pagina Yoco.

Se Yoco non riesce ad avviare il pagamento, il cliente vede Yoco could not start the payment. Please try again in a moment or choose another payment method. e il motivo viene aggiunto alle note dell'ordine. Un ordine sotto R2,00 riceve Yoco requires an order total of at least R2.00.

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

I pagamenti vengono addebitati subito nella pagina Yoco. Il plugin non prevede carte salvate, abbonamenti o pagamenti ricorrenti, nessun modulo di inserimento carta sul sito e nessuna autorizzazione e acquisizione separate, e non funziona con valute diverse da ZAR.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Yoco e non ha ancora pagato, ha annullato nella pagina Yoco, oppure Yoco non ha ancora confermato il pagamento.

Processing or Completed: il pagamento è stato confermato. WooCommerce imposta In lavorazione, oppure Completato per gli ordini con soli prodotti virtuali scaricabili. La nota dell'ordine mostra l'importo, gli ID del pagamento e del checkout Yoco, la modalità e come è stato confermato il pagamento (il ritorno del cliente, il webhook o una verifica prima di un nuovo tentativo di pagamento). L'ID transazione è l'ID del pagamento Yoco.

On hold: Yoco ha segnalato un importo o una valuta diversi dal totale dell'ordine, ad esempio perché l'ordine è stato modificato dopo l'avvio del pagamento. La nota lo spiega, e il cliente che torna da Yoco vede We received your payment and are reviewing it. We will contact you if anything else is needed. Verifica il pagamento prima della spedizione.

Cancelled or Refunded: un pagamento che arriva per un ordine così non lo modifica. Una nota ti chiede di rimborsare il pagamento nel portale Yoco o di ripristinare l'ordine manualmente. Il cliente che torna da Yoco vede Your payment was received after the order had been cancelled. Please contact us — do not pay again.

Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato di nuovo. Una nota ti chiede di rimborsarlo nel portale Yoco.

Rimborsi

Apri l'ordine, clicca su Refund, inserisci l'importo e clicca sul pulsante Refund via con il titolo del tuo metodo di pagamento (per impostazione predefinita Card or Instant EFT (Yoco)). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento (test o live), quindi la chiave segreta di quella modalità deve essere impostata. Un rimborso ripetuto dopo una risposta persa non viene pagato due volte.

Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID del rimborso Yoco. Se Yoco rifiuta il rimborso, WooCommerce mostra Yoco refused the refund: con il motivo, e nessun rimborso viene registrato. Se Yoco segnala il rimborso come in sospeso, WooCommerce indica che è ancora in sospeso e non registra nulla. Non ripeterlo: verrà aggiunto all'ordine quando Yoco lo confermerà tramite webhook.

I rimborsi effettuati nel portale Yoco arrivano tramite il webhook refund.succeeded e vengono registrati automaticamente come rimborsi WooCommerce, senza ripristinare le scorte. Un rimborso superiore all'importo ancora rimborsabile non viene registrato, e una nota ti chiede di controllare l'ordine. Un rimborso non riuscito aggiunge una nota che indica che il denaro non è stato restituito al cliente.

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 > Yoco. Incolla la chiave in License key e clicca 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 verificare 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 su un solo 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, Yoco 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 con accesso vedono ancora il metodo di pagamento, contrassegnato da (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 assistenza richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Yoco non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità attuale abbia una chiave segreta: Test secret key in modalità test, Live secret key in modalità live. La valuta del negozio o dell'ordine deve essere ZAR, e il totale dell'ordine di almeno R2,00. La pagina delle impostazioni mostra un avviso quando la chiave manca o la valuta non è ZAR.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: il webhook non funziona. Apri la sezione Webhooks delle impostazioni e controlla lo stato della modalità che usi. Se non è registrato, o è registrato per un altro URL, salva le impostazioni. Se la registrazione fallisce, la pagina mostra il motivo. Se hai inserito tu il segreto, verifica che appartenga al webhook di questo URL e di questa modalità. L'ordine viene confermato anche quando il cliente torna al negozio dopo il pagamento e quando prova a pagare di nuovo.

Impossibile registrare il webhook: i pagamenti vengono comunque confermati quando i clienti tornano al negozio. Risolvi il motivo indicato nel messaggio, per esempio che il sito deve essere raggiungibile da Internet tramite HTTPS, e salva di nuovo. Puoi anche registrare tu l'URL e incollare il segreto di firma.

I webhook vengono rifiutati: i webhook rifiutati vengono scritti nel registro, origine wcp_yoco_pay. webhook secret not configured significa che non è impostato nessun segreto del webhook. invalid signature significa che il segreto appartiene a un'altra registrazione o modalità. timestamp outside the tolerance significa che l'orologio del server è sbagliato: le firme vengono accettate entro 5 minuti dall'ora del server. checkout not completed yet — retry e could not confirm the checkout with Yoco — retry sono temporanei; Yoco invia di nuovo il webhook.

The secret key must start with sk_test_ / sk_live_ error on save: una chiave è stata incollata nel campo sbagliato. La chiave di test inizia con sk_test_, quella live con sk_live_. È stato mantenuto il valore precedente.

Il cliente vede un errore quando invia l'ordine: leggi le note dell'ordine oppure WooCommerce > Status > Logs, origine wcp_yoco_pay. Yoco is not available at the moment. Please choose another payment method. significa che la modalità attuale non ha una chiave segreta.

Al cliente viene detto che un pagamento deve essere verificato: un tentativo precedente è stato pagato con un importo diverso, oppure dopo l'annullamento dell'ordine. Leggi la nota dell'ordine ed evadi l'ordine oppure rimborsa il pagamento nel portale Yoco.

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 è impostata. Inseriscila e riprova.

Il rimborso non riesce con No answer from Yoco: non è stato registrato nulla in WooCommerce. Se Yoco ha comunque elaborato il rimborso, ripeti lo stesso rimborso: non verrà rimborsato due volte.

Il blocco 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 clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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 conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le registrazioni dei webhook presso Yoco e i log, compresi i file di log ruotati, vengono rimossi solo se Delete data era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID delle transazioni.

Yoco è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Yoco né approvato da Yoco.