VibeFox Quickpay for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

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

PHP: 8.0 o successivo.

Account Quickpay: ti servono due valori dal gestore Quickpay: la chiave API di un utente API (per creare pagamenti, acquisire e rimborsare) e la chiave privata dell'account (per verificare la firma dei callback di Quickpay). Non occorre configurare altro in Quickpay. Il tuo sito deve essere raggiungibile da internet, non protetto da password o in modalità manutenzione, perché i callback di Quickpay possano arrivare.

Chiave di licenza VibeFox: si acquista 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 fai clic su Install Now. Puoi anche caricare la cartella wcp_quickpay_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

5. Incolla la chiave API e la chiave privata dal gestore Quickpay e fai clic su Test API key (vedi Configurazione).

6. Scegli la modalità di acquisizione e lo stato dell'ordine dopo il pagamento, attiva Enable/Disable e salva. Mentre il tuo account Quickpay è in modalità test, attiva Test payments ed effettua un pagamento con una carta di prova Quickpay.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Quickpay. Finché non sono inserite sia la chiave API sia la chiave privata, Quickpay risulta come da configurare nell'elenco dei metodi di pagamento ed è nascosto al checkout, perché un pagamento non potrebbe essere né creato né confermato.

Generale

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Quickpay.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card or MobilePay on the Quickpay payment page.

Credenziali API Quickpay

Nel gestore Quickpay (manage.quickpay.net) apri Settings > Integration. Copia la chiave API di un utente API (Settings > Users) e la chiave privata dell'account. La sezione mostra anche l'URL di callback del tuo negozio, che ha questo formato: https://your-site/wc-api/qpg_quickpay/. Viene inviato automaticamente con ogni pagamento, quindi non occorre configurare nulla in Quickpay.

API key: la chiave API di un utente API Quickpay. Serve per creare pagamenti, acquisire e rimborsare.

Sotto il campo, il pulsante Test API key verifica la chiave digitata nel campo (o quella salvata, se il campo è vuoto) con una richiesta autenticata a Quickpay. Risponde Connection successful — the API key is valid., Quickpay rejected the API key., API key is not configured. oppure Connection failed: seguito dal motivo.

Private key: la chiave privata dell'account. Serve a verificare la firma (HMAC-SHA256) dei callback di Quickpay. Senza di essa nessun pagamento può essere confermato, e i callback vengono rifiutati.

Test payments: Accept payments made with Quickpay test cards. Quickpay non ha una sandbox separata: mentre il tuo account Quickpay è in modalità test, i pagamenti vengono effettuati con carte di prova e contrassegnati come tali. Attivalo solo durante i test. Quando è disattivato, un pagamento di prova non segna mai un ordine come pagato, e l'ordine riceve invece una nota. Quando è attivo, il checkout mostra Test mode: Quickpay test cards are accepted. Predefinito: disattivato.

Pagamento

Capture: quando il denaro viene prelevato dalla carta.

Order status after payment: lo stato dell'ordine una volta che Quickpay ha confermato il pagamento acquisito. Lo stato viene impostato subito, con un solo cambio di stato e un solo set di e-mail.

Avanzate

Debug log: Enable logging. Il registro si trova in WooCommerce > Status > Logs, origine wcp_quickpay_gateway. Errori e avvisi, come i callback rifiutati e gli errori delle API Quickpay, vengono sempre registrati. Attivalo per registrare anche ogni richiesta e ogni callback. Le chiavi API, i dati della carta e i dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete data: Delete the gateway settings and logs when the plugin is deleted. Disattivare il plugin non elimina mai nulla. I dati degli ordini (ID dei pagamenti Quickpay, note) vengono sempre conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Quickpay, mostrato con le icone Visa e Mastercard) e invia l'ordine. Il plugin crea per l'ordine un pagamento Quickpay nella valuta dell'ordine e un link di pagamento per il totale dell'ordine, e indirizza il cliente alla finestra di pagamento Quickpay. Il cliente paga lì con uno dei metodi attivati nella tua finestra di pagamento Quickpay. L'e-mail di fatturazione viene passata a Quickpay. La finestra di pagamento si apre nella lingua del tuo sito quando Quickpay la offre (danese, tedesco, inglese, spagnolo, finlandese, francese, italiano, olandese, norvegese, polacco, svedese), altrimenti in inglese.

