VibeFox Cardcom for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP precedenti.

HTTPS: il tuo negozio deve essere raggiungibile da internet tramite HTTPS, affinché Cardcom possa inviare la notifica di pagamento.

Valuta: la valuta del carrello deve essere ILS, USD, EUR o GBP. Per qualsiasi altra valuta il metodo di pagamento viene nascosto al checkout.

Account Cardcom: per i pagamenti reali 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 PrestaShop. La modalità test funziona senza un account Cardcom.

Chiave di licenza VibeFox: si acquista 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 Cardcom Payment Gateway nell'elenco dei moduli e fai clic su Configure.

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

4. Attiva Enable/Disable, lascia attivo Test Mode e fai clic su Save. Effettua un ordine di prova con la carta 4580 0000 0000 0000, una data di scadenza futura qualsiasi e CVV 123.

5. Per i pagamenti reali disattiva Test Mode, inserisci il Terminal Number, l'API Username e l'API Password ricevuti da Cardcom e fai clic su Save.

All'installazione il modulo crea lo stato dell'ordine Cardcom payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i Paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina mostra un avviso finché la modalità test è attiva. In modalità live avvisa se mancano il numero di terminale o il nome utente API (in tal caso Cardcom viene nascosto al checkout), se nei campi live sono inseriti il terminale di test pubblico 1000 / CardTest1994 (anche in questo caso Cardcom viene nascosto al checkout, perché non verrebbe addebitato denaro reale), e ricorda che senza la password API non sono possibili i rimborsi da PrestaShop. Avvisa inoltre se la valuta predefinita del tuo negozio non è supportata. Quando salvi la modalità live con credenziali mancanti o di test, un messaggio di errore indica che il gateway resta nascosto al checkout finché non inserisci il tuo numero di terminale e il tuo nome utente API.

Cardcom

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit Card (Cardcom). Obbligatorio.

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 di Cardcom 1000 (utente API CardTest1994). Non viene addebitato denaro reale e non serve un account Cardcom. Carta di prova: 4580 0000 0000 0000, una data di scadenza futura qualsiasi, CVV 123. In modalità test il checkout mostra anche una riga con questa carta di prova.

Test Mode: attiva la modalità test (terminale 1000, nessun denaro reale). Predefinito: attivo. Disattivala 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

Il numero di terminale, il nome utente API e la password API ti vengono forniti da Cardcom insieme al tuo account commerciante: nella dashboard di Cardcom, nella sezione delle impostazioni API, oppure tramite l'assistenza 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 resta il valore precedente.

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 PrestaShop. La password salvata non viene più mostrata: il campo resta vuoto e riporta Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear the saved API password: spunta la casella e fai clic su Save per rimuovere la password. Un campo vuoto mantiene il valore salvato.

Pagina di pagamento

Notification URL: Cardcom invia le notifiche di pagamento (IndicatorUrl) a questo indirizzo. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_cardcom_payment_gateway/webhook, eventualmente con un codice lingua come /en/. L'indirizzo viene passato automaticamente a Cardcom con ogni pagamento, insieme all'ID del carrello, quindi non c'è nulla da configurare in Cardcom. Deve essere raggiungibile da internet tramite HTTPS.

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 rata. Predefinito: 1.

Success Order Status: lo stato dell'ordine dopo un pagamento confermato. L'ordine viene creato direttamente in questo stato.

I pagamenti che non corrispondono all'ordine finiscono sempre in Cardcom payment on hold.

Avanzate

Debug log: registra le richieste API e le notifiche in logs/cardcom_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. Credenziali, token delle carte e dati del titolare non vengono mai scritti. Predefinito: disattivato.

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

Delete on Uninstall: se attivo, la disinstallazione del modulo rimuove in modo permanente le impostazioni e i registri. Ordini, transazioni e rimborsi Cardcom e lo stato dell'ordine Cardcom payment on hold vengono sempre conservati, così i vecchi ordini possono essere rimborsati anche dopo una reinstallazione. Predefinito: disattivato.

Checkout

