VibeFox Tap 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: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR o USD. Per i carrelli in altre valute il metodo di pagamento non viene mostrato nel checkout.

Accesso a Internet al tuo negozio: Tap invia il risultato del pagamento a un webhook del tuo negozio, quindi il sito deve essere raggiungibile da Internet. L'URL del webhook viene inviato con ogni pagamento; non serve configurare nulla nella dashboard di Tap.

Account Tap: ti servono le chiavi API dalla tua dashboard Tap (goSell, credenziali API). Le chiavi di test iniziano con pk_test_ / sk_test_, quelle live con pk_live_ / sk_live_. La chiave segreta è sempre necessaria; la chiave pubblicabile solo per il popup. I metodi di pagamento offerti (mada, KNET, Benefit e altri) e la verifica del dominio per Apple Pay si configurano nel tuo account Tap.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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 VibeFox Tap Payments più tardi nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in alto nella pagina Configure, e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci le chiavi Tap di test e live, scegli l'azione di pagamento, il tipo di checkout e la lingua della pagina Tap (vedi Configurazione).

5. Attiva Enable / Disable e fai clic su Save. Prova con le carte di test Tap, poi disattiva Test mode.

All'installazione il modulo crea due stati dell'ordine, Tap payment authorized e Tap payment on hold. PrestaShop attiva un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Tap Payments > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode is on: payments use your Tap test keys and no real money is charged. oppure Live mode: real payments are accepted. Avvisa inoltre quando mancano le chiavi della modalità attuale (il metodo di pagamento non viene quindi mostrato nel checkout) e quando la valuta predefinita del negozio non è offerta con Tap.

Al salvataggio, una chiave con un prefisso sbagliato per il suo campo non viene salvata: resta il valore precedente, le altre impostazioni vengono salvate e compare un messaggio come Test secret key was not saved: a Tap key for this field starts with "sk_test_".. Per esempio, una chiave live in un campo di test viene rifiutata. Un Title vuoto non è accettato: la pagina mostra Enter a title for the payment method. e non salva nulla.

Tap Payments

Il titolo della sezione mostra anche TEST o LIVE per la modalità attuale.

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

Title: il nome del metodo di pagamento mostrato nel checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Tap Payments. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Chiavi API Tap

Trovi le chiavi nella dashboard Tap (goSell, credenziali API). Le chiavi di test iniziano con pk_test_ / sk_test_, quelle live con pk_live_ / sk_live_.

Test mode: usa le chiavi di test; non viene addebitato denaro reale. Pagamenti, verifiche di stato, acquisizioni e rimborsi usano sempre le chiavi della modalità in cui è stato effettuato il pagamento: un pagamento di test viene quindi ancora verificato e rimborsato con la chiave di test anche dopo il passaggio al live. Predefinito: attivo. Finché è attivo, i clienti vedono Test mode: no real payment will be made. sotto il metodo di pagamento.

Test publishable key: inizia con pk_test_. Necessaria per il popup.

Test secret key: inizia con sk_test_.

Live publishable key: inizia con pk_live_. Necessaria per il popup.

Live secret key: inizia con sk_live_.

Merchant ID: facoltativo. Il tuo ID merchant Tap; serve solo se Tap ti ha chiesto di instradare i pagamenti verso un account merchant specifico.

Le chiavi segrete salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiare la chiave. Le chiavi pubblicabili sono pubbliche e restano visibili.

Clear saved secrets: seleziona una chiave segreta e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Pagamento

Payment action: cosa succede al denaro quando il cliente paga.

Checkout type: dove paga il cliente.

Tap page language: English (predefinito) oppure Arabic.

Notifiche di pagamento (webhook)

Tap invia il risultato del pagamento all'URL mostrato in Webhook URL in questa sezione. Con URL SEO-friendly ha questo aspetto: https://your-shop/module/wcp_tap_payment_gateway/webhook, eventualmente con un codice lingua come /en/. L'URL viene inviato con ogni pagamento, quindi non serve configurare nulla nella dashboard di Tap. Assicurati solo che sia raggiungibile da Internet (non bloccato da un firewall o da un'autenticazione HTTP). Ogni notifica viene verificata con la firma hashstring (HMAC-SHA256 con la chiave segreta della modalità in cui è stato effettuato il pagamento). I webhook senza una firma valida vengono rifiutati. Anche una notifica firmata non è considerata affidabile di per sé: il modulo rilegge il pagamento dall'API di Tap prima di creare o modificare l'ordine. Senza un webhook funzionante, l'ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Avanzate

Debug log: registra gli eventi di pagamento in logs/tap_p_debug.log.php nella cartella del modulo. Il file non può essere letto dal web. Errori e avvisi vengono sempre registrati; attiva questa opzione per registrare anche ogni evento di pagamento. Il registro non contiene mai chiavi, dati della carta o 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 del gateway e il registro. I record di pagamento degli ordini vengono conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Tap Payments) e conferma l'ordine. A questo punto l'ordine non esiste ancora.

