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

HTTPS e PCI DSS: i dati della carta vengono inseriti nel checkout e inviati dal tuo server a Helcim tramite HTTPS. Non vengono mai memorizzati né registrati, ma transitano attraverso il tuo server, quindi il tuo negozio necessita di un certificato SSL e il tuo hosting deve rispettare PCI DSS (SAQ D).

Account Helcim: un account commerciante Helcim in Canada o negli Stati Uniti e un token API con diritti di elaborazione delle transazioni (vedi Configurazione). Helcim elabora CAD e USD. Un account Helcim di test (sviluppatore) è facoltativo per le prove.

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 più tardi VibeFox Helcim 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. In Helcim apri All Tools > Integrations > API Access Configuration, crea un accesso API con diritti di elaborazione delle transazioni (acquisti, pre-autorizzazioni, acquisizioni, rimborsi) e copia il suo token.

5. Incolla il token in Live API token, e il token del tuo account Helcim di test in Test API token se ne hai uno.

6. Scegli il Transaction type e le Account currencies, attiva Enable / Disable e fai clic su Save. Per provare prima, attiva Test mode e paga con il tuo account di test; poi disattivalo.

All'installazione il modulo crea due stati dell'ordine, Helcim payment authorized e Helcim payment on hold. PrestaShop attiva 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 Helcim Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa se la valuta predefinita del tuo negozio non è tra le Account currencies e, mentre il metodo di pagamento è attivo, se il token API della modalità corrente è vuoto. In tal caso il metodo di pagamento viene nascosto nel checkout.

Helcim

Enable / Disable: Enable Helcim Gateway attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il titolo del metodo di pagamento mostrato nel checkout. È anche il nome del metodo di pagamento memorizzato nell'ordine. Predefinito: Credit card (Helcim). Obbligatorio.

Description: la descrizione del metodo di pagamento mostrata nel checkout. Predefinito: Pay securely with your credit card.

Credenziali API

In Helcim vai su All Tools > Integrations > API Access Configuration, crea un accesso API e copia il suo token. Assegnagli il diritto di elaborazione delle transazioni per acquisti, pre-autorizzazioni, acquisizioni e rimborsi. Gli account di test di Helcim usano lo stesso indirizzo API degli account live, quindi la modalità di test utilizza semplicemente il token del tuo account di test Helcim.

Live API token: il token API del tuo account Helcim live. Viene usato quando la modalità di test è disattivata.

Test mode: usa il Test API token (account di test Helcim). Pagamenti, acquisizioni e rimborsi vanno al tuo account di test Helcim, e i clienti vedono un avviso di modalità di test. Acquisizioni e rimborsi di un ordine utilizzano sempre il token della modalità con cui è stato pagato l'ordine. Predefinito: off.

Test API token: il token API del tuo account Helcim di test (sviluppatore). Viene usato quando la modalità di test è attiva.

I token salvati non vengono mai più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per modificarlo.

Clear saved tokens: seleziona un token e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Pagamento

Transaction type: come viene addebitata la carta.

Account currencies: le valute che il tuo account Helcim può elaborare. Gli ordini vengono sempre addebitati nella valuta del carrello. Il metodo di pagamento viene nascosto nel checkout per le altre valute.

Avanzate

Debug log: scrive le richieste e le risposte API in logs/wc_hlg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. I numeri di carta vengono ridotti alle ultime 4 cifre. CVC, scadenza, token, nomi, indirizzi, e-mail e indirizzi IP non vengono mai registrati. Gli errori (pagamenti rifiutati o falliti, errori API, acquisizioni e rimborsi falliti) vengono sempre registrati, anche quando questa opzione è disattivata. Predefinito: off.

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 i suoi file di log. Le transazioni, i rimborsi e gli stati dell'ordine Helcim restano sempre, quindi gli ordini pagati in precedenza possono ancora essere acquisiti e rimborsati dopo una reinstallazione. Predefinito: off.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit card (Helcim), con un'icona di carta) e inserisce Card Number, Expiry (MM/YY), CVC e Cardholder Name nel modulo sottostante. In modalità di test il modulo mostra TEST MODE — payments go to a Helcim test account, no real charges are made. Quando il cliente effettua l'ordine, il modulo verifica il checksum del numero di carta, che la data di scadenza sia valida e non passata, che il CVC abbia 3 o 4 cifre e che il nome sia compilato. Gli errori vengono mostrati nel checkout e non viene inviato nulla a Helcim.

