VibeFox Helcim for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Senza WooCommerce il plugin rifiuta di attivarsi.

PHP: 8.0 o successivo.

HTTPS e PCI DSS: i dati della carta vengono inseriti nel tuo 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 essere conforme a 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 di test (sviluppatore) Helcim è facoltativo per effettuare prove.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un 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_helcim_gateway in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. 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 relativo token.

4. Apri le impostazioni: WooCommerce > Settings > Payments > Helcim > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.

5. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

6. Incolla il token in Live API token e il token del tuo account di test Helcim in Test API token se ne possiedi uno.

7. Scegli il Transaction type e le Account currencies, attiva Enable / Disable e salva. Per testare prima, attiva Test mode ed effettua un pagamento con il tuo account di test; poi disattivalo.

Configurazione

Tutte le impostazioni sono in una sola pagina: WooCommerce > Settings > Payments > Helcim. Sopra i campi, la pagina ti avvisa quando la valuta del negozio non è una delle Account currencies e, mentre il gateway è abilitato, quando il token API della modalità attuale è vuoto. In entrambi i casi il gateway viene nascosto al checkout. Nell'elenco dei metodi di pagamento il gateway è contrassegnato come richiedente configurazione finché la modalità attuale non ha un token.

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

Title: il titolo del metodo di pagamento mostrato al checkout. Predefinito: Credit card (Helcim).

Description: la descrizione del metodo di pagamento mostrata al 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 relativo token. Assegnagli i diritti di elaborazione delle transazioni per acquisti, pre-autorizzazioni, acquisizioni e rimborsi. Gli account di test Helcim utilizzano lo stesso indirizzo API degli account live, quindi la modalità di test usa semplicemente il token del tuo account di test Helcim.

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

Test mode: Use the Test API token (Helcim test account). Pagamenti, acquisizioni e rimborsi vanno al tuo account di test Helcim e i clienti visualizzano un avviso di modalità di test. I rimborsi e le acquisizioni di un ordine utilizzano sempre il token della modalità in cui l'ordine è stato pagato. Predefinito: disattivato.

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

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 dell'ordine. Il gateway viene nascosto al checkout per le altre valute.

Avanzate

Debug log: Log API requests and responses in WooCommerce > Status > Logs, origine wcp_helcim_gateway. I numeri di carta sono ridotti alle ultime 4 cifre. CVC, scadenza, token, nomi, indirizzi, e-mail e indirizzi IP non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit card (Helcim)) e inserisce Card Number, Expiry (MM/YY), CVC e Cardholder Name nel tuo checkout. Le icone di Visa, Mastercard, American Express e Discover sono mostrate accanto al titolo. In modalità di test il modulo mostra TEST MODE — payments go to a Helcim test account, no real charges are made. Prima dell'invio, il plugin 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.

Quando l'ordine viene effettuato, il tuo server invia la carta a Helcim come acquisto o pre-autorizzazione per il totale dell'ordine nella valuta dell'ordine. L'indirizzo di fatturazione, il telefono e l'e-mail vengono inviati per la verifica dell'indirizzo. Il pagamento viene visualizzato in Helcim con un numero di fattura composto dal numero d'ordine e da un codice breve. Helcim risponde nella stessa richiesta. L'ordine viene contrassegnato come pagato solo dopo che Helcim ha approvato la transazione e l'importo e la valuta approvati corrispondono all'ordine. Quindi il cliente arriva alla pagina dell'ordine ricevuto.

Viene eseguito un solo tentativo di pagamento alla volta per ciascun ordine, e un ordine già pagato non viene mai addebitato di nuovo. Ogni tentativo utilizza una chiave di idempotenza. Se Helcim non risponde, l'ordine rimane In attesa di pagamento e un nuovo tentativo entro 5 minuti restituisce il risultato originale di Helcim anziché addebitare la carta due volte.

Messaggi che il cliente può visualizzare: 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 respinte; 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 è mancante o rifiutato; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. in caso di doppio invio. I dettagli tecnici vengono inseriti nelle note dell'ordine e nel registro.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout (con gli stessi campi carta) e nella pagina Pay for order. È compatibile con la memorizzazione degli ordini ad alte prestazioni (HPOS) di WooCommerce.

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

Ordini e rimborsi

Stati dell'ordine

Pending payment: il pagamento è stato rifiutato o non è ancora stato confermato. Se Helcim non ha risposto, la nota dell'ordine chiede di verificare la fattura in Helcim prima di addebitare nuovamente il cliente.

Processing: un acquisto è stato approvato o una pre-autorizzazione è stata acquisita. Gli ordini con soli prodotti virtuali scaricabili diventano Completato, come impostazione predefinita di WooCommerce. La nota dell'ordine mostra l'ID transazione, il codice di approvazione, il tipo di carta, le ultime 4 cifre e la modalità. L'ID transazione è l'ID transazione Helcim.

