VibeFox HyperPay for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

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

PHP: 8.0 o successivo.

Account HyperPay: HyperPay rilascia l'Access Token e l'Entity ID quando viene configurato il tuo account commerciante. Le credenziali di test e quelle live sono diverse. Ti servono inoltre un webhook di pagamento nella dashboard di HyperPay e la sua chiave di decrittazione (chiave webhook), mostrata in Administration > Webhooks (vedi Configurazione).

Dati della carta: la carta viene inserita solo nel widget HyperPay, quindi i dati della carta non arrivano mai al tuo server (PCI DSS SAQ A).

Chiave di licenza VibeFox: acquistata 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. Puoi anche caricare la cartella wcp_hyperpay_payment_gateway in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

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

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

5. Inserisci l'Access Token, l'Entity ID e la chiave webhook di test rilasciati da HyperPay e lascia attivo Test Mode.

6. Nella dashboard di HyperPay (Administration > Webhooks) aggiungi un webhook di pagamento con l'URL mostrato nelle impostazioni e copia la sua chiave di decrittazione nel campo chiave webhook della stessa modalità.

7. Attiva Enable/Disable ed effettua un pagamento di prova con una carta di test HyperPay. Poi inserisci le credenziali live e disattiva Test Mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > HyperPay. Sopra i campi la pagina mostra La modalità test è attiva: i pagamenti vengono inviati al sistema di test di HyperPay e non viene addebitato denaro reale. finché la modalità test è attiva. Avvisa quando mancano l'Access Token o l'Entity ID della modalità corrente (in tal caso il metodo di pagamento non viene mostrato al checkout) e quando la modalità corrente non ha una chiave webhook valida (in tal caso i pagamenti vengono confermati solo quando il cliente torna nel negozio). Nell'elenco dei metodi di pagamento il gateway è contrassegnato come da configurare finché la modalità corrente non ha Access Token ed Entity ID. Al salvataggio gli spazi vengono rimossi dalle credenziali, e la pagina mostra un errore se una chiave webhook non è una chiave esadecimale di 64 caratteri.

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

Title: il titolo che il cliente vede durante il checkout. Predefinito: Credit/Debit Card (HyperPay).

Description: la descrizione che il cliente vede durante il checkout. Predefinito: Pay securely using your credit or debit card.

Credenziali API

Access Token, Entity ID e chiave webhook vengono rilasciati da HyperPay quando viene configurato il tuo account commerciante. Le credenziali di test e quelle live sono diverse. La chiave webhook è mostrata nella dashboard di HyperPay in Administration > Webhooks.

Test Mode: Enable Test Mode usa il sistema di test di HyperPay (eu-test.oppwa.com) e le credenziali di test. Non viene addebitato denaro reale. Disattivalo per accettare pagamenti reali con le credenziali live (eu-prod.oppwa.com). Predefinito: attivo.

Test Access Token: il bearer token del tuo account di test HyperPay.

Test Entity ID: l'Entity ID del canale di pagamento di test.

Test Webhook Key: la chiave esadecimale di 64 caratteri usata per decifrare le notifiche webhook del sistema di test.

Live Access Token: il bearer token del tuo account live HyperPay.

Live Entity ID: l'Entity ID del canale di pagamento live.

Live Webhook Key: la chiave esadecimale di 64 caratteri usata per decifrare le notifiche webhook del sistema live.

Webhook

Il webhook informa il tuo negozio dei pagamenti anche quando il cliente chiude il browser prima di tornare nel negozio. Nella dashboard di HyperPay (Administration > Webhooks) aggiungi un webhook per i pagamenti con l'URL mostrato in questa sezione delle impostazioni. Ha questo formato: https://your-site/wp-json/hyperpay-p/v1/webhook. Poi copia la chiave di decrittazione del webhook in Test Webhook Key o Live Webhook Key, per la stessa modalità.

I webhook HyperPay sono cifrati (AES-256-GCM). Un webhook che non può essere decifrato con le tue chiavi viene rifiutato. Vengono elaborate solo le notifiche di pagamento, e il pagamento deve appartenere a una sessione di pagamento di uno dei tuoi ordini, creata nella stessa modalità della chiave che lo ha decifrato. Le notifiche di test di HyperPay vengono confermate. Il webhook segnala anche acquisizioni, storni, rimborsi e chargeback effettuati nella dashboard di HyperPay (vedi Ordini e rimborsi). Senza webhook, un pagamento viene confermato solo quando il cliente torna nel negozio dopo aver pagato.

