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

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.

Negozio raggiungibile: Datatrans invia i webhook dai propri server, quindi il tuo negozio deve essere raggiungibile da internet.

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 Datatrans 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 alto nella pagina Configure e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci le credenziali sandbox dal Web Admin sandbox di Datatrans (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Effettua un pagamento di prova in modalità sandbox. Quando tutto funziona, inserisci le credenziali di produzione e disattiva Sandbox mode.

All'installazione il modulo crea lo stato dell'ordine Datatrans payment on hold. PrestaShop attiva di default il nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences; Datatrans viene mostrato solo per le valute consentite lì.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Quando il metodo di pagamento è attivo ma l'ambiente corrente non ha Merchant ID o password API, la pagina mostra Datatrans is hidden at checkout until these settings are filled in: con i campi mancanti. Mentre la modalità sandbox è attiva, la pagina mostra Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Datatrans

Enable/Disable: Enable Datatrans Payment 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: Datatrans. Obbligatorio.

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

Sandbox mode: usa la sandbox di Datatrans: pagamenti di prova, nessun denaro reale. Il selettore cambia sia i server di Datatrans sia le credenziali usate per i nuovi pagamenti. Predefinito: attivo. Disattivalo per accettare pagamenti reali. Finché è attivo, i clienti vedono Sandbox mode: no real payment is taken. sotto il metodo di pagamento. Rimborsi e acquisizioni usano sempre l'ambiente in cui è stato effettuato il pagamento, qualunque sia la posizione di questo selettore.

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 dell'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 tramite 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 dell'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 tramite l'API di stato di Datatrans.

Le password e le chiavi di firma salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo. Una chiave di firma deve essere una stringa esadecimale così come rilasciata da Datatrans. Qualsiasi altro valore non viene salvato: la pagina mostra un errore e mantiene il valore precedente, mentre le altre impostazioni vengono salvate.

Clear saved secrets: spunta una password o una chiave di firma e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

URL del webhook

La sezione mostra l'URL del webhook del tuo negozio. Con gli URL semplificati ha questo aspetto: https://your-shop/module/wcp_datatrans_gateway/webhook, eventualmente con un codice lingua come /en/. Il modulo invia questo URL a Datatrans con ogni transazione, quindi non devi inserirlo da nessuna parte. Puoi anche inserirlo nelle impostazioni dei webhook del Web Admin di Datatrans per ricevere gli aggiornamenti di acquisizioni e annullamenti effettuati lì; copialo esattamente come lo mostrano le impostazioni. I rimborsi effettuati nel Web Admin di Datatrans non vengono riportati nell'ordine.

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

Con una chiave di firma HMAC, ogni webhook viene verificato tramite la sua intestazione Datatrans-Signature con la chiave di firma dell'ambiente in cui è stato effettuato il pagamento. I webhook senza una firma valida vengono rifiutati. Senza chiave di firma, il modulo non si fida del contenuto del webhook e controlla ogni webhook tramite l'API di stato di Datatrans. Senza il webhook, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Elaborazione del pagamento

Auto settle: acquisisce (salda) i pagamenti immediatamente. Se disattivato, i pagamenti vengono solo autorizzati: l'ordine va in Datatrans payment on hold e lo acquisisci più tardi con Capture Datatrans payment nel blocco Datatrans dell'ordine, oppure lo rilasci con Cancel Datatrans authorization. Predefinito: attivo.

Order status after payment: lo stato dell'ordine una volta saldato il pagamento.

I pagamenti solo autorizzati e le discordanze di importo o valuta finiscono sempre in Datatrans payment on hold.

Avanzate

Logging: scrive gli eventi di pagamento e le chiamate API in logs/datatrans_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche quando questo selettore è disattivato. Non vengono scritte chiavi, dati delle carte né dati dei clienti. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro, con un pulsante per svuotarlo.

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le sue impostazioni e il registro. I dati di pagamento Datatrans degli ordini (transazioni, rimborsi) e lo stato dell'ordine restano sempre. Predefinito: disattivato.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (di default Datatrans) e vede la nota You will be redirected to the Datatrans payment page to complete the payment securely. Dopo la conferma, il modulo crea una transazione Datatrans per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento di Datatrans. La pagina si apre in tedesco, inglese, francese o italiano se la lingua del negozio è una di queste. Lì il cliente paga con qualsiasi metodo attivo nel tuo account Datatrans. In questo momento non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Datatrans lo conferma: tramite il webhook oppure tramite una richiesta lato server all'API di stato di Datatrans quando il cliente torna. L'indirizzo di ritorno contiene la chiave sicura del carrello, e il ritorno in sé non crea mai un ordine. Poi l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Datatrans has been received. Per un pagamento solo autorizzato la pagina mostra Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. Se Datatrans non ha ancora confermato il pagamento, una pagina Payment confirmation mostra Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. con il pulsante Check again; il webhook crea l'ordine appena arriva.

Se il cliente annulla nella pagina di Datatrans, torna al checkout con The payment was canceled. You can try again or choose another payment method. Se il pagamento non è riuscito, il messaggio è The payment was not completed. Please try again or choose another payment method. Il carrello viene conservato. Un nuovo tentativo crea una nuova transazione Datatrans; un pagamento tardivo di un tentativo precedente viene comunque riconosciuto.

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

Il webhook funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

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

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Datatrans e non ha pagato, il pagamento non è riuscito o è stato annullato, oppure Datatrans non lo ha ancora confermato. Esiste solo il carrello.

Payment accepted, Delivered o Datatrans payment on hold: il pagamento è stato saldato. Lo stato segue Order status after payment. Il pagamento viene registrato con l'ID transazione Datatrans, e una nota mostra importo, metodo di pagamento, ambiente e come è stato confermato (webhook o ritorno).

Datatrans payment on hold dopo un'autorizzazione: Auto settle è disattivato e il pagamento è solo autorizzato. Acquisiscilo o annullalo nel blocco dell'ordine.

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

Canceled: l'autorizzazione è stata rilasciata, nel blocco dell'ordine o nel Web Admin di Datatrans.

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

Se arriva un secondo pagamento per un carrello già pagato o autorizzato, l'ordine non cambia. Una nota ti chiede di verificarlo e di rimborsare il duplicato in Datatrans. Una transazione fallita o annullata non declassa mai un ordine pagato.

Blocco Datatrans payment

La pagina dell'ordine mostra un blocco Datatrans payment con l'ID transazione, lo stato Datatrans, il metodo di pagamento, l'importo, gli importi pagati e rimborsati, un badge Sandbox per i pagamenti sandbox, lo storico dei rimborsi e le Datatrans notes dell'ordine. Le azioni del blocco richiedono il permesso di modificare gli ordini; non serve l'accesso alle pagine dei moduli.

Acquisizione e annullamento

Per un pagamento solo autorizzato il blocco mostra Capture Datatrans payment e Cancel Datatrans authorization. L'acquisizione salda il pagamento per il totale attuale dell'ordine, che non deve superare l'importo autorizzato; poi l'ordine passa allo stato di Order status after payment. L'annullamento rilascia l'autorizzazione e imposta l'ordine su Canceled. Entrambe le operazioni vanno all'ambiente del pagamento. Se Datatrans rifiuta, il blocco mostra l'errore e viene aggiunta una nota.

Rimborsi

Nel blocco Datatrans payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Datatrans. Conferma la domanda Refund this amount through Datatrans? This cannot be undone. Sono supportati rimborsi totali e parziali, fino all'importo effettivamente addebitato da Datatrans meno i rimborsi precedenti. Il rimborso viene inviato all'ambiente del pagamento, quindi devono essere impostati il Merchant ID e la password API di quell'ambiente. Un rimborso ritentato non viene accreditato due volte. Se Datatrans non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico e alle note con l'ID transazione di rimborso Datatrans. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato.

Per un pagamento solo autorizzato non è stato ancora addebitato nulla: si può "rimborsare" solo l'importo totale, che annulla l'autorizzazione. I rimborsi sono disponibili quando Datatrans ha saldato il pagamento; un'autorizzazione con importo non corrispondente non può essere rimborsata finché non viene saldata.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Datatrans. I rimborsi effettuati nel Web Admin di Datatrans non vengono registrati in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Datatrans Gateway è il primo blocco della pagina Modules > Module Manager > VibeFox Datatrans Gateway > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per 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 compaiono la riga Product: presta-payment-datatrans e il collegamento 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 cambiare 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, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato un posto 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 posto dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Datatrans 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 vengono toccati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

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 alla 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

Datatrans does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che l'ambiente corrente abbia il Merchant ID e la password API: i campi sandbox in modalità sandbox, i campi di produzione altrimenti. La pagina delle impostazioni elenca i campi mancanti. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

The payment went through, but no order was created: Datatrans non è riuscito a raggiungere l'URL del webhook e il cliente non è tornato nel negozio. Verifica che il negozio sia raggiungibile da internet e che nessun firewall blocchi le richieste all'URL del webhook. Verifica che la chiave di firma nelle impostazioni appartenga all'ambiente del pagamento. Controlla il campo Log nella pagina del modulo.

Webhook answers Invalid signature: la chiave di firma HMAC nelle impostazioni non coincide con quella del Web Admin di Datatrans, oppure appartiene all'altro ambiente. Copiala di nuovo.

Webhook answers Not configured or Verification failed: il webhook doveva essere verificato tramite l'API di stato di Datatrans, ma mancano le credenziali di quell'ambiente, oppure Datatrans non ha risposto. Datatrans ritenta il webhook.

Webhook answers Busy, retry: l'ordine era in fase di conferma da un'altra richiesta nello stesso momento, oppure l'ordine non è stato possibile crearlo (ad esempio perché il modulo è disattivato). Datatrans ritenta il webhook. Il registro mostra il motivo.

The webhook URL shows Method not allowed in the browser: è normale. L'URL accetta solo richieste da Datatrans.

The HMAC sign key is not saved: la chiave deve essere una stringa esadecimale. Copiala di nuovo dal Web Admin di Datatrans.

The customer sees Datatrans payments are not configured yet: manca il Merchant ID o la password API dell'ambiente corrente.

The customer sees The payment could not be started: controlla il campo Log. Le cause più comuni sono un Merchant ID o una password API errati, oppure credenziali dell'ambiente sbagliato.

Order is Datatrans payment on hold after payment: leggi le Datatrans notes nel blocco dell'ordine (vedi Stati dell'ordine), poi completa l'ordine oppure rimborsa il pagamento.

Capture is refused: il totale dell'ordine è superiore all'importo autorizzato. Datatrans non può saldare più di quanto autorizzato.

Refund or capture fails with a message about missing credentials: il pagamento è stato effettuato nell'altro ambiente, e il suo Merchant ID o la sua password API non sono impostati. Inseriscili e riprova.

Disinstallazione

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

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