On hold (pre-authorization): i fondi sono solo trattenuti. Acquisiscili con l'azione dell'ordine o sbloccali con un rimborso completo.

On hold after payment: Helcim ha approvato una transazione, ma l'importo, la valuta o l'ID transazione nella sua risposta non corrispondono all'ordine. La nota recita Helcim response verification FAILED. Controlla la transazione in Helcim prima di evadere l'ordine.

Acquisizione

Apri l'ordine (stato in sospeso), scegli l'azione dell'ordine Capture Helcim pre-authorization e fai clic su Update. Viene acquisito il totale attuale dell'ordine, al netto dei rimborsi. Può essere inferiore all'importo autorizzato, ma non superiore. L'acquisizione utilizza il token della modalità in cui l'ordine è stato pagato. Dopo un'acquisizione riuscita, l'ordine passa a In lavorazione e l'ID transazione cambia con quello della transazione di acquisizione. Se l'acquisizione fallisce, viene visualizzato il motivo e aggiunto alle note dell'ordine.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit card (Helcim) (il pulsante mostra il tuo Title). Sono supportati rimborsi completi e parziali di un acquisto o di una pre-autorizzazione acquisita. Una pre-autorizzazione non acquisita può essere rimborsata solo per intero: la trattenuta viene sbloccata e al cliente non viene addebitato alcun importo. Il rimborso viene inviato nella modalità in cui l'ordine è stato pagato, quindi il token di tale modalità deve essere impostato. Ha valore solo quando Helcim lo approva. Se Helcim lo rifiuta, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID della transazione di rimborso Helcim. Un nuovo tentativo dopo un timeout non rimborsa due volte.

Il plugin non riceve webhook Helcim. Le acquisizioni, i rimborsi e gli annullamenti effettuati nella dashboard di Helcim non vengono riflessi in WooCommerce, quindi eseguili direttamente da 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 > Helcim. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino a cui la licenza è attiva e il tuo dominio. Usa Check now per controllare nuovamente 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 dominio. Rimuovere la chiave da un sito non libera il relativo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Helcim non viene mostrato ai clienti al checkout. Se un pagamento viene comunque avviato, 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 come (unlicensed — visible to admins only), in modo da poter configurare e testare il plugin prima di acquistare una chiave. Un promemoria viene visualizzato nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: acquisizioni e rimborsi continuano a funzionare.

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

Helcim non compare al checkout: controlla che la licenza sia attiva, che Enable / Disable sia attivo, che la modalità attuale disponga del relativo token API (Live API token, oppure Test API token in modalità di test) e che la valuta del carrello sia una delle Account currencies. Nella pagina Pay for order conta la valuta dell'ordine. La pagina delle impostazioni mostra un avviso in entrambi i casi.

Helcim non ha risposto e l'ordine rimane In attesa di pagamento: la carta potrebbe essere stata addebitata. Leggi la nota dell'ordine e controlla la fattura in Helcim prima di addebitare nuovamente il cliente. Un nuovo tentativo entro 5 minuti restituisce il risultato originale e non addebita due volte.

I clienti visualizzano This payment method is temporarily unavailable: il token API della modalità attuale è vuoto oppure è stato rifiutato da Helcim. La nota dell'ordine invita a verificare il token e i relativi permessi. Assicurati che l'accesso API abbia i diritti di elaborazione delle transazioni.

Pagamento non riuscito con motivo Helcim: Helcim ha rifiutato la richiesta, ad esempio a causa della carta o dei dettagli di fatturazione. La nota dell'ordine riporta i dettagli.

L'ordine è in sospeso dopo il pagamento: leggi la nota dell'ordine. L'ordine è stato pre-autorizzato ed è in attesa di acquisizione, oppure la risposta di Helcim non corrispondeva all'ordine (verifica della risposta non riuscita).

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

Il rimborso non riesce: leggi il messaggio. Una pre-autorizzazione non acquisita può essere rimborsata solo per intero. Un messaggio relativo alla modalità indica che il token della modalità in cui l'ordine è stato pagato è vuoto. Un rimborso rifiutato non viene registrato.

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

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già utilizzata 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 di licenza non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Per gli sviluppatori: il filtro wc_hlg_supported_currencies modifica l'elenco delle valute e wc_hlg_card_brands modifica le icone delle carte al checkout.

Disinstallazione

Disattivando il plugin, tutti i dati vengono mantenuti. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le opzioni proprietarie del plugin e i registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti rimangono per una successiva reinstallazione. I dati degli ordini fanno parte della cronologia degli ordini e non vengono mai eliminati. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

Helcim è un marchio del rispettivo titolare. Questo plugin non è affiliato a Helcim né approvato da Helcim.