Pagamento

Transaction Type: come viene addebitata la carta.

Payment Brands: i marchi mostrati nel widget di pagamento: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Predefinito: VISA e Mastercard. Seleziona solo i marchi che HyperPay ha attivato per il tuo Entity ID; mada, STC Pay e Apple Pay spesso usano un'entità propria, che questo plugin non supporta.

Avanzate

Enable Logging: Log API requests and responses. Le informazioni di debug vengono scritte in WooCommerce > Status > Logs, origine wcp_hyperpay_payment_gateway. Gli errori vengono sempre registrati. I log non contengono dati della carta, chiavi o dati dei clienti. Predefinito: disattivato.

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Rimuove le impostazioni e i file di log quando il plugin viene eliminato. I dati HyperPay salvati negli ordini vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card (HyperPay)) e clicca su Continue to payment. L'ordine viene creato e il cliente passa alla pagina Pay for order. Lì il plugin prepara una sessione di pagamento HyperPay per il totale dell'ordine nella valuta dell'ordine e mostra il widget HyperPay con il messaggio Completa il pagamento qui sotto:. Il widget usa la lingua del tuo sito quando HyperPay la supporta. In modalità test la pagina mostra Modalità test: usa una carta di test HyperPay, non verrà effettuato alcun pagamento reale. Il cliente inserisce i dati della carta nel widget.

Dopo il pagamento, il cliente torna nel tuo negozio. Il plugin verifica che il pagamento appartenga a una delle sessioni di pagamento di questo ordine e chiede a HyperPay il risultato con una richiesta server-to-server. L'ordine viene segnato come pagato solo dopo la conferma di HyperPay: con quella richiesta o con il webhook. Importo e valuta devono corrispondere all'ordine. Un ritorno e un webhook arrivati nello stesso momento vengono gestiti uno dopo l'altro, quindi l'ordine non viene mai elaborato due volte. Quando il pagamento è confermato, il cliente arriva alla pagina di ordine ricevuto.

Se il pagamento non è andato a buon fine, il cliente torna alla pagina Pay for order con un messaggio: Pagamento non riuscito: e il motivo comunicato da HyperPay, Il pagamento non è stato completato. Riprova., oppure Non siamo ancora riusciti a confermare il tuo pagamento. Se ti è stato addebitato l'importo, l'ordine verrà aggiornato automaticamente; in caso contrario, riprova. Il cliente può pagare di nuovo nella stessa pagina. Se il widget non può essere preparato, il cliente vede un breve messaggio, per esempio che alcuni dati di fatturazione non sono stati accettati dal fornitore di pagamento, e un pulsante Try Again. I dettagli vengono aggiunti alle note dell'ordine.

Gli importi vengono inviati con due decimali, come richiede l'API di HyperPay. Nelle valute a 3 decimali (KWD, BHD, JOD, OMR) il totale dell'ordine viene arrotondato a due decimali.

Il metodo di pagamento funziona nel checkout classico, nei blocchi Carrello e Checkout e nella pagina Pay for order. In modalità test il blocco Checkout mostra Modalità test: non verrà effettuato alcun pagamento reale. È compatibile con l'archiviazione ad alte prestazioni degli ordini di WooCommerce (HPOS).

Il plugin non prevede rimborsi o annullamenti da WooCommerce, carte salvate o tokenizzazione, abbonamenti, verifica del dominio per Apple Pay, un'entità separata per ogni marchio né Tabby, Tamara o altri metodi buy-now-pay-later.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente non ha ancora pagato, non ha completato il widget oppure HyperPay non ha ancora confermato il pagamento.

Processing: un pagamento con addebito è stato confermato, oppure una pre-autorizzazione è stata acquisita. Gli ordini con solo prodotti scaricabili virtuali diventano Completato, il comportamento predefinito di WooCommerce. La nota dell'ordine mostra il codice di esito di HyperPay, la descrizione e l'ID di pagamento. L'ID transazione è l'ID di pagamento HyperPay. Se HyperPay ha segnalato il pagamento per una verifica manuale, la nota lo indica; controllalo nella dashboard di HyperPay prima della spedizione.

On hold (pre-authorization): l'importo è stato riservato. Acquisiscilo con l'azione sull'ordine Capture HyperPay payment o nella dashboard di HyperPay; il webhook di acquisizione completa poi l'ordine.

