VibeFox Yoco 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 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 sotto Selling Online > Payment Gateway. Si inseriscono solo le chiavi segrete. Il webhook viene registrato dal modulo e il suo segreto di firma viene compilato per te.

Sito pubblico: Yoco invia webhook al tuo negozio, quindi deve essere raggiungibile da internet. L'URL del webhook deve accettare un POST senza reindirizzamenti.

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 clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento clicca su Configure, oppure trova più tardi VibeFox Yoco Pay Gateway 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 la chiave segreta di test (sk_test_...) e, quando sei pronto, la chiave segreta live (sk_live_...). Clicca su Save. Il webhook viene registrato per ogni modalità che ha una chiave.

5. Attiva Enable/Disable e clicca su Save. Effettua un pagamento di prova con una carta di test Yoco mentre Test mode è attivo, poi disattiva Test mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine Yoco payment on hold. PrestaShop attiva il 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 Yoco Pay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando la valuta del negozio non è ZAR (Yoco non viene quindi offerto al checkout) e quando la modalità corrente non ha una chiave segreta, ad esempio Enter the test secret key to offer Yoco at checkout (test mode). Al salvataggio il modulo verifica le chiavi e i segreti dei webhook e registra i webhook. I messaggi al riguardo compaiono in cima alla pagina.

Yoco

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento memorizzato nell'ordine. 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 sotto Selling Online > Payment Gateway. Yoco ha un'unica API per entrambe le modalità: è la chiave a determinare se un pagamento è di test o reale. La modalità test usa solo la chiave di test, la modalità live solo la chiave live.

Test mode: usa la chiave segreta di test. Non viene addebitato denaro reale; paga con le carte di test Yoco. Predefinito: attivo. Disattivalo per accettare pagamenti reali. Finché è attivo, i clienti vedono Test mode — use a Yoco test card; no real money is charged. sotto il metodo di pagamento.

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, ad esempio Yoco: the test secret key must start with sk_test_ — the previous value was kept. Se Yoco comunica durante la registrazione del webhook che una chiave appartiene all'altra modalità, la pagina te lo segnala.

Chiavi e segreti salvati non vengono mai più mostrati. Il campo resta vuoto e riporta Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.

Webhook

Yoco conferma pagamenti e rimborsi all'URL mostrato in Webhook URL in questa sezione. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_yoco_pay/webhook, eventualmente con un codice lingua come /en/. Non devi creare il webhook nel portale Yoco. Quando salvi le impostazioni, il modulo registra l'URL presso Yoco per ogni modalità che ha una chiave segreta ma nessun segreto di 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à (Test e Live) la sezione mostra lo stato del webhook:

Il modulo gestisce questi eventi (sono elencati anche in questa sezione):

I webhook senza firma valida vengono rifiutati. Un evento deve essere firmato con il segreto della modalità in cui è stato effettuato il pagamento, quindi una chiave segreta di test non conferma mai un pagamento reale. Copia 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. Svuotalo e salva per registrare di nuovo il webhook.

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

Clear saved secrets: seleziona una chiave o un segreto e clicca su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato. Svuotare un segreto del webhook e salvare registra di nuovo il webhook.

Avanzate

Debug log: scrive richieste e webhook di Yoco in logs/yoco_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi, come richieste fallite verso Yoco e webhook rifiutati, vengono sempre registrati. Chiavi, segreti dei webhook e indirizzi e-mail sono mascherati. Predefinito: disattivato.

Log: mostra la dimensione e gli ultimi inserimenti del registro. Clicca su Clear log per svuotarlo.

Delete data: se attivo, la disinstallazione del modulo rimuove le impostazioni, il registro e i webhook che il modulo ha registrato presso Yoco. I dati degli ordini (ID di checkout e di pagamento Yoco, rimborsi) e lo stato dell'ordine Yoco payment on hold restano sempre, perché sono necessari per i rimborsi. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Card or Instant EFT (Yoco)) e conferma. Il modulo crea un checkout Yoco per il totale del carrello in centesimi e invia il cliente alla pagina di pagamento Yoco, dove paga con carta o Instant EFT. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Yoco: il modulo chiede a Yoco il checkout quando il cliente torna e di nuovo quando arriva il webhook firmato. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Yoco has been received. Se Yoco non ha ancora confermato il pagamento quando il cliente torna, una pagina Payment confirmation mostra We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. con un pulsante Check again; il webhook crea l'ordine appena arriva.

Se il cliente annulla sulla pagina Yoco, torna al checkout con The Yoco payment was cancelled. Your cart is saved — you can pay again 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. Il carrello viene conservato.

Prima di un nuovo tentativo di pagamento per lo stesso carrello, il modulo verifica il precedente con Yoco. Se è già stato pagato, l'ordine viene creato senza 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. Altrimenti viene creato un nuovo checkout Yoco.

Se Yoco non riesce ad avviare il pagamento, il cliente resta al checkout con Yoco could not start the payment. Please try again in a moment or choose another payment method. e il motivo viene scritto nel registro. Un ordine inferiore a R2,00 mostra Yoco requires an order total of at least R2.00.

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