Il tuo server invia quindi la carta a Helcim come acquisto o pre-autorizzazione per il totale del carrello nella valuta del carrello. Indirizzo di fatturazione, telefono ed e-mail vengono inviati per la verifica dell'indirizzo. Il pagamento compare in Helcim con un numero di fattura composto dal numero del carrello, -PS e un breve codice. Helcim risponde nella stessa richiesta. L'ordine viene creato solo dopo che Helcim ha approvato la transazione, e il cliente arriva alla pagina standard di conferma dell'ordine. Prima di allora non esiste alcun ordine.

Per ogni carrello è in corso un solo tentativo di pagamento alla volta, e un carrello che ha già un ordine non viene mai addebitato di nuovo. Ogni tentativo utilizza una chiave di idempotenza. Se Helcim non risponde, non viene creato alcun ordine, e un nuovo tentativo entro 5 minuti restituisce il risultato originale di Helcim anziché addebitare la carta due volte. Se il pagamento è stato approvato ma non è stato possibile creare l'ordine, il tentativo successivo dello stesso carrello crea l'ordine senza addebitare di nuovo la carta.

Messaggi che il cliente può vedere nel checkout: Your card was declined. Please check the card details or use another card. quando Helcim rifiuta; Payment failed: con il motivo di Helcim per le altre richieste rifiutate; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card. quando Helcim non risponde; This payment method is temporarily unavailable. Please choose another payment method. quando il token API manca o viene rifiutato da Helcim; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. in caso di doppio invio; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. quando il pagamento è stato approvato ma non è stato possibile creare l'ordine. Il carrello viene conservato. I dettagli tecnici vanno nel registro.

Il modulo non usa HelcimPay.js né Helcim.js, quindi i dati della carta transitano attraverso il tuo server. Non prevede carte salvate, abbonamenti, pagamenti ACH o bancari, Apple Pay, Google Pay o 3-D Secure, né webhook Helcim.

Ordini e rimborsi

Stati dell'ordine

No order: la carta è stata rifiutata, Helcim non ha risposto oppure il cliente non ha ancora pagato. Esiste solo il carrello. Rifiuti ed errori vengono registrati nel log.

Payment accepted: un acquisto è stato approvato, oppure una pre-autorizzazione è stata acquisita. Il pagamento viene registrato con l'ID transazione Helcim, e una nota mostra l'ID transazione, il codice di approvazione, il tipo di carta, le ultime 4 cifre e la modalità.

Helcim payment authorized: una pre-autorizzazione è stata approvata. I fondi sono solo trattenuti. Acquisiscili o sbloccali con un rimborso completo.

Helcim payment on hold: Helcim ha approvato una transazione, ma l'importo, la valuta o l'ID transazione nella sua risposta non corrispondono al carrello, ad esempio dopo un'approvazione parziale o se il carrello è stato modificato durante il pagamento. La nota riporta Helcim response verification FAILED. Per un acquisto, il pagamento viene registrato con l'importo che Helcim ha effettivamente addebitato. Verifica la transazione in Helcim prima di evadere l'ordine.

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

Canceled: una pre-autorizzazione non acquisita è stata sbloccata. Il cliente non è stato addebitato.

Se per un carrello che ha già un ordine viene approvata una seconda transazione, l'ordine non cambia. Una nota ti chiede di verificarla e di stornarla o rimborsarla in Helcim.

Blocco pagamento Helcim

La pagina dell'ordine mostra un blocco Helcim payment con l'ID transazione (e l'ID della pre-autorizzazione dopo un'acquisizione), il tipo di transazione e lo stato dell'acquisizione, il numero di fattura, la carta e il codice di approvazione, l'importo approvato, il totale dell'ordine e l'importo rimborsato, un badge Test mode per i pagamenti di prova, lo storico dei rimborsi e le Helcim notes dell'ordine. Acquisizione e rimborsi richiedono il permesso di modificare gli ordini.

Acquisizione

Per un ordine in Helcim payment authorized, fai clic su Capture payment nel blocco e conferma Capture the pre-authorized amount through Helcim? Viene acquisito il totale attuale dell'ordine, meno i rimborsi. Può essere inferiore all'importo pre-autorizzato, ma non superiore. L'acquisizione utilizza il token della modalità con cui è stato pagato l'ordine. Dopo un'acquisizione riuscita, l'ordine passa a Pagamento accettato e il pagamento viene registrato con l'ID transazione dell'acquisizione. Se l'acquisizione fallisce, il blocco mostra il motivo e lo aggiunge alle note.

