VibeFox dLocal for WooCommerce — Guida
Requisiti
WordPress: 5.8 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo.
PHP: 8.0 o successivo. Il plugin si rifiuta di attivarsi con una versione più vecchia di PHP o WordPress.
Accesso al sito: il tuo sito deve essere raggiungibile da Internet e usare HTTPS in ambiente live, perché dLocal Go possa consegnare le notifiche di pagamento. Un firewall, la modalità di manutenzione o l'autenticazione di base possono bloccarle.
Account dLocal Go: ti servono l'API key e l'API secret dalla dashboard di dLocal Go, sezione Payment integration: dashboard-sbx.dlocalgo.com per la sandbox, dashboard.dlocalgo.com per il live. Sandbox e live usano credenziali diverse. L'API enterprise dLocal Payments (credenziali X-Login / X-Trans-Key) è un prodotto diverso e non è supportata.
Paesi e valute: il plugin non li limita. È dLocal Go a decidere quali metodi di pagamento offrire per il paese del cliente e la valuta del negozio.
Chiave di licenza VibeFox: si acquista 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_dlocal_payment in /wp-content/plugins/ via FTP.
2. Fai clic su Activate. WooCommerce deve essere attivo.
3. Apri le impostazioni: WooCommerce > Settings > Payments > dLocal Go > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
4. Inserisci la tua chiave di licenza VibeFox nel blocco della licenza in cima alla pagina e fai clic su Activate.
5. Scegli l'Environment e incolla l'API key e l'API secret di quell'ambiente (vedi Configurazione).
6. Attiva Enable/Disable e salva. Prova un pagamento in sandbox, poi imposta Environment su Production.
Configurazione
Tutte le impostazioni sono in una sola pagina: WooCommerce > Settings > Payments > dLocal Go. Il titolo della pagina mostra SANDBOX o PRODUCTION. Finché non vengono inseriti l'API key e il secret dell'ambiente selezionato, la pagina avvisa che il metodo di pagamento è nascosto al checkout. Mentre è selezionata la sandbox e il gateway è attivo, mostra Sandbox mode is active: payments are simulated, no money is charged. Nell'elenco dei metodi di pagamento, dLocal Go è indicato come da configurare finché non vengono impostate le credenziali, e in sandbox mostra Test mode.
Generale
Enable/Disable: Enable dLocal Go attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: dLocal Go.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with local cards, bank transfer or cash via dLocal Go.
Credenziali API
Copia l'API key e l'API secret dalla dashboard di dLocal Go, Payment integration: dashboard-sbx.dlocalgo.com (sandbox) o dashboard.dlocalgo.com (live). Tutti i campi delle credenziali sono campi password.
Environment: quali credenziali e quali server di dLocal Go vengono usati.
Sandbox API Key: la tua API key sandbox di dLocal Go.
Sandbox API Secret: il tuo API secret sandbox di dLocal Go.
Production API Key: la tua API key live di dLocal Go.
Production API Secret: il tuo API secret live di dLocal Go.
Pagamento
Default country: dLocal Go mostra i metodi di pagamento del paese del cliente, preso dall'indirizzo di fatturazione e poi dall'indirizzo di spedizione. Questo paese viene usato quando l'ordine non ha né l'uno né l'altro. Predefinito: Uruguay.
Auto-complete orders: Set paid orders to "Completed" instead of "Processing". Lo stato viene impostato subito, con un solo gruppo di email. Predefinito: disattivato.
Notifiche (IPN)
Le notifiche comunicano al tuo negozio che un pagamento o un rimborso è cambiato. Il plugin invia gli URL di notifica a dLocal Go con ogni pagamento e rimborso, quindi non occorre configurare nulla nella dashboard di dLocal Go. Questa sezione delle impostazioni mostra entrambi gli URL:
Le notifiche vengono verificate con il tuo API secret (HMAC-SHA256). Le notifiche senza una firma valida vengono rifiutate. Dopodiché stato, importo e valuta del pagamento vengono sempre riletti dall'API di dLocal Go; il contenuto della notifica non viene considerato affidabile. Senza notifiche, un ordine viene aggiornato solo quando il cliente torna al negozio.
Avanzate
Debug log: Log API requests and notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_dlocal_payment, senza credenziali API né dati personali. Gli errori vengono sempre registrati. Predefinito: disattivato.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment data is kept). Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita dLocal Go) ed effettua l'ordine. Il plugin crea un pagamento dLocal Go per il totale dell'ordine nella valuta dell'ordine, con paese, nome, email e telefono del cliente, e invia il cliente alla pagina di pagamento di dLocal Go. Lì il cliente paga con un metodo del suo paese. Il pagamento appare sulla pagina di dLocal Go come Order # seguito dal numero d'ordine. In modalità sandbox il checkout mostra Sandbox mode: no real payment is made. sotto il metodo di pagamento.
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 dLocal Go: tramite la notifica firmata o tramite una richiesta lato server all'API di dLocal Go quando il cliente arriva su quella pagina.
Se il cliente lascia la pagina di dLocal Go senza pagare, torna al checkout (o alla pagina Pay for order) e vede The payment at dLocal Go was not completed. You can try again or choose another payment method. Se il pagamento è stato rifiutato o è scaduto, il messaggio è Your dLocal payment was not completed: it was declined or it expired. Please try again or choose another payment method. Se risulta che il pagamento è stato effettuato, il cliente viene inviato alla pagina di ordine ricevuto. Un link di pagamento precedente dello stesso ordine può ancora essere pagato dopo un nuovo tentativo.
Se dLocal Go non riesce ad avviare il pagamento, il cliente vede un breve messaggio senza dettagli tecnici, per esempio dLocal could not start the payment: seguito dal motivo indicato da dLocal, e può scegliere un altro metodo. Succede anche quando il paese del cliente e la valuta del negozio non sono abilitati nel tuo account dLocal Go. Il motivo tecnico viene scritto nel registro.
Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con l'archiviazione degli ordini ad alte prestazioni (HPOS) di WooCommerce.
Il plugin accetta solo pagamenti singoli sulla pagina di dLocal Go. Non prevede un modulo della carta sul tuo sito, carte salvate, abbonamenti né autorizzazione e acquisizione separate.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a dLocal Go e non ha ancora pagato, oppure il pagamento è in attesa presso dLocal Go (per esempio un voucher in contanti non ancora pagato). Ogni nuovo tentativo di pagamento viene annotato nell'ordine con il suo ID di pagamento dLocal, l'importo e l'ambiente.
Processing or Completed: il pagamento è stato confermato. L'ordine è In lavorazione (impostazione predefinita di WooCommerce), oppure Completato con Auto-complete orders attivo. L'ID transazione è l'ID di pagamento dLocal.
On hold: dLocal Go ha comunicato un importo o una valuta diversi dal totale dell'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota dell'ordine lo spiega. Confronta con la dashboard di dLocal Go ed evadi l'ordine o rimborsa il pagamento.
Failed: l'ultimo tentativo di pagamento è stato rifiutato o è scaduto. Il cliente può riprovare.
Cancelled: dLocal Go ha segnalato l'ultimo tentativo di pagamento come annullato.
Solo l'ultimo tentativo di pagamento può far fallire o annullare un ordine non pagato. Un ordine pagato non viene mai riaperto da una vecchia notifica. Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsare il pagamento duplicato nella dashboard di dLocal Go.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via dLocal Go. Sono supportati rimborsi totali e parziali per gli ordini pagati tramite dLocal Go. Il rimborso viene inviato all'ambiente in cui è stato effettuato il pagamento, con le credenziali di quell'ambiente. Se dLocal Go non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso accettato viene aggiunto alle note dell'ordine con l'ID e lo stato del rimborso.
dLocal Go comunica poi lo stato finale del rimborso tramite la notifica di rimborso, e lo stato viene aggiunto alle note dell'ordine. Se in seguito dLocal Go rifiuta o annulla un rimborso che aveva accettato, la nota avvisa che il denaro non è stato restituito al cliente. Controlla il rimborso WooCommerce registrato per esso: eliminalo e rimborsa di nuovo, oppure rimborsa il cliente in un altro modo.
I rimborsi effettuati nella dashboard di dLocal Go non vengono registrati come rimborsi WooCommerce e di solito non aggiungono note all'ordine. Se necessario, crea un rimborso manuale in WooCommerce senza Refund via dLocal Go.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > dLocal Go. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui 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 lo slot del suo dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, dLocal Go 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 continuano a vedere il metodo di pagamento, contrassegnato (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i 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
dLocal Go non appare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo e che l'API key e l'API secret dell'Environment selezionato siano impostati. La pagina delle impostazioni mostra un avviso quando mancano.
Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: dLocal Go non è riuscito a raggiungere l'URL di notifica (firewall, modalità di manutenzione, autenticazione di base) e il cliente non è tornato alla pagina di ordine ricevuto. Controlla WooCommerce > Status > Logs, origine wcp_dlocal_payment, e il pagamento nella dashboard di dLocal Go. Appena arriva una notifica o il cliente apre la pagina di ordine ricevuto, l'ordine viene aggiornato.
La notifica risponde Missing signature o Invalid signature: l'API key e il secret nelle impostazioni non appartengono all'account che ha inviato la notifica. Le notifiche vengono verificate con le credenziali di entrambi gli ambienti, quindi i pagamenti avviati prima di cambiare Environment vengono comunque confermati, purché le credenziali del loro ambiente restino nelle impostazioni.
La notifica risponde Gateway not configured: mancano le credenziali dell'ambiente selezionato. dLocal Go ritenta la notifica.
La notifica risponde API verification failed: non è stato possibile raggiungere l'API di dLocal Go per leggere il pagamento. dLocal Go ritenta la notifica.
La notifica risponde Order not found: il pagamento non appartiene a un ordine di questo negozio, per esempio è stato creato da un altro sito con lo stesso account dLocal Go.
Il cliente vede This payment method is temporarily unavailable: dLocal Go ha rifiutato l'API key o il secret. Controlla le credenziali dell'ambiente selezionato.
L'ordine è In sospeso dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi dall'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Evadi l'ordine o rimborsa il pagamento.
Il rimborso non riesce con un messaggio sulle credenziali mancanti: il pagamento è stato effettuato nell'altro ambiente e le sue credenziali non sono impostate. Inseriscile e riprova.
Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata 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 delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Per gli sviluppatori, la documentazione del plugin elenca i filtri dlocal_p_payment_data, dlocal_p_currency_decimals e dlocal_p_icon.
Disinstallazione
La disattivazione del 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 e i registri vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.
dLocal è un marchio del rispettivo proprietario. Questo plugin non è affiliato a dLocal né approvato da dLocal.