VibeFox Tap 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.

Valuta del negozio: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR o USD. Per le altre valute il metodo di pagamento viene nascosto nel checkout.

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

Account Tap: ti servono le chiavi API dalla 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 di Tap Checkout. 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 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_tap_payment_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Tap Payments > 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. 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).

6. Attiva Enable / Disable e salva. Prova con le carte di test Tap, poi deseleziona Test mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Tap Payments. Sopra i campi la pagina mostra Test mode is on: payments use your Tap test keys and no real money is charged. finché la modalità test è attiva. Indica anche quando mancano le chiavi della modalità corrente (il gateway non viene quindi mostrato nel checkout) e quando la valuta del negozio non è supportata da Tap. Nell'elenco dei metodi di pagamento, Tap Payments risulta da configurare finché la modalità corrente non ha una chiave segreta (e, per il popup, una chiave pubblicabile).

Al salvataggio, una chiave con un prefisso errato per il suo campo non viene salvata: appare un errore e resta il valore precedente. Ad esempio, una chiave live in un campo di test viene rifiutata.

Generale

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

Title: il nome del metodo di pagamento mostrato nel checkout. Predefinito: Tap Payments.

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

Trova 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: Use the test keys (no real money is charged). Pagamenti, verifiche di stato e rimborsi usano sempre le chiavi della modalità in cui è stato effettuato il pagamento: un pagamento di test continua quindi a essere verificato e rimborsato con la chiave di test anche dopo il passaggio a live. Predefinito: attivo.

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: opzionale. Il tuo ID merchant Tap; serve solo se Tap ti ha chiesto di instradare i pagamenti verso uno specifico account merchant.

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 questa sezione. Ha questo formato: https://your-site/wc-api/tap_p_webhook/. L'URL viene inviato con ogni pagamento, quindi non c'è nulla da configurare nella dashboard di Tap. Assicurati solo che sia raggiungibile da Internet (non bloccato da un firewall, dalla modalità manutenzione o da un'autenticazione HTTP). Ogni notifica viene verificata con la firma hashstring (HMAC-SHA256 con la chiave segreta della modalità del pagamento). I webhook senza una firma valida vengono rifiutati. Anche una notifica firmata non è considerata affidabile di per sé: il plugin rilegge il pagamento dall'API di Tap prima di modificare l'ordine. Senza un webhook funzionante, l'ordine viene aggiornato solo quando il cliente torna nel negozio dopo aver pagato.

Avanzate

Debug log: Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway"). Gli errori vengono sempre registrati. Il registro non contiene mai chiavi, dati della carta o dei clienti. Predefinito: disattivato.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment records are kept). Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Tap Payments) e effettua l'ordine. In modalità test il checkout mostra Test mode: no real payment will be made.

