VibeFox Braintree for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 8.0 o successivo, installato e attivo.
PHP: 8.0 o successivo.
HTTPS: il tuo sito deve usare HTTPS.
Account Braintree: ti servono Merchant ID, Public Key e 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. Il 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 alcun webhook.
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo 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_braintree_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Braintree > 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. Copia Merchant ID, Public Key e Private Key dal Braintree Control Panel nei campi sandbox o live.
6. Attiva Enable/Disable. Lascia attivo Sandbox mode ed effettua un ordine di prova con una carta di test Braintree, per esempio 4111 1111 1111 1111 con una data di scadenza futura qualsiasi. Per il 3-D Secure usa le carte di test 3-D Secure di Braintree.
7. Deseleziona Sandbox mode per accettare pagamenti reali con le credenziali live.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Braintree. Quando il gateway è attivo ma mancano Merchant ID, Public Key o Private Key della modalità selezionata, la pagina ti avvisa che il metodo di pagamento è nascosto al checkout finché non li compili. La pagina mostra solo i campi delle credenziali della modalità selezionata; entrambi i gruppi restano salvati.
Generali
Enable/Disable: Enable Braintree card payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Credit / debit card.
Description: il testo mostrato sopra il modulo della carta 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, poi su API e API Keys. Le chiavi pubblica e privata sono elencate lì, e il Merchant ID è mostrato nella stessa pagina.
Sandbox mode: Use the Braintree sandbox (test payments, no real money). Predefinito: attivato. Deseleziona per accettare pagamenti reali con le credenziali live. Rimborsi, acquisizioni e annullamenti usano sempre l'ambiente in cui l'ordine è stato pagato.
Sandbox Merchant ID e Live Merchant ID: il Merchant ID dell'account sandbox o live.
Sandbox Public Key e Live Public Key: la chiave pubblica di quell'account.
Sandbox Private Key e Live Private Key: la chiave privata di quell'account.
Sandbox merchant account ID(s) e Live merchant account ID(s): facoltativi. 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.
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.
Avanzate
Debug log: Also log API calls and payment steps (errors are always logged). I registri si trovano in WooCommerce > Status > Logs, origine wcp_braintree_gateway. Non contengono mai chiavi API, dati della carta o dei clienti. Predefinito: disattivato.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / debit card) e inserisce la carta nel modulo Braintree nella pagina del checkout. In modalità sandbox il modulo mostra SANDBOX / TEST MODE — no real money is charged. Con il 3-D Secure attivo, il cliente completa la verifica della banca quando effettua l'ordine.
Il plugin addebita il token monouso tramite l'API Braintree per il totale dell'ordine nella valuta dell'ordine, con il numero dell'ordine come ID ordine. L'ordine viene segnato come pagato solo in base alla risposta autenticata di Braintree, dopo aver verificato importo e valuta addebitati rispetto all'ordine. Se il pagamento viene approvato, il cliente va alla pagina Ordine ricevuto. I pagamenti con carta non richiedono un webhook: il risultato è noto subito.
Se il pagamento non riesce, l'ordine resta In attesa di pagamento, il motivo viene aggiunto alle note dell'ordine e il cliente vede un messaggio chiaro, 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 addebitata non corrisponde a quella dell'ordine, 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 ordine 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.
Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin accetta solo pagamenti con carta. Non prevede carte salvate (vaulting), WooCommerce Subscriptions o pre-ordini, PayPal, Venmo, Apple Pay, Google Pay, ACH o altri metodi di pagamento locali, webhook Braintree, né dati Level 2/3, righe di articoli o Fastlane.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il pagamento non è ancora stato effettuato oppure è stato rifiutato.
Processing or Completed: la carta è stata addebitata (Sale), oppure un'autorizzazione è stata acquisita. WooCommerce imposta In lavorazione, oppure Completato per gli ordini con soli prodotti virtuali scaricabili. La nota dell'ordine mostra l'importo, l'ID transazione e il risultato del 3-D Secure. L'ID transazione è quello di Braintree e, nella schermata dell'ordine, collega alla transazione nel Braintree Control Panel.
On hold: i fondi sono solo autorizzati (Authorize only). Un ordine viene messo in sospeso anche quando Braintree restituisce uno stato di transazione inatteso, oppure quando un addebito in valuta errata non può essere annullato automaticamente. La nota dell'ordine spiega cosa verificare nel Braintree Control Panel.
Cancelled: un'autorizzazione è stata annullata con Void Braintree authorization.
Acquisizione e annullamento
Per un ordine con un'autorizzazione, apri l'ordine e scegli Capture Braintree payment o Void Braintree authorization tra le azioni dell'ordine, poi fai clic sul pulsante di aggiornamento. L'acquisizione segna l'ordine come pagato; l'annullamento annulla l'ordine e libera l'importo bloccato sulla carta del cliente. Se l'azione non riesce, l'errore viene mostrato nella schermata dell'ordine e aggiunto alle note dell'ordine.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit / debit card (il pulsante riporta il titolo del tuo metodo di pagamento). Sono supportati rimborsi totali e parziali. Braintree può rimborsare solo transazioni regolate, di solito entro 24 ore. Prima del regolamento, un rimborso totale viene eseguito come annullamento; in quel caso un rimborso parziale non riesce, con un messaggio che invita ad attendere il regolamento. Il rimborso viene inviato all'ambiente (sandbox o live) in cui l'ordine è stato pagato. Se Braintree non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso o un annullamento riuscito viene aggiunto alle note dell'ordine.
Le contestazioni (chargeback) e i rifiuti in fase di regolamento non vengono sincronizzati con WooCommerce. Controllali nel Braintree Control Panel.
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 > Braintree. 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 verificare di nuovo 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 solo dominio. Rimuovere la chiave da un sito non libera il posto del dominio. Liberalo 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: acquisizioni, annullamenti e rimborsi funzionano.
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
Braintree non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità selezionata abbia Merchant ID, Public Key e Private Key. La pagina delle impostazioni mostra un avviso quando manca una chiave.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: con le carte la conferma è immediata, senza webhook. Se la nota dell'ordine dice che la risposta di Braintree è andata persa, controlla nel Braintree Control Panel una transazione con questo numero d'ordine prima di accettare un altro pagamento. Attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_braintree_gateway.
Il modulo della carta mostra Could not initialize payment form: le chiavi della modalità selezionata sono errate, oppure l'ID dell'account commerciante non esiste in quell'account. Controlla le chiavi e gli ID degli account commerciante, poi ricarica la pagina.
Il 3-D Secure non funziona per nessun pagamento: il 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).
Il cliente riceve il messaggio 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 dell'ordine nel campo account commerciante della modalità corrente.
Un rimborso parziale non riesce subito dopo il pagamento: Braintree può rimborsare solo transazioni regolate, di solito entro 24 ore. Rimborsa l'intero importo per annullare subito la transazione, oppure fai il rimborso parziale dopo il regolamento.
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.
Disinstallazione
Disattivare il plugin mantiene 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. Impostazioni del gateway e registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. I dati Braintree salvati negli ordini vengono sempre conservati, perché servono per i rimborsi dopo una reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.
Braintree è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Braintree.