VibeFox HyperPay for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione OpenSSL (decrittra i webhook). Senza di essa il modulo non può essere installato.

Account HyperPay: HyperPay rilascia Access Token ed Entity ID quando viene configurato il tuo account commerciante. Le credenziali di test e quelle live sono diverse. Ti serve inoltre un webhook di pagamento nella dashboard di HyperPay e la sua chiave di decrittazione (webhook key), 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. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox HyperPay Payment Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

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

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

6. Attiva Enable/Disable, fai clic su Save ed esegui un pagamento di prova con una carta di test di HyperPay. Poi inserisci le credenziali live e disattiva Test Mode.

All'installazione il modulo crea tre stati dell'ordine: Awaiting HyperPay payment, HyperPay payment authorized e HyperPay payment on hold. PrestaShop collega un nuovo modulo di pagamento alle valute, ai paesi e ai gruppi di clienti attivi in quel momento. I paesi che attivi più tardi devono essere consentiti in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode is on: payments go to the HyperPay test system and no real money is charged. finché la modalità test è attiva. Ti avvisa se mancano Access Token o Entity ID della modalità corrente (in questo caso il metodo di pagamento non viene mostrato nel checkout) e se la modalità corrente non ha una chiave webhook valida (in questo caso i pagamenti vengono confermati solo quando il cliente torna nel negozio). Al salvataggio vengono rimossi gli spazi dalle credenziali, e la pagina avvisa se una chiave webhook non è una chiave esadecimale di 64 caratteri.

HyperPay

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

Title: il titolo che il cliente vede durante il checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit/Debit Card (HyperPay). Obbligatorio.

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: 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. Finché è attivo, i clienti vedono Test mode: no real payment will be made. sotto il metodo di pagamento.

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

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

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

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

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

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

Gli access token e le chiavi webhook salvati non vengono più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Cancellare i segreti salvati: seleziona un token o una chiave e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

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 Webhook URL in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_hyperpay_payment_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni. Copia poi la chiave di decrittazione del webhook in Test Webhook Key o Live Webhook Key, per la stessa modalità.

I webhook di HyperPay sono cifrati (AES-256-GCM). Un webhook che non può essere decrittato 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 carrelli, creata nella stessa modalità della chiave che lo ha decrittato. 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 il webhook, un pagamento viene confermato solo quando il cliente torna nel negozio dopo aver pagato.

Payment

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. Se non è selezionato nessun marchio, la pagina avvisa e il widget mostra VISA e Mastercard. Seleziona solo i marchi che HyperPay ha abilitato per il tuo Entity ID; mada, STC Pay e Apple Pay spesso usano un'entità propria, che questo modulo non supporta.

Advanced

Enable Logging: registra richieste e risposte API in logs/hyperpay_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. I log non contengono dati della carta, chiavi o dati dei clienti. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro. Fai clic su Clear log per svuotarlo.

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni, la tabella dei tentativi di pagamento HyperPay e i file di log. Ordini e stati dell'ordine del modulo vengono conservati. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card (HyperPay)) e conferma l'ordine. Il modulo prepara una sessione di pagamento HyperPay per il totale del carrello nella valuta del carrello e apre la pagina HyperPay payment del negozio con il widget HyperPay e il messaggio Please complete your payment below:. Il widget usa la lingua del cliente quando HyperPay la supporta. In modalità test la pagina mostra Test mode: use a HyperPay test card, no real payment will be made. Il cliente inserisce i dati della carta nel widget, oppure segue Choose another payment method per tornare al checkout. In questo momento l'ordine non esiste ancora. Ricaricando la pagina viene riutilizzata la stessa sessione di pagamento per un massimo di 25 minuti, finché il carrello non cambia.

Dopo il pagamento, il cliente torna nel tuo negozio. Il modulo verifica che il pagamento appartenga a una sessione di pagamento di questo carrello e chiede a HyperPay il risultato con una richiesta server-to-server, nella modalità in cui è stata creata la sessione. L'ordine viene segnato come pagato solo quando HyperPay lo conferma: con quella richiesta o con il webhook. Importo e valuta devono corrispondere al carrello. Se il ritorno e un webhook arrivano nello stesso momento, vengono elaborati uno dopo l'altro, quindi l'ordine non viene mai creato due volte. Quando il pagamento è confermato, l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine.

Se il pagamento non è andato a buon fine, il cliente torna al checkout con un messaggio: Payment failed: e il motivo fornito da HyperPay, Payment was not completed. Please try again., oppure We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Il carrello viene conservato e il cliente può pagare di nuovo; ogni nuovo tentativo riceve una nuova sessione di pagamento HyperPay. Se il modulo di pagamento non può essere preparato, il cliente resta nel checkout con un breve messaggio, ad esempio che alcuni dati di fatturazione non sono stati accettati dal fornitore di pagamento, oppure che il modulo di pagamento non è disponibile a causa di un errore di configurazione. Il motivo tecnico viene scritto nel log.

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

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

Il modulo non prevede rimborsi o annullamenti da PrestaShop, 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

