VibeFox Datatrans for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo.

PHP: 8.0 o successivo.

HTTPS: il tuo sito deve essere raggiungibile da internet tramite HTTPS, in modo che Datatrans possa consegnare i webhook.

Account Datatrans: ti servono il Merchant ID, la password API server-to-server e, consigliata, la chiave di firma HMAC-SHA256 per i webhook. Le credenziali sandbox si ottengono dal Web Admin sandbox di Datatrans (admin.sandbox.datatrans.com), quelle di produzione dal Web Admin di produzione (admin.datatrans.com). Sandbox e produzione sono account Datatrans separati, con Merchant ID e chiavi diversi.

Valuta: la valuta del negozio (o la valuta dell'ordine del tuo plugin multivaluta) deve essere attiva per il tuo account commerciante Datatrans.

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 via FTP la cartella wcp_datatrans_gateway in /wp-content/plugins/.

2. Fai clic su Activate. WooCommerce deve essere attivo.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Datatrans > 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. Inserisci le credenziali sandbox e, per i pagamenti reali, le credenziali di produzione (vedi Configurazione).

6. Attiva Enable/Disable. Lascia attivo Sandbox mode durante i test, poi deseleziona la casella per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Datatrans. Quando il gateway è attivo ma mancano il Merchant ID o la password API dell'ambiente corrente, la pagina mostra Datatrans is hidden at checkout until these settings are filled in: con l'elenco dei campi mancanti. Finché la modalità sandbox è attiva, mostra Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Webhook

La Webhook URL è mostrata in cima alle impostazioni. Ha un formato simile a https://your-site/wc-api/datatrans_payment_callback/. Il plugin invia questo URL a Datatrans con ogni transazione, quindi non devi inserirlo da nessuna parte. Puoi anche inserirlo nelle impostazioni webhook del Web Admin di Datatrans per ricevere gli aggiornamenti su acquisizioni e annullamenti effettuati lì.

Il webhook comunica lo stato della transazione. Il plugin agisce in base a questi stati:

Con una chiave di firma HMAC, ogni webhook viene verificato tramite l'intestazione Datatrans-Signature. I webhook senza una firma valida vengono rifiutati. Senza chiave di firma, il plugin non si fida del contenuto del webhook e verifica ogni webhook con l'API di stato di Datatrans. Senza il webhook, un ordine viene confermato solo quando il cliente torna al negozio dopo aver pagato.

Generali

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Datatrans.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Datatrans.

Sandbox mode: Use the Datatrans sandbox (test payments, no real money). Cambia sia gli host dell'API e della pagina di pagamento sia le credenziali riportate sotto. Rimborsi e acquisizioni usano sempre l'ambiente in cui è stato effettuato il pagamento. Predefinito: attivo. Deseleziona la casella per accettare pagamenti reali.

Credenziali sandbox

Copiale dal Web Admin sandbox di Datatrans (admin.sandbox.datatrans.com). La chiave di firma si trova lì, nelle impostazioni di sicurezza.

Sandbox merchant ID: il Merchant ID del tuo account sandbox.

Sandbox API password: la password API server-to-server del tuo account sandbox.

Sandbox HMAC sign key: la chiave esadecimale usata per verificare l'intestazione Datatrans-Signature dei webhook. Senza di essa, ogni webhook viene ricontrollato con l'API di stato di Datatrans.

Credenziali di produzione

Copiale dal Web Admin di produzione di Datatrans (admin.datatrans.com).

Production merchant ID: il Merchant ID del tuo account di produzione.

Production API password: la password API server-to-server del tuo account di produzione.

Production HMAC sign key: la chiave esadecimale usata per verificare l'intestazione Datatrans-Signature dei webhook di produzione. Senza di essa, ogni webhook viene ricontrollato con l'API di stato di Datatrans.

Una chiave di firma deve essere una stringa esadecimale come quella emessa da Datatrans. Qualsiasi altro valore non viene salvato: la pagina mostra un errore e mantiene il valore precedente. Se aggiorni dalla versione 1.0, l'unico set di credenziali di quella versione viene spostato nei campi sandbox se la modalità sandbox era attiva; altrimenti resta nei campi di produzione.

Elaborazione del pagamento

Auto settle: Capture (settle) payments immediately. Predefinito: attivo. Se lo disattivi, i pagamenti vengono solo autorizzati: l'ordine viene messo in sospeso e lo acquisisci in seguito con l'azione dell'ordine Capture Datatrans payment, oppure lo rilasci con Cancel Datatrans authorization.

Order status after payment: lo stato dell'ordine impostato una volta regolato il pagamento. Lo stato viene impostato subito, senza un secondo cambio di stato.

Avanzate

Logging: Log payment events and API calls scrive i dettagli in WooCommerce > Status > Logs, origine wcp_datatrans_gateway. Gli errori vengono sempre registrati. Non vengono scritti chiavi, dati della carta o dati dei clienti. Predefinito: disattivato.

Delete data on uninstall: Remove the plugin settings when the plugin is deleted. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Datatrans) ed effettua l'ordine. Il plugin crea una transazione Datatrans per il totale dell'ordine nella valuta dell'ordine, con l'ID dell'ordine come riferimento, e indirizza il cliente alla pagina di pagamento di Datatrans. Lì il cliente paga con qualsiasi metodo attivo nel tuo account Datatrans, per esempio una carta, TWINT o PostFinance. La pagina di pagamento si apre in tedesco, inglese, francese o italiano quando il tuo sito usa una di queste lingue; altrimenti è Datatrans a scegliere la lingua.

