VibeFox Cardcom 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.
HTTPS: il tuo sito deve essere raggiungibile da internet tramite HTTPS, così che Cardcom possa inviare la notifica di pagamento.
Valuta: la valuta dell'ordine deve essere ILS, USD, EUR o GBP. Per qualsiasi altra valuta il metodo di pagamento viene nascosto al checkout.
Account Cardcom: per i pagamenti live ti serve un account commerciante Cardcom con numero di terminale, nome utente API e password API. Per i pagamenti bastano il numero di terminale e il nome utente API. La password API serve solo per i rimborsi da WooCommerce. La modalità test funziona senza un account Cardcom.
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 fai clic su Install Now. Puoi anche caricare la cartella wcp_cardcom_payment_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Cardcom > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
5. Attiva Enable/Disable, lascia attivo Test Mode ed effettua un ordine di prova con la carta 4580 0000 0000 0000, una data di scadenza futura qualsiasi e CVV 123.
6. Per i pagamenti reali deseleziona Test Mode e inserisci il Terminal Number, l'API Username e la API Password ricevuti da Cardcom.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Cardcom. Sopra i campi la pagina mostra Test mode is on. finché la modalità test è attiva. In modalità live avvisa se mancano il numero di terminale o il nome utente API (Cardcom resta nascosto al checkout) e ricorda che senza la password API non sono possibili i rimborsi da WooCommerce. Avvisa anche quando la valuta del negozio non è supportata. Se salvi la modalità live senza numero di terminale o nome utente API, un messaggio di errore indica che il gateway resta nascosto al checkout finché non vengono inseriti.
Generali
Enable/Disable: Enable Cardcom Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Credit Card (Cardcom).
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your credit card via Cardcom.
Modalità test
La modalità test usa il terminale di test pubblico Cardcom 1000 (utente API CardTest1994). Non viene addebitato denaro reale e non serve un account Cardcom. Carta di test: 4580 0000 0000 0000, una data di scadenza futura qualsiasi, CVV 123. In modalità test anche il checkout mostra una riga con questa carta di test.
Test Mode: Enable test mode (terminal 1000, no real money). Predefinito: attivato. Deseleziona per accettare pagamenti reali con le credenziali live qui sotto. I rimborsi vengono sempre inviati con le credenziali della modalità in cui l'ordine è stato pagato.
Credenziali live
Numero di terminale, nome utente API e password API sono forniti da Cardcom insieme al tuo account commerciante: nella dashboard Cardcom, sotto le impostazioni API, oppure tramite il supporto Cardcom. Questi campi vengono usati solo in modalità live.
Terminal Number: il tuo numero di terminale Cardcom. Deve contenere solo cifre. Se inserisci altro, viene mostrato un errore e il valore precedente viene mantenuto.
API Username: il tuo nome utente API Cardcom (ApiName) per questo terminale. Gli spazi vengono rimossi al salvataggio.
API Password: la tua password API Cardcom. Serve solo per i rimborsi da WooCommerce ed è salvata esattamente come digitata.
Pagina di pagamento
Cardcom invia le notifiche di pagamento (IndicatorUrl) all'indirizzo mostrato in questa sezione. Ha una forma come https://your-site/wc-api/cardcom_p_callback/. L'indirizzo viene passato automaticamente a Cardcom con ogni pagamento, insieme al numero dell'ordine, quindi non c'è nulla da configurare in Cardcom. Deve essere raggiungibile da internet.
Operation: cosa fa Cardcom nella pagina di pagamento.
Max Installments: il numero massimo di rate (pagamenti) che il cliente può scegliere nella pagina Cardcom, da 1 a 36. 1 significa nessuna rateizzazione. Predefinito: 1.
Success Order Status: lo stato dell'ordine dopo un pagamento confermato. Lo stato viene impostato subito, senza un secondo cambio di stato.
Avanzate
Debug log: Log API requests and notifications scrive in WooCommerce > Status > Logs, origine wcp_cardcom_payment_gateway. Gli errori vengono sempre registrati. Credenziali, token delle carte e dati del titolare non vengono mai scritti. Predefinito: disattivato.
Delete on Uninstall: Delete all plugin data when uninstalling. Se attivo, eliminando il plugin vengono rimossi in modo permanente le impostazioni, i dati Cardcom salvati negli ordini e i registri. Gli ordini stessi vengono conservati. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (Cardcom)) e fa l'ordine. Il plugin crea una pagina di pagamento Cardcom per il totale dell'ordine nella valuta dell'ordine e vi invia il cliente. La pagina si apre in ebraico se la lingua del sito è l'ebraico, altrimenti in inglese. Gli articoli dell'ordine vengono passati a Cardcom come nome del prodotto. Il cliente inserisce i dati della carta e, se le rate sono consentite, sceglie il numero di pagamenti.
Dopo il pagamento, il cliente torna alla pagina Ordine ricevuto del tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Cardcom. Cardcom chiama l'indirizzo di notifica, e il plugin ricava da quella chiamata solo il codice della pagina di pagamento. Verifica che questo codice sia stato emesso dal tuo negozio per quell'ordine, poi chiede a Cardcom il risultato reale da server a server. Se la notifica arriva in ritardo, lo stesso controllo viene eseguito quando il cliente arriva alla pagina Ordine ricevuto.
Se il pagamento non viene completato, Cardcom rimanda il cliente al checkout (o alla pagina Pay for order), che mostra The card payment was not completed. Please try again or choose a different payment method. Un pagamento rifiutato confermato da Cardcom porta l'ordine a Non riuscito. Il cliente può pagare di nuovo un ordine non pagato, per esempio dalla pagina Pay for order. Un pagamento effettuato su una pagina di pagamento più vecchia dello stesso ordine viene comunque riconosciuto. Se il cliente è passato a un altro metodo di pagamento ma ha pagato nella pagina Cardcom, il pagamento viene registrato e il metodo di pagamento torna a Cardcom.
Se Cardcom non riesce ad aprire la pagina di pagamento, il cliente vede un breve messaggio, per esempio Could not connect to Cardcom. Please try again in a moment. oppure che Cardcom non ha potuto aprire la pagina di pagamento, con il codice Cardcom, e può scegliere un altro metodo di pagamento.
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 accetta pagamenti con carta solo sulla pagina Cardcom. Non prevede carte salvate o pagamenti con un clic, abbonamenti, non addebita i token salvati, non ha impostazioni di fattura o ricevuta Cardcom, nessun Bit, Apple Pay, Google Pay o PayPal tramite Cardcom, nessuna modalità iframe e nessuna operazione con acquisizione differita. Le pagine di pagamento abbandonate non vengono verificate automaticamente.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Cardcom e non ha ancora pagato, oppure Cardcom non ha ancora confermato il pagamento.
Processing, Completed or On Hold: il pagamento è stato confermato. Lo stato segue Success Order Status. La nota dell'ordine mostra la transazione Cardcom e, quando Cardcom le riporta, le ultime quattro cifre della carta, il numero della fattura e il numero di rate. I pagamenti di prova sono contrassegnati con Test mode — no real money was charged. L'ID transazione dell'ordine è il numero di operazione Cardcom.
On hold after payment: Cardcom ha confermato un pagamento che non corrisponde all'ordine, per esempio il totale dell'ordine è stato modificato dopo l'apertura della pagina di pagamento, oppure è stata addebitata un'altra somma o un'altra valuta. La nota dell'ordine lo spiega. Confronta il pagamento nella dashboard Cardcom con l'ordine, poi evadi l'ordine oppure rimborsa il pagamento.
Failed: Cardcom ha rifiutato il pagamento. La nota dell'ordine mostra il codice di risposta Cardcom. Un rifiuto su una pagina di pagamento più vecchia non fa fallire un nuovo tentativo, e un rifiuto tardivo non modifica mai un ordine pagato.
Se arriva un secondo pagamento riuscito per un ordine già pagato (per esempio il cliente ha pagato in due schede del browser), l'ordine non viene modificato di nuovo. Una nota avvisa che il cliente potrebbe essere stato addebitato due volte e ti chiede di rimborsarlo nella dashboard Cardcom.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit Card (Cardcom) (il pulsante mostra il titolo del metodo di pagamento). Sono supportati rimborsi totali e parziali, ed è possibile eseguire più rimborsi parziali per un ordine. Il rimborso viene inviato con le credenziali della modalità in cui l'ordine è stato pagato: gli ordini di prova vengono rimborsati sul terminale di test Cardcom anche dopo il passaggio alla modalità live, mentre gli ordini live usano sempre le tue credenziali live. Per i rimborsi live servono API Username e API Password. Se Cardcom non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con la transazione di rimborso Cardcom e il motivo.
I rimborsi effettuati nella dashboard Cardcom non vengono comunicati al negozio. Se necessario, crea un rimborso manuale in WooCommerce senza usare Refund via il gateway.
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 > Cardcom. 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 posto del dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Cardcom 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 che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.
Risoluzione dei problemi
Cardcom non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la valuta dell'ordine sia ILS, USD, EUR o GBP. In modalità live controlla che Terminal Number e API Username siano compilati. La pagina delle impostazioni mostra un avviso quando manca qualcosa.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: Cardcom non è riuscito a raggiungere il tuo sito, per esempio a causa della modalità manutenzione, di un firewall, della protezione con password o di un sito di sviluppo locale. L'indirizzo di notifica deve essere raggiungibile da internet tramite HTTPS. L'ordine viene confermato anche quando il cliente torna alla pagina Ordine ricevuto. Attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_cardcom_payment_gateway.
La notifica risponde Missing or invalid lowprofilecode o Unknown lowprofilecode for this order: la chiamata non conteneva un codice di pagina di pagamento emesso dal tuo negozio per quell'ordine. L'ordine non viene modificato.
La notifica risponde Gateway not configured o Indicator check failed: mancano le credenziali della modalità in cui è stata creata la pagina di pagamento, oppure Cardcom non è raggiungibile per la verifica. L'ordine non viene modificato e viene ricontrollato quando il cliente torna nel negozio.
La notifica risponde ReturnValue mismatch o Terminal mismatch: Cardcom ha segnalato un pagamento per un altro ordine o un altro terminale. L'ordine non viene modificato. Controlla che Terminal Number sia il terminale del tuo account.
Il cliente vede Payment error: this currency is not supported by Cardcom.: la valuta dell'ordine non è ILS, USD, EUR o GBP.
Il cliente vede Card payment is temporarily unavailable. Please choose another payment method.: la modalità live è attiva, ma manca il numero di terminale o il nome utente API.
Il cliente vede un errore quando effettua l'ordine: apri le note dell'ordine oppure attiva il Debug log e controlla il registro. Lì vengono scritti i problemi di connessione e i codici di errore Cardcom.
L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi dall'ordine. Evadi l'ordine oppure rimborsa il pagamento.
Il rimborso non riesce con API username and API password are required for refunds: inserisci la API Password (e l'API Username) nelle impostazioni e riprova.
Il rimborso non riesce con Could not connect to Cardcom: controlla la dashboard Cardcom prima di riprovare, perché il rimborso potrebbe essere stato eseguito oppure no.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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.
Per gli sviluppatori, il readme elenca il filtro cardcom_p_supported_currencies, che estende l'elenco delle valute (aggiungi solo le valute abilitate sul tuo terminale Cardcom).
Disinstallazione
Disattivare il plugin mantiene 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. Impostazioni del gateway, dati Cardcom salvati negli ordini e registri vengono rimossi solo se Delete on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.
Cardcom è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Cardcom.