VibeFox Braintree 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 Braintree: ti servono il Merchant ID, la Public Key e la Private Key del tuo account Braintree. Si trovano nel Braintree Control Panel (sandbox: sandbox.braintreegateway.com, live: www.braintreegateway.com) sotto l'icona dell'ingranaggio, API, API Keys. Gli account sandbox e live hanno chiavi diverse. 3-D Secure deve essere attivo per il tuo account commerciante Braintree, a meno che tu non imposti 3-D Secure su Disabled. Non serve nessun webhook: i pagamenti con carta vengono confermati subito.

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 Braintree Gateway nell'elenco dei moduli e fai clic su Configure.

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

4. Copia il Merchant ID, la Public Key e la Private Key dal Braintree Control Panel nei campi sandbox o live.

5. Attiva Enable/Disable e fai clic su Save. Lascia attivo Sandbox mode ed effettua un ordine di prova con una carta di test Braintree sandbox. Poi disattiva Sandbox mode per accettare pagamenti reali con le credenziali live.

All'installazione il modulo crea due stati dell'ordine: Braintree payment authorized e Braintree 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 Braintree Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Quando il metodo di pagamento è attivo ma manca il Merchant ID, la Public Key o la Private Key dell'ambiente selezionato, la pagina ti avvisa che il metodo di pagamento è nascosto al checkout finché non vengono compilati. Mentre la modalità sandbox è attiva, la pagina mostra Sandbox mode is on: test payments, no real money.

Braintree

Enable/Disable: Enable Braintree card payments attiva o disattiva il metodo di pagamento. Predefinito: off.

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 / debit card. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your credit or debit card via Braintree.

Credenziali API

Accedi al Braintree Control Panel (sandbox o live), fai clic sull'icona dell'ingranaggio, quindi su API e API Keys. Lì sono elencate la Public Key e la Private Key, e il Merchant ID è mostrato nella stessa pagina. La pagina mostra solo i campi delle credenziali dell'ambiente selezionato; entrambi i set restano salvati.

Sandbox mode: usa la sandbox Braintree (pagamenti di prova, nessun denaro reale). Predefinito: on. Disattivalo per accettare pagamenti reali con le credenziali live. Rimborsi, acquisizioni e annullamenti usano sempre l'ambiente in cui l'ordine è stato pagato. Quando è attiva, i clienti vedono SANDBOX / TEST MODE — no real money is charged. sotto il metodo di pagamento.

Sandbox Merchant ID e Live Merchant ID: il Merchant ID dell'account sandbox o live.

Sandbox Public Key e Live Public Key: la Public Key di quell'account.

Sandbox Private Key e Live Private Key: la Private Key di quell'account. Le Private Key salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Sandbox merchant account ID(s) e Live merchant account ID(s): opzionali. Braintree addebita nella valuta dell'account commerciante. Lascia vuoto per usare l'account commerciante predefinito, inserisci un ID (per esempio mystore_EUR) oppure uno per valuta: EUR=mystore_EUR, USD=mystore_USD. Se la valuta addebitata non corrisponde a quella dell'ordine, la transazione viene annullata automaticamente e il cliente non viene addebitato.

Clear saved private keys: seleziona Sandbox Private Key o Live Private Key e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Pagamento

Transaction type: come viene addebitata la carta.

3-D Secure: il 3-D Secure 2 (Strong Customer Authentication) è obbligatorio per la maggior parte dei pagamenti con carta nello SEE e nel Regno Unito. Deve essere attivo anche per il tuo account Braintree (contatta il supporto Braintree se i pagamenti falliscono con un errore di configurazione 3-D Secure).

Il risultato di 3-D Secure viene verificato sul server, non solo nel browser, prima dell'addebito sulla carta.

Avanzate

Debug log: registra anche le chiamate API e i passaggi del pagamento in logs/wc_btg_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche se l'opzione è disattivata. Il registro non contiene mai chiavi API, dati della carta o dei clienti. 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 il registro. Le transazioni, i rimborsi e gli stati dell'ordine Braintree restano sempre, quindi gli ordini pagati in precedenza possono essere ancora rimborsati, acquisiti o annullati dopo una reinstallazione. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / debit card) e inserisce la carta nel modulo Braintree all'interno dell'opzione di pagamento. Il modulo viene caricato da Braintree solo nella pagina del checkout e usa la lingua del negozio. Con 3-D Secure attivo, il cliente completa la verifica della banca quando effettua l'ordine; il totale del carrello, l'e-mail e l'indirizzo di fatturazione vengono passati a questa verifica.

Il modulo addebita poi il token monouso tramite l'API Braintree per il totale del carrello nella valuta del carrello, usando il numero del carrello come ID ordine in Braintree. Prima di questo punto non esiste alcun ordine. L'importo e la valuta addebitati vengono confrontati con il carrello. L'ordine viene creato solo dopo che Braintree ha accettato il pagamento, e il cliente vede la pagina standard di conferma dell'ordine di PrestaShop.

Se il pagamento non va a buon fine, non viene creato alcun ordine, il motivo viene scritto nel registro del modulo e il cliente resta nella fase di pagamento con un messaggio, per esempio Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. oppure The card security code or billing address could not be verified. Please check your details and try again. Il cliente può riprovare subito. Se la valuta o l'importo addebitato non corrispondono al carrello, la transazione viene annullata e il cliente vede This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.

Un carrello non viene mai addebitato due volte. Un secondo invio mentre il pagamento è in corso mostra This order is already being paid. Please wait a moment and check your e-mail before trying again. Se la carta è stata addebitata ma PrestaShop non è riuscito a creare l'ordine, il cliente vede Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Il tentativo successivo per lo stesso carrello crea l'ordine dalla transazione salvata, senza addebitare di nuovo.