No order yet: il cliente è stato inviato alla pagina di pagamento e non ha pagato, il pagamento è stato rifiutato, oppure HyperPay non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: è stato confermato un pagamento con addebito o è stata acquisita una pre-autorizzazione. Il pagamento viene registrato con l'ID del pagamento HyperPay come ID della transazione, e una nota privata mostra il codice di esito di HyperPay, la descrizione e l'ID del pagamento. Se HyperPay ha segnalato il pagamento per una verifica manuale, la nota lo indica; verificalo nella dashboard di HyperPay prima della spedizione.

HyperPay payment authorized: l'importo è stato riservato da una pre-autorizzazione. Acquisiscilo nel blocco HyperPay dell'ordine o nella dashboard di HyperPay; il webhook di acquisizione sposta poi l'ordine in Payment accepted.

Awaiting HyperPay payment: HyperPay ha segnalato il pagamento come in sospeso. L'ordine passa in Payment accepted quando HyperPay lo conferma.

HyperPay payment on hold: HyperPay ha segnalato un importo o una valuta diversi da quelli del carrello o dell'ordine (ad esempio, il carrello è stato modificato dopo l'apertura della pagina di pagamento), oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota lo spiega. Verifica il pagamento nella dashboard di HyperPay, poi evadi l'ordine oppure rimborsa il pagamento.

Canceled: una pre-autorizzazione è stata stornata nella dashboard di HyperPay, e il webhook di storno annulla l'ordine autorizzato.

Un esito di rifiuto non modifica mai un ordine esistente. 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.

Blocco di pagamento HyperPay

La pagina dell'ordine mostra un blocco HyperPay payment con l'ID del pagamento (e l'ID dell'acquisizione dopo un'acquisizione), il tipo di transazione, l'ID della sessione di pagamento, l'ID della transazione del commerciante, l'importo inviato a HyperPay, l'esito e un badge Test mode per i pagamenti di test. Le note del modulo si trovano nei messaggi privati dell'ordine.

Acquisizione

Per un ordine in HyperPay payment authorized il blocco mostra Capture payment con l'importo. Fai clic e conferma Capture the pre-authorized amount through HyperPay?. Viene acquisito il totale attuale dell'ordine, nella modalità in cui è stata fatta la pre-autorizzazione, quindi devono essere impostati Access Token ed Entity ID di quella modalità. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine del modulo. Dopo un'acquisizione riuscita l'ordine passa in Payment accepted e l'ID dell'acquisizione viene aggiunto al pagamento e alle note. Se HyperPay rifiuta l'acquisizione, vengono mostrati il codice di esito e la descrizione, aggiunti alle note, e l'ordine resta autorizzato. Un doppio clic non acquisisce due volte. Lo storno (void) di una pre-autorizzazione si fa nella dashboard di HyperPay.

Rimborsi

I rimborsi da PrestaShop non sono supportati, e i pulsanti di rimborso standard di PrestaShop non restituiscono denaro tramite HyperPay. Rimborsa il pagamento nella dashboard di HyperPay e registralo in PrestaShop con un rimborso parziale o una nota di credito, se necessario. 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 modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox HyperPay Payment Gateway è il primo blocco in Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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. Più sotto si trovano la riga Product: presta-payment-hyperpay 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 cambiare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e 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 aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, fai clic 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 suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, HyperPay non viene mostrato ai clienti nel 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 è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo nel checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati, e acquisizioni e rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 alcun cron job. Disinstallando o reimpostando il modulo, vengono sempre rimossi la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

HyperPay non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia il proprio Access Token e Entity ID: quelli di test in modalità test, quelli live in modalità live. La pagina delle impostazioni mostra un avviso se mancano. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, 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 e il cliente non è tornato nel negozio. Nella dashboard di HyperPay verifica che esista il webhook di pagamento per la modalità che usi, che il suo URL sia esattamente quello mostrato in Webhook URL e che la sua chiave di decrittazione sia nel campo della chiave webhook della stessa modalità. Attiva Enable Logging e controlla il campo Log nella pagina del modulo.

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 ripete il webhook.

Il webhook risponde Busy, retry later: l'ordine era in elaborazione da un'altra richiesta nello stesso momento, oppure l'ordine non può essere creato (ad esempio perché il modulo è disattivato). HyperPay ripete il webhook. Il motivo è nel log.

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

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste POST da HyperPay.

Il modulo di pagamento non si carica: controlla il log. 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 abilitati per il tuo Entity ID.

L'ordine è in HyperPay payment on hold: leggi le note dell'ordine (vedi Stati dell'ordine), verifica il pagamento nella dashboard di HyperPay, poi evadi l'ordine oppure rimborsa il pagamento.

L'acquisizione non va a buon fine: leggi il codice di esito e la descrizione nel blocco e nelle note. L'acquisizione viene inviata nella modalità della pre-autorizzazione, quindi le credenziali di quella modalità devono essere impostate; altrimenti il blocco segnala che Access Token / Entity ID di quella modalità sono vuoti.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox HyperPay Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni, la tabella dei tentativi di pagamento HyperPay e i file di log. Se è disattivato, tutto viene conservato per una reinstallazione successiva. Gli stati dell'ordine Awaiting HyperPay payment, HyperPay payment authorized e HyperPay payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le loro note di pagamento e gli ID delle transazioni.

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