Dopo il pagamento, il cliente torna alla pagina di conferma dell'ordine del tuo negozio. Il ritorno in sé non segna nulla come pagato. L'ordine viene segnato come pagato solo quando Quickpay lo conferma con il callback firmato e importo e valuta corrispondono all'ordine. Con Authorize only, l'ordine passa invece allo stato In attesa, e acquisisci il pagamento più tardi.

Se il cliente annulla nella finestra di pagamento durante il checkout, l'ordine non pagato viene annullato nel modo standard di WooCommerce e il carrello viene ripristinato. Nella pagina Pay for order, l'annullamento riporta il cliente su quella pagina, quindi l'ordine resta pagabile. Un pagamento non riuscito o annullato può essere ritentato: il nuovo tentativo riutilizza il pagamento Quickpay dell'ordine con un link nuovo, quindi un link vecchio non può mai essere pagato in parallelo. Quando un ordine non pagato viene annullato, il suo link di pagamento viene eliminato in Quickpay.

Se il pagamento non può essere avviato, il cliente vede The Quickpay payment could not be started. Please try again or choose another payment method. Il motivo tecnico viene aggiunto alle note dell'ordine e al registro. Se le chiavi mancano, il cliente vede Quickpay is not available at the moment. Please choose another payment method.

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

Il plugin accetta solo pagamenti una tantum. Non prevede abbonamenti né pagamenti ricorrenti, carte salvate, commissioni di pagamento, non invia a Quickpay righe di carrello o di fattura e non ha metodi separati MobilePay, Apple Pay o Klarna: il cliente sceglie tra i metodi della tua finestra di pagamento Quickpay.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Quickpay e non ha ancora pagato. Con l'acquisizione automatica, un pagamento autorizzato in attesa di acquisizione viene annotato sull'ordine.

Processing or Completed: Quickpay ha confermato il pagamento acquisito con importo e valuta corretti. Lo stato segue Order status after payment. La nota dell'ordine mostra l'ID del pagamento Quickpay (contrassegnato TEST per i pagamenti di prova), ed è salvato come ID transazione dell'ordine.

On hold: il pagamento è solo autorizzato e attende Capture Quickpay payment; oppure Quickpay ha segnalato un importo o una valuta diversi dal totale dell'ordine (per esempio l'ordine è stato modificato dopo l'avvio del pagamento, o nel gestore Quickpay è stato acquisito un importo diverso); oppure l'acquisizione non è riuscita e l'importo è ancora solo riservato. La nota dell'ordine lo spiega, anche quando l'ordine era già In attesa.

Failed: il tentativo di pagamento è stato rifiutato. Il cliente può pagare di nuovo.

Cancelled: il cliente ha annullato nella finestra di pagamento, l'ordine è stato annullato da te o dal timeout di riserva scorte di WooCommerce, oppure il pagamento è stato annullato nel gestore Quickpay.

Un pagamento che arriva per un ordine già pagato, annullato o rimborsato non modifica l'ordine. Una nota ti chiede di verificare il pagamento nel gestore Quickpay, per esempio per rimborsare un doppio pagamento.

Acquisizione

Con Authorize only, apri l'ordine, scegli Capture Quickpay payment tra le azioni dell'ordine e fai clic sul pulsante di aggiornamento. Viene acquisito il totale dell'ordine; l'acquisizione parziale non è disponibile. Se Quickpay conferma subito, l'ordine viene segnato come pagato. Altrimenti una nota indica che l'acquisizione è stata richiesta, e l'ordine viene segnato come pagato quando il callback di Quickpay lo conferma. Un'acquisizione rifiutata viene mostrata nella schermata dell'ordine e annotata sull'ordine.