Rimborsi

Nel blocco inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Helcim. Conferma Refund this amount through Helcim? This cannot be undone. Sono supportati rimborsi completi e parziali di un acquisto o di una pre-autorizzazione acquisita, fino all'importo che Helcim ha effettivamente addebitato; quindi, dopo un'approvazione parziale, non puoi rimborsare più di quanto ha pagato il cliente. Per una pre-autorizzazione non acquisita il pulsante è Release pre-authorization: si può sbloccare solo l'importo totale, la trattenuta viene rimossa e l'ordine passa a Annullato.

Il rimborso viene inviato nella modalità con cui è stato pagato l'ordine, quindi il token di quella modalità deve essere impostato. Il rimborso conta solo se Helcim lo approva. Se Helcim lo rifiuta, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con l'ID transazione del rimborso Helcim. Un rimborso completo imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. Un nuovo tentativo dopo un timeout non rimborsa due volte.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non rimandano denaro tramite Helcim. Il modulo non riceve webhook Helcim: acquisizioni, rimborsi e annullamenti effettuati nella dashboard di Helcim non vengono riflessi in PrestaShop, quindi eseguili dalla pagina dell'ordine.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Helcim Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox Helcim 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-helcim 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 incluse le lingue inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad 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 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, Helcim non viene mostrato ai clienti nel checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che hai effettuato l'accesso 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à effettuati restano, e acquisizioni e rimborsi continuano a funzionare.

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 a settimana. Non serve alcun cron job. La disinstallazione o il ripristino del modulo rimuovono sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Helcim non compare nel checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo, che la modalità corrente abbia il suo token API (Live API token, o Test API token in modalità di test) e che la valuta del carrello sia una delle Account currencies. La pagina delle impostazioni mostra un avviso quando il token manca o la valuta del negozio non è consentita. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il cliente ha visto «We could not confirm your payment»: Helcim non ha risposto, quindi la carta potrebbe essere stata addebitata. Controlla il campo Log: l'errore indica il carrello e la fattura Helcim. Verifica quella fattura in Helcim prima di addebitare di nuovo il cliente. Un nuovo tentativo entro 5 minuti restituisce il risultato originale e non addebita due volte.

I clienti vedono «This payment method is temporarily unavailable»: il token API della modalità corrente è vuoto oppure è stato rifiutato da Helcim. Il log indica di controllare il token e i suoi permessi. Assicurati che l'accesso API abbia il diritto di elaborazione delle transazioni.

Pagamento fallito con un motivo di Helcim: Helcim ha rifiutato la richiesta, ad esempio per la carta o per i dati di fatturazione. Il log contiene i dettagli.

Il cliente ha visto «Your payment was received, but the order could not be completed»: Helcim ha approvato il pagamento, ma PrestaShop non è riuscito a creare l'ordine (ad esempio perché il modulo era disattivato). Il log indica il motivo. Quando il cliente invia di nuovo lo stesso carrello, l'ordine viene creato dal pagamento approvato senza un secondo addebito.

Ordine in Helcim payment on hold: leggi le note nel blocco Helcim. La risposta di Helcim non corrispondeva al carrello (verifica della risposta non riuscita). Verifica la transazione in Helcim, poi evadi l'ordine o rimborsa il pagamento.

Acquisizione non possibile: l'importo da acquisire deve essere maggiore di 0 e non superiore all'importo pre-autorizzato, e il token della modalità con cui è stato pagato l'ordine deve essere impostato.

Rimborso non riuscito: leggi il messaggio. Una pre-autorizzazione non acquisita può essere sbloccata solo per intero. Un messaggio sulla modalità significa che il token della modalità con cui è stato pagato l'ordine è vuoto. Un rimborso rifiutato non viene registrato.

Pagamenti di test: la modalità di test invia pagamenti, acquisizioni e rimborsi al tuo account di test Helcim. Gli ordini mantengono la modalità con cui sono stati pagati, quindi cambiare modalità in seguito non sposta le loro acquisizioni e i loro rimborsi sull'altro account.

Disinstallazione

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

Helcim è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Helcim né approvato da Helcim.