Tap payment page: il plugin crea un addebito Tap (oppure un'autorizzazione in modalità Authorize only) per il totale dell'ordine nella valuta dell'ordine, con la descrizione Order # e il numero dell'ordine, e invia il cliente alla pagina di pagamento Tap. Lì il cliente sceglie una carta, mada, KNET, Benefit, Apple Pay o Google Pay (in base a quanto attivato nel tuo account Tap) e paga. Se Tap non riesce ad avviare il pagamento, il cliente vede The Tap payment could not be started. Please try again or choose another payment method. e il motivo viene aggiunto alle note dell'ordine.

Tap checkout popup: il cliente va alla pagina di pagamento dell'ordine, 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.

Dopo il pagamento, il cliente torna alla pagina di conferma dell'ordine. L'ordine viene segnato come pagato solo quando Tap lo conferma: il plugin rilegge il pagamento dall'API di Tap con la chiave della modalità del pagamento, verifica che si riferisca a questo ordine e sia stato avviato dal suo checkout, e confronta importo e valuta con quelli dell'ordine. Il solo ID Tap nell'indirizzo di ritorno non segna mai un ordine come pagato. Il webhook esegue la stessa verifica in background. Webhook ripetuti e ritorni non modificano mai un ordine due volte (una modifica alla volta per ordine).

Se il pagamento non è ancora confermato, la pagina di conferma mostra 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. Per un pagamento autorizzato mostra Your payment has been authorized. We will process the order as soon as the payment is captured.

Se il pagamento è stato rifiutato o abbandonato, l'ordine viene segnato come Non riuscito e il cliente torna alla pagina Pay for order con il messaggio Your payment was not completed. Please try again or choose another payment method. (con il motivo indicato da Tap, quando lo fornisce). Un pagamento non concluso mostra The payment was not completed. You can try again below. Il cliente può pagare di nuovo l'ordine da quella pagina.

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

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

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Tap e non ha ancora pagato, oppure Tap non ha ancora confermato il pagamento.

Processing: Tap ha confermato un pagamento acquisito. È lo stato standard di WooCommerce dopo il pagamento (gli ordini con soli prodotti scaricabili virtuali passano a Completato). La nota dell'ordine mostra l'importo, l'ID dell'addebito Tap (chg_...), il metodo di pagamento e (in modalità test) l'indicazione che si tratta di un pagamento di test. L'ID transazione è l'ID dell'addebito Tap.

On hold: il pagamento è stato solo autorizzato e attende l'acquisizione; oppure l'importo o la valuta pagati non corrispondevano all'ordine (Tap: amount/currency mismatch — manual review required.); oppure un pagamento è arrivato dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega.

Failed: il pagamento è stato rifiutato, abbandonato, annullato o è scaduto. Solo un ordine che attende ancora il pagamento viene segnato come Non riuscito; un tentativo fallito non modifica mai un ordine pagato, autorizzato o annullato. Il cliente può pagare di nuovo.

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

Se arriva un secondo pagamento riuscito per un ordine già pagato, l'ordine non viene modificato di nuovo. Una nota indica che si tratta di un pagamento duplicato e chiede di rimborsarlo nella dashboard di Tap. Un pagamento che si riferisce all'ordine ma non è stato avviato dal suo checkout viene solo annotato.

Acquisizione e annullamento

In modalità Authorize only, apri l'ordine in attesa e scegli in Order actions: Capture Tap payment acquisisce il totale dell'ordine; l'ordine diventa poi pagato. Void Tap authorization rilascia i fondi e annulla l'ordine. Se Tap rifiuta l'azione, viene mostrato un errore e aggiunto alle note dell'ordine. Se un'autorizzazione viene acquisita direttamente nella dashboard di Tap, il webhook segna l'ordine come pagato; i rimborsi per un pagamento di questo tipo devono essere effettuati nella dashboard di Tap.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Tap Payments (il pulsante mostra il tuo Title). Sono supportati rimborsi totali e parziali per addebiti Tap acquisiti. 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 alle note dell'ordine con l'ID e lo stato del rimborso Tap. Se Tap lo rifiuta, WooCommerce mostra l'errore e non viene registrato alcun rimborso. I rimborsi effettuati nella dashboard di Tap non compaiono in WooCommerce.

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 > Tap Payments. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per controllare 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 lo slot del dominio. Libera lo slot 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. Gli amministratori del negozio che hanno effettuato l'accesso 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 rimborsi, acquisizione e annullamento funzionano.

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

Risoluzione dei problemi

Tap Payments non compare nel checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità corrente abbia una chiave segreta (e una chiave pubblicabile quando Checkout type è il popup). Verifica che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia una tra AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: il webhook non riesce a raggiungere il tuo sito. Verifica che l'URL mostrato nelle impostazioni (/wc-api/tap_p_webhook/) sia raggiungibile da Internet (nessun firewall, modalità manutenzione o autenticazione HTTP) e controlla WooCommerce > Status > Logs, origine wcp_tap_payment_gateway. L'ordine viene aggiornato 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.

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

L'ordine è On hold: leggi la nota dell'ordine. Il pagamento è stato solo autorizzato (acquisiscilo dalle azioni dell'ordine), l'importo o la valuta pagati non corrispondevano all'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato.

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

Hook per sviluppatori: sono disponibili i filtri tap_p_supported_currencies, tap_p_currency_decimals, tap_p_charge_payload, tap_p_icon, tap_p_checkout_sdk_url e tap_p_payment_page_hosts.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad 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 dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le altre opzioni del plugin e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento, gli ID Tap e gli ID di transazione.

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