Tap payment page: il modulo crea un addebito Tap (oppure un'autorizzazione in modalità Authorize only) per il totale del carrello nella valuta del carrello, con la descrizione Cart # e il numero del carrello, e invia il cliente alla pagina di pagamento Tap. Nome, e-mail e telefono del cliente vengono passati a Tap. Lì il cliente sceglie una carta, mada, KNET, Benefit, Apple Pay o Google Pay (come attivati nel tuo account Tap) e paga. Se Tap non riesce ad avviare il pagamento, il cliente resta nel checkout con The Tap payment could not be started. Please try again or choose another payment method. e il motivo viene scritto nel registro.

Tap checkout popup: il cliente va alla pagina Tap payment del modulo, dove si apre il modulo di pagamento Tap. La pagina mostra anche il link Pay on the Tap payment page instead. Se la finestra viene chiusa, il pulsante Pay now la riapre. Se il modulo non può essere caricato, al cliente viene chiesto di usare la pagina di pagamento Tap. Ricaricare la pagina riutilizza lo stesso tentativo di pagamento.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Tap lo conferma: il modulo legge il pagamento dall'API di Tap con la chiave della modalità del pagamento, verifica che si riferisca a questo carrello e che sia stato avviato dal suo checkout, e confronta importo e valuta con quelli del carrello. L'ID Tap nell'indirizzo di ritorno da solo non crea mai un ordine. Il webhook esegue la stessa verifica in background. L'ordine viene poi creato e il cliente vede la pagina standard di conferma dell'ordine. Per un pagamento autorizzato la pagina mostra Your payment has been authorized. We will process the order as soon as the payment is captured.; per un ordine in attesa mostra Your payment is being reviewed. We will contact you if anything else is needed.

Se Tap non ha ancora confermato il pagamento quando il cliente torna, compare una pagina Payment confirmation con We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. e i pulsanti Check again e Back to checkout. Il webhook crea l'ordine appena arriva.

Se il pagamento è stato rifiutato, abbandonato o annullato, non viene creato alcun ordine. Il cliente torna al checkout con Your payment was not completed. Please try again or choose another payment method. (con il motivo di Tap quando Tap ne fornisce uno). Un pagamento incompleto mostra The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato e può essere pagato di nuovo.

Altri messaggi nel checkout: Tap does not accept payments in, seguito dalla valuta, quando la valuta del carrello non è supportata, e The order total must be greater than zero to pay with Tap.

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

Il modulo non prevede carte salvate né tokenizzazione, abbonamenti o campi per la carta incorporati nel checkout. Capture Tap payment acquisisce sempre il totale dell'ordine; l'acquisizione parziale non è supportata.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Tap e non ha pagato, oppure Tap non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: Tap ha confermato un pagamento acquisito. Il pagamento viene registrato con l'ID dell'addebito Tap (chg_...) come ID transazione, e una nota mostra l'importo, l'ID dell'addebito, il metodo di pagamento e, in modalità test, che si tratta di un pagamento di test.

Tap payment authorized: il pagamento è stato solo autorizzato e attende acquisizione o annullamento.

Tap payment on hold: l'importo o la valuta pagati non corrispondevano al carrello (Tap: amount/currency mismatch — manual review required.), oppure un pagamento è arrivato dopo che l'ordine era stato annullato. La nota lo spiega. Controlla l'ordine ed evadilo, oppure rimborsa il pagamento.

Canceled: l'autorizzazione è stata annullata con Void Tap authorization, quindi i fondi riservati sono stati rilasciati.

Refunded: il pagamento è stato rimborsato integralmente tramite il modulo.

Un tentativo fallito non modifica mai un ordine pagato, autorizzato o annullato. Se arriva un secondo pagamento riuscito per un ordine già pagato, l'ordine non viene modificato. Una nota segnala che si tratta di un pagamento duplicato e chiede di rimborsarlo nella dashboard di Tap. Un pagamento che si riferisce al carrello ma non è stato avviato dal suo checkout viene solo annotato.

Blocco di pagamento Tap

La pagina dell'ordine mostra un blocco Tap payment con l'ID Tap, l'autorizzazione e l'addebito, la modalità (un badge Test mode per i pagamenti di test), lo stato e il metodo di pagamento, Charged / refunded, lo storico dei rimborsi, i tentativi di pagamento del carrello e le Payment notes dell'ordine. I pulsanti del blocco funzionano nella pagina stessa dell'ordine; serve il permesso di modificare gli ordini, non l'accesso alle impostazioni del modulo.

Acquisizione e annullamento

In modalità Authorize only, apri l'ordine nello stato Tap payment authorized. Capture Tap payment (con il totale dell'ordine sul pulsante) acquisisce il totale dell'ordine dopo la domanda Capture the reserved funds of this order through Tap?; l'ordine passa quindi a Payment accepted. Void Tap authorization chiede Release the reserved funds? The order will be canceled., rilascia i fondi e imposta l'ordine su Canceled. Se Tap rifiuta l'azione, nel blocco compare un errore che viene aggiunto alle note. Se un'autorizzazione viene acquisita direttamente nella dashboard di Tap, il webhook segna l'ordine come pagato; i rimborsi di questo pagamento vanno effettuati nella dashboard di Tap.