Il modulo accetta solo pagamenti con carta. Non prevede carte salvate, abbonamenti o pagamenti ricorrenti, né PayPal, Venmo, Apple Pay, Google Pay o metodi di pagamento locali, e non utilizza webhook Braintree.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il pagamento non è stato effettuato o è stato rifiutato. Esiste solo il carrello.

Payment accepted: la carta è stata addebitata (Sale), oppure un'autorizzazione è stata acquisita. Il pagamento viene registrato con l'ID transazione Braintree, e una nota privata nei messaggi dell'ordine mostra l'importo, l'ID transazione e il risultato di 3-D Secure.

Braintree payment authorized: i fondi sono solo autorizzati (Authorize only). Nessun pagamento viene registrato finché non lo acquisisci.

Braintree payment on hold: Braintree ha restituito uno stato della transazione inatteso, oppure un addebito in una valuta o per un importo errati non è stato possibile annullarlo automaticamente. La nota spiega cosa controllare nel Braintree Control Panel.

Canceled: un'autorizzazione è stata annullata.

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

Se arriva un'altra transazione per un ordine già creato, l'ordine non viene modificato. Una nota ti chiede di controllarla nel Braintree Control Panel e di annullarla o rimborsarla.

Blocco Braintree payment

La pagina dell'ordine mostra un blocco Braintree payment con l'ID transazione (collegato alla transazione nel Braintree Control Panel del rispettivo ambiente), lo stato della transazione, l'importo e l'account commerciante, il risultato di 3-D Secure, l'importo addebitato e rimborsato, un badge Sandbox per i pagamenti sandbox e lo storico dei rimborsi. I pulsanti del blocco richiedono il permesso di modificare gli ordini; non serve l'accesso alle pagine Modules.

Acquisizione e annullamento

Per un ordine con lo stato Braintree payment authorized, fai clic su Capture Braintree payment per addebitare il totale dell'ordine, oppure su Void Braintree authorization per rilasciare l'importo bloccato. L'acquisizione imposta l'ordine su Payment accepted e registra il pagamento; l'annullamento lo imposta su Canceled. Se l'azione non riesce, l'errore viene mostrato nel blocco e aggiunto alle note dell'ordine.

Rimborsi

Nel blocco Braintree payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Braintree. Conferma la domanda Refund this amount through Braintree? This cannot be undone. Sono supportati rimborsi totali e parziali. I rimborsi vengono eseguiti nell'importo e nella valuta addebitati da Braintree, quindi dopo una differenza di importo o di valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato. Braintree rimborsa solo le transazioni regolate, di solito entro 24 ore. Prima della regolazione, un rimborso totale viene eseguito come annullamento; un rimborso parziale fallisce allora con un messaggio che invita ad attendere la regolazione. Il rimborso viene inviato all'ambiente (sandbox o live) del pagamento, quindi le credenziali di quell'ambiente devono essere impostate. Se Braintree non accetta il rimborso, il blocco mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note. 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 Braintree. Le contestazioni (chargeback), i rifiuti in fase di regolamento e i rimborsi effettuati nel Braintree Control Panel non vengono sincronizzati con PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Braintree Gateway è il primo blocco di Modules > Module Manager > VibeFox Braintree 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 di essi ci sono la riga Product: presta-payment-braintree 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 cambiare la chiave. I testi del blocco seguono la lingua del back office (sono incluse le lingue inglese e russa).

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 oppure License expired on con 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 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, Braintree 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 hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche a 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 acquisizioni, annullamenti e rimborsi continuano a funzionare.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto 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 alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Braintree non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che l'ambiente selezionato abbia un Merchant ID, una Public Key e una Private Key. La pagina delle impostazioni mostra un avviso quando manca una chiave. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il Paese del cliente e il gruppo di clienti.

La carta è stata addebitata, ma non è stato creato alcun ordine: i pagamenti con carta vengono confermati subito, senza webhook. Controlla il campo Log nella pagina del modulo. Se il registro dice che la risposta di Braintree è andata persa, controlla nel Braintree Control Panel se esiste una transazione con il numero del carrello come ID ordine prima di accettare un altro pagamento. Se l'ordine non è stato creato dopo l'addebito, il tentativo di pagamento successivo per lo stesso carrello lo crea senza addebitare di nuovo.

Il modulo della carta mostra Could not initialize payment form: le chiavi dell'ambiente selezionato sono errate, oppure l'ID dell'account commerciante non esiste in quell'account. Controlla le chiavi e gli ID degli account commerciante, quindi ricarica la pagina.

3-D Secure fallisce per ogni pagamento: 3-D Secure deve essere attivo per il tuo account commerciante Braintree. Contatta il supporto Braintree oppure imposta 3-D Secure su Disabled (sconsigliato nello SEE e nel Regno Unito, dove la SCA è obbligatoria).

Al cliente viene comunicato che il pagamento non può essere elaborato nella valuta dell'ordine: Braintree ha addebitato nella valuta dell'account commerciante. Inserisci l'ID dell'account commerciante per la valuta del carrello nel campo dell'account commerciante dell'ambiente attuale.

Il cliente vede il messaggio The order total must be greater than zero to pay by card: il totale del carrello è zero, per esempio dopo un buono sconto. Questi ordini non possono essere pagati con carta.

Un rimborso parziale fallisce subito dopo il pagamento: Braintree può rimborsare solo le transazioni regolate, di solito entro 24 ore. Rimborsa l'intero importo per annullare ora la transazione, oppure effettua il rimborso parziale dopo la regolazione.

Rimborso, acquisizione o annullamento fallisce con un messaggio sull'ambiente: il pagamento è stato effettuato nell'ambiente sandbox o live, e le credenziali di quell'ambiente non sono impostate. Inseriscile e riprova.

Disinstallazione

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

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