Annullare un ordine autorizzato non rilascia automaticamente l'importo riservato. La nota dell'ordine ti ricorda di annullare il pagamento nel gestore Quickpay; altrimenti la riserva termina alla scadenza dell'autorizzazione.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Quickpay. Sono supportati i rimborsi totali e parziali per i pagamenti acquisiti. Quickpay elabora i rimborsi in modo asincrono: una nota indica che il rimborso è stato richiesto, e il callback aggiunge l'esito finale, confirmed o FAILED con il motivo. Se Quickpay rifiuta subito il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un pagamento autorizzato mai acquisito non può essere rimborsato; annullalo nel gestore Quickpay.

I pagamenti e i rimborsi effettuati direttamente nel gestore Quickpay vengono solo annotati sull'ordine. Non vengono registrati automaticamente come rimborsi WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza Refund via Quickpay.

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 > Quickpay. 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 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, Quickpay 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 collegati vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare 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 acquisizione e rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Quickpay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che siano inserite sia API key sia Private key. Senza entrambe le chiavi il metodo è nascosto.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: il callback di Quickpay non ha raggiunto il negozio o è stato rifiutato. Verifica che il sito sia raggiungibile da internet (senza protezione con password né modalità manutenzione) e che Private key sia la chiave privata dello stesso account Quickpay. I callback rifiutati vengono sempre scritti in WooCommerce > Status > Logs, origine wcp_quickpay_gateway. Attiva Debug log per vedere ogni callback.

Il registro mostra Callback rejected: invalid checksum.: la chiave privata nelle impostazioni non appartiene all'account che ha inviato il callback. Copiala di nuovo da Settings > Integration nel gestore Quickpay.

Il registro mostra Callback rejected: the private key is not configured.: inserisci la chiave privata. I callback non vengono mai accettati senza di essa.

Il registro mostra Callback: no order found for payment …: il callback appartiene a un pagamento Quickpay che nessun ordine di questo negozio conosce, per esempio un pagamento creato fuori da WooCommerce o per un ordine eliminato.

Il registro mostra Callback: order #… is locked by another request.: un altro callback dello stesso ordine era in fase di applicazione in quel momento. Il callback riceve una risposta di errore, quindi non viene considerato gestito. Se l'ordine resta invariato, verifica il pagamento nel gestore Quickpay.

Un pagamento di prova non ha segnato l'ordine come pagato: Test payments è disattivato. La nota dell'ordine indica che il pagamento di prova non è stato accettato. Attiva l'impostazione durante i test, e disattivala quando il tuo account va in produzione.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. Il pagamento potrebbe essere solo autorizzato e in attesa di Capture Quickpay payment, l'importo o la valuta pagati potrebbero differire dall'ordine, oppure l'acquisizione non è riuscita. Acquisisci, evadi l'ordine o rimborsa il pagamento nel gestore Quickpay.

Test API key says Quickpay rejected the API key.: la chiave è errata o appartiene a un utente senza accesso API. Copia la chiave API di un utente API dal gestore Quickpay.

Il cliente vede The Quickpay payment could not be started.: apri le note dell'ordine o il registro. La nota mostra l'errore di Quickpay, per esempio una valuta che il tuo account Quickpay non accetta.

Il rimborso non riesce: l'ordine deve avere un pagamento Quickpay acquisito. Il messaggio The Quickpay payment of this order has not been captured — there is nothing to refund. significa che il pagamento è solo autorizzato; annullalo invece nel gestore Quickpay.

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 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 della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log del plugin (file di log, inclusi quelli ruotati, e voci di log nel database) vengono rimossi solo se Delete data era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

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