Al passaggio del pagamento, il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (Cardcom)) e vede la nota You will be redirected to the secure Cardcom payment page. Dopo la conferma, il modulo crea una pagina di pagamento Cardcom per il totale del carrello nella valuta del carrello e invia lì il cliente. A questo punto l'ordine non esiste ancora. La pagina si apre in ebraico se la lingua del cliente è l'ebraico, altrimenti in inglese. I prodotti del carrello 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 nel tuo negozio. L'ordine viene contrassegnato come pagato solo quando Cardcom lo conferma. Cardcom chiama l'indirizzo di notifica e il modulo ricava da quella chiamata solo il codice della pagina di pagamento. Verifica che quel codice sia stato emesso dal tuo negozio per quel carrello, quindi chiede a Cardcom, da server a server, il risultato reale. Se la notifica arriva in ritardo, la stessa verifica viene eseguita quando il cliente torna. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Cardcom has been received. Se Cardcom non ha ancora confermato il pagamento quando il cliente torna, una pagina Payment confirmation mostra Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. con un pulsante Check again; la notifica crea l'ordine non appena arriva.

Se il pagamento non viene completato o Cardcom lo rifiuta, il cliente torna al checkout con The card payment was not completed. Please try again or choose a different payment method. Nessun ordine viene creato e il carrello viene conservato. Il cliente può riprovare: ogni tentativo ottiene una nuova pagina di pagamento Cardcom. Un pagamento effettuato su una pagina di pagamento precedente dello stesso carrello viene comunque riconosciuto, e un rifiuto su una pagina precedente non influisce su un nuovo tentativo.

Se Cardcom non riesce ad aprire la pagina di pagamento, il cliente resta al checkout con un breve messaggio, ad esempio Could not connect to Cardcom. Please try again in a moment., oppure con il messaggio che Cardcom non è riuscito ad aprire la pagina di pagamento, insieme al codice Cardcom, e può scegliere un altro metodo di pagamento.

La notifica funziona anche mentre il negozio è in modalità manutenzione e non viene bloccata dalla restrizione per Paese del tuo negozio.

Il modulo accetta pagamenti con carta solo nella pagina Cardcom. Non prevede carte salvate o pagamenti con un clic, né abbonamenti, non addebita i token salvati, non ha impostazioni di fattura o ricevuta Cardcom, né Bit, Apple Pay, Google Pay o PayPal tramite Cardcom, né modalità iframe né operazioni con acquisizione differita.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Cardcom e non ha pagato, il pagamento è stato rifiutato oppure Cardcom non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted, Delivered or Cardcom payment on hold: il pagamento è stato confermato. Lo stato segue Success Order Status. Il pagamento viene registrato con il numero dell'operazione (deal) Cardcom come ID transazione. Un messaggio privato dell'ordine mostra la transazione Cardcom e, quando Cardcom li riporta, le ultime quattro cifre della carta, il numero di fattura e il numero di rate. I pagamenti di prova sono contrassegnati con Test mode — no real money was charged.

Cardcom payment on hold after payment: Cardcom ha confermato un pagamento che non corrisponde all'ordine, ad esempio perché il carrello è stato modificato dopo l'apertura della pagina di pagamento, oppure perché è stato addebitato un importo o una valuta diversi. Il messaggio lo spiega e il blocco Cardcom lo mostra sotto Needs review. Il pagamento viene registrato per l'importo addebitato da Cardcom quando la valuta coincide con quella dell'ordine. Confronta il pagamento nella dashboard Cardcom con l'ordine, quindi evadi l'ordine oppure rimborsa il pagamento.

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

Se arriva un secondo pagamento riuscito per un carrello che ha già un ordine (ad esempio se il cliente ha pagato in due schede del browser), l'ordine non cambia. Un messaggio avvisa che il cliente potrebbe essere stato addebitato due volte e ti chiede di rimborsarlo dalla dashboard Cardcom.

Blocco pagamento Cardcom

La pagina dell'ordine mostra un blocco Cardcom payment con la transazione, il codice della pagina di pagamento, lo stato, la carta, le rate, la fattura, il token della carta (con Charge + Save token), l'importo addebitato, il totale dell'ordine e l'importo rimborsato, un badge Test mode per i pagamenti di prova e la cronologia dei rimborsi.