Rimborsi

Nel blocco Tap payment inserisci l'importo (viene riempito l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Tap. Conferma la domanda Refund this amount through Tap? This cannot be undone. Sono supportati rimborsi totali e parziali per gli addebiti Tap acquisiti. Puoi rimborsare fino all'importo e alla valuta che Tap ha effettivamente addebitato, anche se l'ordine è stato modificato in seguito. Il rimborso viene inviato con la chiave segreta della modalità in cui è stato effettuato il pagamento, quindi quella chiave deve essere impostata. Un rimborso accettato da Tap viene aggiunto allo storico dei rimborsi e alle note con l'ID e lo stato del rimborso Tap. Se Tap lo rifiuta, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato. Per un ordine autorizzato i rimborsi sono disponibili dopo l'acquisizione dell'autorizzazione. Un ordine in attesa dopo una differenza di importo o di valuta viene rimborsato nella dashboard di Tap.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Tap. I rimborsi effettuati nella dashboard di Tap non compaiono in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Tap Payments è il primo blocco di Modules > Module Manager > VibeFox Tap Payments > Configure, sopra le impostazioni. Incolla 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 verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto di essi si trovano la riga Product: presta-payment-tap 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 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 oppure 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 relativo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Tap Payments 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. La vetrina di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene 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 rimborsi, acquisizione e annullamento continuano a funzionare.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta a settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Tap Payments non compare nel checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità attuale abbia una chiave segreta (e una chiave pubblicabile quando Checkout type è il popup). Verifica che la valuta del carrello sia una tra AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. La pagina delle impostazioni mostra un avviso per le chiavi mancanti e per una valuta del negozio non supportata.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il webhook non riesce a raggiungere il tuo negozio. Verifica che l'URL mostrato in Webhook URL sia raggiungibile da Internet (senza firewall o autenticazione HTTP) e attiva Debug log per vedere le risposte nel campo Log. L'ordine viene creato anche quando il cliente torna da Tap.

Webhook answers invalid signature: la notifica non è stata firmata con la chiave segreta della modalità del pagamento. Controlla le chiavi segrete nelle impostazioni.

Webhook answers gateway not configured: la chiave segreta della modalità del pagamento (test o live) è vuota. Inseriscila.

Webhook answers verification failed: non è stato possibile raggiungere l'API di Tap per verificare il pagamento. Tap riprova il webhook più tardi.

Webhook answers order not found: la notifica indica un carrello che non ha alcun tentativo di pagamento Tap in questo negozio.

Webhook answers busy, retry later or order could not be updated, retry later: l'ordine era in conferma da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). Tap riprova il webhook. Controlla il campo Log per il motivo.

Una chiave non viene salvata: la chiave deve iniziare con il prefisso del suo campo: pk_test_, sk_test_, pk_live_ o sk_live_.

Il cliente vede The Tap payment could not be started: controlla il campo Log nella pagina del modulo. Vi vengono registrate una chiave errata o una richiesta rifiutata.

Il cliente vede We could not match this payment to an order: il pagamento non appartiene a questo carrello o non è stato avviato dal suo checkout. Se il denaro è stato addebitato, verifica il pagamento nella dashboard di Tap.

L'ordine è Tap payment on hold: leggi le note nel blocco Tap payment. L'importo o la valuta pagati non corrispondevano al carrello, oppure il pagamento è arrivato dopo che l'ordine era stato annullato.

Il rimborso fallisce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live e per quella modalità non è impostata alcuna chiave segreta. Inseriscila e riprova. Se il blocco indica che non è stato trovato alcun addebito Tap acquisito, rimborsa il pagamento nella dashboard di Tap.

Hook per sviluppatori: gli hook actionWcpTapChargePayload, actionWcpTapSupportedCurrencies e actionWcpTapCurrencyDecimals permettono a uno sviluppatore di modificare la richiesta di pagamento, le valute supportate e i decimali delle valute.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Tap Payments 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 del gateway e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I tentativi di pagamento e i rimborsi Tap e gli stati dell'ordine Tap payment authorized e Tap payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID di transazione.

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