Dopo il pagamento, il cliente torna alla pagina di ordine ricevuto del tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Datatrans: tramite il webhook o tramite una richiesta lato server all'API di stato di Datatrans quando il cliente ritorna. L'indirizzo di ritorno contiene la chiave dell'ordine, e il ritorno in sé non segna mai un ordine come pagato.

Se il cliente annulla nella pagina di pagamento, viene indirizzato alla pagina Pay for order con il messaggio The payment was canceled. You can try again or choose another payment method. Dopo un pagamento non riuscito il messaggio è The payment was not completed. Please try again or choose another payment method. L'ordine resta pagabile e il cliente può riprovare.

Se Datatrans non riesce ad avviare il pagamento, il cliente vede The payment could not be started. Please try again or choose another payment method. Il motivo viene scritto nel registro.

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

Il plugin accetta solo pagamenti singoli nella pagina di pagamento di Datatrans. Non prevede carte salvate o alias, abbonamenti, integrazione di Lightbox o Secure Fields, scelta dei metodi di pagamento nelle impostazioni né acquisizione parziale di un'autorizzazione.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato indirizzato a Datatrans e non ha ancora pagato, ha annullato nella pagina di pagamento, oppure Datatrans non ha ancora confermato il pagamento. Ogni nuova transazione viene annotata nell'ordine con il suo ID e il suo ambiente.

Processing, Completed or On Hold: il pagamento è stato regolato. Lo stato segue Order status after payment. La nota dell'ordine mostra l'importo, il metodo di pagamento, l'ID transazione Datatrans e l'ambiente (sandbox o produzione). L'ID transazione viene salvato nell'ordine.

On hold, authorized: con Auto settle disattivato, il pagamento è stato autorizzato ma non acquisito. Apri l'ordine e scegli Capture Datatrans payment o Cancel Datatrans authorization nelle azioni dell'ordine. L'acquisizione usa il totale attuale dell'ordine, che non deve superare l'importo autorizzato. Se lo supera, o se Datatrans rifiuta l'acquisizione o l'annullamento, il motivo viene aggiunto alle note dell'ordine.