Rimborsi

Nel blocco Cardcom payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Cardcom. Conferma la domanda Refund this amount through Cardcom? This cannot be undone. Sono supportati rimborsi totali e parziali, ed è possibile effettuare più rimborsi parziali per un ordine. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine dei moduli. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Cardcom, quindi dopo una differenza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non il totale dell'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 reali usano sempre le tue credenziali live. Per i rimborsi live servono API Username e API Password. Se Cardcom non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e ai messaggi dell'ordine, con la transazione di rimborso Cardcom e il motivo. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non modifica lo stato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Cardcom. I rimborsi effettuati nella dashboard Cardcom non vengono comunicati al negozio.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Cardcom Payment Gateway è il primo blocco di Modules > Module Manager > VibeFox Cardcom 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 (ad 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. Sotto di essi ci sono la riga Product: presta-payment-cardcom e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con l'autorizzazione 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 spiega il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo una modifica dell'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, 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. La vetrina 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 al 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 i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e assistenza richiedono un 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Cardcom non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la valuta del carrello sia ILS, USD, EUR o GBP. In modalità live verifica che Terminal Number e API Username siano compilati con le tue credenziali, non con il terminale di test 1000 / CardTest1994. La pagina delle impostazioni mostra un avviso quando manca qualcosa. 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: Cardcom non è riuscito a raggiungere il tuo negozio, ad esempio a causa di un firewall, di una protezione con password o di un sito di sviluppo locale. L'indirizzo di notifica deve essere raggiungibile da internet tramite HTTPS. L'ordine viene creato anche quando il cliente torna nel negozio dopo il pagamento. Attiva Debug log e controlla il campo Log nella pagina del modulo.

La notifica risponde Missing or invalid lowprofilecode or Unknown lowprofilecode for this order: la chiamata non conteneva un codice di pagina di pagamento emesso dal tuo negozio per quel carrello. Non viene modificato nulla.

La notifica risponde Gateway not configured or Indicator check failed: mancano le credenziali della modalità in cui è stata creata la pagina di pagamento, oppure Cardcom non è stato raggiunto per la verifica. Non viene modificato nulla; il pagamento viene verificato di nuovo quando il cliente torna nel negozio.

La notifica risponde Busy, retry: il carrello era in fase di conferma da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). Attiva Debug log per vedere il motivo.

La notifica risponde ReturnValue mismatch or Terminal mismatch: Cardcom ha segnalato un pagamento per un altro carrello o un altro terminale. Non viene modificato nulla. Verifica che Terminal Number sia il terminale del tuo account.

Il cliente vede Payment error: this currency is not supported by Cardcom.: la valuta del carrello non è ILS, USD, EUR o GBP.

Il cliente vede Card payment is temporarily unavailable. Please choose another payment method.: la modalità live è attiva, ma il numero di terminale o il nome utente API manca, oppure i campi live contengono il terminale di test pubblico.

Il cliente vede un errore quando sceglie Cardcom: attiva Debug log e controlla il campo Log. Lì vengono scritti i problemi di connessione e i codici di errore Cardcom.

L'ordine è Cardcom payment on hold after payment: leggi il messaggio dell'ordine oppure Needs review nel blocco Cardcom payment. L'importo o la valuta pagati non corrispondevano all'ordine. Evadi l'ordine oppure rimborsa il pagamento.

Il rimborso non riesce con il messaggio 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 il messaggio Could not connect to Cardcom: controlla la dashboard Cardcom prima di riprovare, perché il rimborso potrebbe essere stato effettuato oppure no.

Per gli sviluppatori, il README elenca l'hook actionCardcomSupportedCurrencies, che estende l'elenco delle valute (aggiungi solo valute attive sul tuo terminale Cardcom), e actionCardcomLowProfileParams, che modifica i parametri della pagina di pagamento.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Cardcom Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete on Uninstall è attivo, le impostazioni e i registri vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi Cardcom e lo stato dell'ordine Cardcom payment on hold vengono sempre conservati, così gli ordini pagati in precedenza possono essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano i loro messaggi di pagamento e gli ID delle transazioni.

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