I pagamenti vengono addebitati immediatamente sulla pagina Yoco. Il modulo non prevede carte salvate, abbonamenti o pagamenti ricorrenti, né modulo di carta sul sito né autorizzazione e acquisizione separate, e non funziona in valute diverse da ZAR.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Yoco e non ha pagato, ha annullato sulla pagina Yoco, oppure Yoco non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Viene registrato con l'ID di pagamento Yoco come ID transazione, e una nota mostra l'importo, gli ID di pagamento e checkout Yoco, la modalità e il modo in cui il pagamento è stato confermato (il ritorno del cliente, il webhook o una verifica prima di un nuovo tentativo di pagamento).

Yoco payment on hold: Yoco ha comunicato un importo o una valuta diversi dal totale del carrello, ad esempio perché il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento. Nessun pagamento viene registrato, la nota lo spiega e il cliente vede We received your payment and are reviewing it. We will contact you if anything else is needed. Verifica il pagamento prima della spedizione. Se il cliente paga poi l'importo corretto con un altro tentativo, l'ordine passa a Payment accepted.

Cancelled or Refunded: un pagamento che arriva per un ordine del genere non lo modifica. Una nota ti chiede di rimborsare il pagamento nel portale Yoco o di ripristinare l'ordine manualmente. Il cliente 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 cambia. Una nota ti chiede di rimborsarlo nel portale Yoco.

Blocco pagamento Yoco

La pagina dell'ordine mostra un blocco Yoco payment con gli ID di pagamento e di checkout Yoco, lo stato, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di test, lo storico dei rimborsi, i tentativi di pagamento del carrello (quando ce n'è più di uno) e le Yoco notes dell'ordine.

Rimborsi

Nel blocco Yoco payment inserisci l'importo (viene compilato quello non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Yoco. Conferma la domanda Refund this amount through Yoco? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il diritto di modificare gli ordini. I rimborsi sono calcolati sull'importo addebitato da Yoco, quindi puoi rimborsare al massimo quanto il cliente ha effettivamente pagato, anche se l'ordine è stato modificato in seguito. 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 allo storico dei rimborsi e alle note con l'ID di rimborso Yoco. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. Se Yoco rifiuta il rimborso, il blocco mostra Yoco refused the refund: con il motivo, e nessun rimborso viene registrato. Se Yoco comunica che il rimborso è in attesa, il blocco lo indica. Non ripeterlo: verrà registrato quando Yoco lo confermerà tramite webhook. I rimborsi sono disponibili per gli ordini pagati tramite un checkout Yoco. Un ordine in Yoco payment on hold non ha un checkout pagato da rimborsare; rimborsalo nel portale Yoco.

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

I rimborsi effettuati nel portale Yoco arrivano tramite il webhook refund.succeeded e vengono registrati nello storico dei rimborsi e nelle note. Quando raggiungono l'importo pagato, l'ordine passa a Refunded. Un rimborso superiore all'importo ancora rimborsabile non viene registrato, e una nota ti chiede di verificare l'ordine. Un rimborso non riuscito aggiunge una nota che indica che il denaro non è stato restituito al cliente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Yoco Pay Gateway è il primo blocco di Modules > Module Manager > VibeFox Yoco Pay Gateway > 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 compaiono la riga Product: presta-payment-yoco 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 incluse l'inglese e il 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 un posto per il 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il posto per il dominio. Liberalo 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. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a 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 continuano a essere confermati e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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 nessun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Yoco non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia una chiave segreta: Test secret key in modalità test, Live secret key in modalità live. La valuta del carrello 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 del negozio non è ZAR. In Payment > Preferences verifica che il modulo sia consentito per ZAR, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: 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 creato anche quando il cliente torna al negozio dopo il pagamento, e quando il cliente 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, ad esempio che il negozio 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. webhook secret not configured significa che nessun segreto del webhook è impostato. 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.

L'URL del webhook mostra solo POST nel browser: è normale. L'URL accetta solo richieste da Yoco.

Errore al salvataggio «The secret key must start with sk_test_ / sk_live_»: 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 scegliendo Yoco: controlla il campo Log nella pagina del modulo. Yoco is not available at the moment. Please choose another payment method. significa che la modalità corrente non ha una chiave segreta.

Al cliente viene comunicato che un pagamento deve essere verificato: un tentativo è stato pagato con un importo diverso, o dopo che l'ordine era stato annullato. Leggi le note nel blocco Yoco payment ed evadi l'ordine oppure rimborsa il pagamento nel portale Yoco.

Il rimborso fallisce 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 fallisce con No answer from Yoco: nulla è stato registrato in PrestaShop. Se Yoco ha comunque elaborato il rimborso, ripeti lo stesso rimborso: non verrà rimborsato due volte.

Sviluppatori: l'hook actionYocoPCheckoutPayload consente a un altro modulo di modificare la richiesta che crea il checkout Yoco.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Yoco Pay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data è attivo, vengono rimosse le impostazioni, il registro e i webhook che il modulo ha registrato presso Yoco. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I checkout e i rimborsi Yoco e lo stato dell'ordine Yoco payment on hold vengono sempre conservati, così gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.

Yoco è un marchio del rispettivo titolare. Questo modulo non è affiliato a Yoco né approvato da Yoco.