On hold after payment: Datatrans ha comunicato un importo o una valuta diversi dal totale dell'ordine (per esempio, l'ordine è stato modificato dopo l'avvio del pagamento), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega. Controlla la transazione nel Web Admin di Datatrans ed evadi l'ordine o rimborsa il pagamento.

Failed: il pagamento non è riuscito o è stato rifiutato. Il cliente può riprovare.

Cancelled: l'autorizzazione è stata rilasciata, tramite l'azione dell'ordine o nel Web Admin di Datatrans.

Una notifica tardiva di errore o annullamento non modifica mai un ordine pagato. Se per un ordine già pagato arriva un secondo pagamento riuscito, l'ordine non viene modificato. Una nota avverte di un possibile doppio addebito e ti chiede di rimborsarlo in Datatrans, se necessario.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Datatrans. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato nell'ambiente in cui è stato effettuato il pagamento, quindi le credenziali di quell'ambiente devono essere impostate. Un rimborso ritentato non viene accreditato due volte. Se Datatrans non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'importo e l'ID della transazione di rimborso Datatrans.

Per un pagamento solo autorizzato, il rimborso dell'intero importo annulla l'autorizzazione. Un rimborso parziale non è possibile finché il pagamento non viene acquisito.

I rimborsi effettuati nel Web Admin di Datatrans non vengono registrati in WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza Refund via Datatrans.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Datatrans. 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 ricontrollare 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 suo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Datatrans 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 comunque il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare 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 rimborsi e acquisizioni funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Datatrans non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il Merchant ID e la password API dell'ambiente corrente siano impostati: i campi sandbox in modalità sandbox, altrimenti i campi di produzione. La pagina delle impostazioni elenca i campi mancanti.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: Datatrans non è riuscito a raggiungere l'URL del webhook e il cliente non è tornato al negozio. Verifica che il sito sia raggiungibile da internet tramite HTTPS e che nessun plugin di sicurezza o firewall blocchi le richieste a /wc-api/datatrans_payment_callback/. Verifica che la chiave di firma nelle impostazioni appartenga all'ambiente del pagamento. Attiva Logging e consulta WooCommerce > Status > Logs, origine wcp_datatrans_gateway.

Il webhook risponde Invalid signature: la chiave di firma HMAC nelle impostazioni non corrisponde a quella del Web Admin di Datatrans, oppure appartiene all'altro ambiente. Copia di nuovo la chiave.

Il webhook risponde Not configured o Verification failed: il webhook doveva essere verificato con l'API di stato di Datatrans, ma mancano le credenziali di quell'ambiente, oppure Datatrans non ha risposto. Datatrans ritenta il webhook.

La chiave di firma HMAC non viene salvata: la chiave deve essere una stringa esadecimale. Copiala di nuovo dal Web Admin di Datatrans.

Il cliente vede The payment could not be started: il Merchant ID o la password API sono errati, appartengono all'altro ambiente, oppure la valuta non è attiva per il tuo account Datatrans. Attiva Logging per vedere il motivo.

L'ordine è In sospeso dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati differivano dall'ordine, il pagamento è arrivato dopo l'annullamento dell'ordine, oppure il pagamento è solo autorizzato e attende l'acquisizione.

L'acquisizione non è possibile: il totale dell'ordine è superiore all'importo autorizzato. L'acquisizione usa il totale attuale dell'ordine, quindi riducilo all'importo autorizzato o a meno.

Il rimborso non riesce, con un messaggio sulle credenziali: il pagamento è stato effettuato nell'altro ambiente e le sue credenziali non sono impostate. Inseriscile e riprova. Per un pagamento autorizzato, rimborsa l'intero importo oppure acquisiscilo prima.

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 menziona il filtro wcp_datatrans_gateway_init_request, per esempio per limitare i metodi di pagamento mostrati nella pagina Datatrans.

Disinstallazione

Disattivare il plugin conserva 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. Le impostazioni del gateway vengono rimosse solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID transazione.

Datatrans è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Datatrans né approvato da Datatrans.