On hold after payment: HyperPay ha segnalato un importo o una valuta diversi da quelli dell'ordine (per esempio perché l'ordine è stato modificato dopo l'apertura della pagina di pagamento), il pagamento è ancora in sospeso presso HyperPay oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota dell'ordine lo spiega. Controlla il pagamento nella dashboard di HyperPay e completalo o rimborsalo.

Failed: HyperPay ha rifiutato il pagamento. Il motivo è nella nota dell'ordine e viene mostrato al cliente. Tentativo rifiutato: non modifica mai un ordine già pagato, riservato, in attesa o annullato.

Cancelled: una pre-autorizzazione è stata annullata nella dashboard di HyperPay, e il webhook di annullamento annulla l'ordine In attesa.

Se arriva un altro pagamento riuscito per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nella dashboard di HyperPay. Un pagamento riuscito per un ordine rimborsato aggiunge solo una nota.

Acquisizione

L'azione sull'ordine Capture HyperPay payment compare sugli ordini In attesa con una pre-autorizzazione non ancora acquisita. Acquisisce il totale attuale dell'ordine, meno i rimborsi già registrati in WooCommerce, nella modalità in cui è stata effettuata la pre-autorizzazione. Dopo un'acquisizione riuscita, l'ordine diventa In lavorazione. Se HyperPay rifiuta l'acquisizione, vengono mostrati il codice di esito e la descrizione e vengono aggiunti alle note dell'ordine. L'annullamento (void) di una pre-autorizzazione si esegue nella dashboard di HyperPay.

Rimborsi

I rimborsi da WooCommerce non sono supportati. Rimborsa il pagamento nella dashboard di HyperPay e registralo in WooCommerce con Refund manually. I rimborsi e i chargeback effettuati in HyperPay vengono aggiunti all'ordine come nota dal webhook; 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 > HyperPay. 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 posto del suo dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, HyperPay non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. Gli amministratori del negozio connessi vedono comunque il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così possono 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 le acquisizioni funzionano.

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

HyperPay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia Access Token ed Entity ID: quelli di test in modalità test, quelli live in modalità live. La pagina delle impostazioni mostra un avviso quando mancano.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: il webhook non funziona e il cliente non è tornato nel negozio. Nella dashboard di HyperPay verifica che il webhook di pagamento esista per la modalità che usi, che il suo URL sia esattamente quello mostrato nelle impostazioni e che la sua chiave di decrittazione sia nel campo chiave webhook della stessa modalità. Controlla WooCommerce > Status > Logs, origine wcp_hyperpay_payment_gateway.

Il webhook risponde Decryption failed: la chiave webhook appartiene a un altro webhook o a un'altra modalità. Copia di nuovo la chiave dalla dashboard di HyperPay.

Il webhook risponde Webhook key not configured: non è impostata una chiave webhook valida. Incolla la chiave di 64 caratteri nelle impostazioni. HyperPay riprova il webhook.

Il log mostra Webhook ignored: il pagamento non appartiene a un ordine di questo negozio, oppure è stato effettuato nell'altra modalità. I pagamenti di test e quelli live restano separati.

Il modulo di pagamento non si carica: leggi la nota dell'ordine. Un errore di configurazione di solito indica un Access Token o un Entity ID errati per la modalità corrente. Un messaggio sui dati di fatturazione significa che HyperPay non ha accettato alcuni dati del cliente. Assicurati che i Payment Brands selezionati siano attivi per il tuo Entity ID.

L'ordine è On hold con una nota di mancata corrispondenza di importo o valuta: HyperPay ha segnalato un pagamento che non corrisponde al totale o alla valuta dell'ordine, per esempio perché l'ordine è stato modificato dopo l'apertura della pagina di pagamento. Controlla il pagamento nella dashboard di HyperPay e completalo o rimborsalo.

L'acquisizione non riesce: leggi il codice di esito e la descrizione nella nota dell'ordine. L'acquisizione viene inviata nella modalità della pre-autorizzazione, quindi le credenziali di quella modalità devono essere impostate.

Il blocco licenza mostra un errore: segui il messaggio del blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca 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.

Per gli sviluppatori: il filtro hyperpay_p_icon cambia l'icona del metodo di pagamento.

Disinstallazione

Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, i dati temporanei del plugin e i file di log vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una futura reinstallazione. I dati HyperPay salvati negli ordini vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID di transazione.

HyperPay è un marchio registrato del suo titolare. Questo plugin non è affiliato né approvato da HyperPay.