VibeFox dLocal for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni di PHP più vecchie.

Accesso al negozio: il tuo negozio deve essere raggiungibile da Internet e usare HTTPS in produzione, così che dLocal Go possa inviare le notifiche di pagamento.

Account dLocal Go: ti servono la chiave API e il secret API dalla dashboard di dLocal Go, sezione Payment integration: dashboard-sbx.dlocalgo.com per la sandbox, dashboard.dlocalgo.com per la produzione. Sandbox e produzione usano credenziali diverse. L'API enterprise dLocal Payments (credenziali X-Login / X-Trans-Key) è un prodotto diverso e non è supportata.

Paesi e valute: il modulo non li limita. dLocal Go decide quali metodi di pagamento offrire per il paese del cliente e la valuta del carrello. Si applicano solo le restrizioni di pagamento di PrestaShop.

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 clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova VibeFox dLocal Payment più tardi nell'elenco dei moduli e clicca su Configure.

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

4. Scegli l'Environment e incolla la chiave API e il secret API di quell'ambiente (vedi Configurazione).

5. Attiva Enable/Disable e clicca su Save. Prova un pagamento in sandbox, poi imposta Environment su Production.

All'installazione il modulo crea lo stato dell'ordine dLocal payment on hold. PrestaShop offre il 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 dLocal Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Il titolo della prima sezione mostra SANDBOX o PRODUCTION. Finché non inserisci la chiave API e il secret dell'ambiente selezionato, la pagina ti avvisa che il metodo di pagamento è nascosto al checkout, per esempio Enter the sandbox API key and secret: until then the payment method is hidden at checkout. Quando la sandbox è selezionata e il metodo di pagamento è attivo, compare Sandbox mode is active: payments are simulated, no money is charged.

dLocal Go

Enable/Disable: Enable dLocal Go 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: dLocal Go. Obbligatorio.

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 la chiave API e il secret API dalla dashboard di dLocal Go, Payment integration: dashboard-sbx.dlocalgo.com (sandbox) o dashboard.dlocalgo.com (produzione). La sezione contiene i link a entrambe le dashboard.

Environment: quali credenziali e quali server di dLocal Go vengono usati per i nuovi pagamenti.

Rimborsi e notifiche di un pagamento usano sempre le credenziali dell'ambiente in cui è stato effettuato, quindi conserva le credenziali dell'altro ambiente finché i suoi pagamenti sono ancora aperti o potrebbero essere rimborsati.

Sandbox API Key: la tua chiave API sandbox di dLocal Go.

Sandbox API Secret: il tuo secret API sandbox di dLocal Go.

Production API Key: la tua chiave API di produzione di dLocal Go.

Production API Secret: il tuo secret API di produzione di dLocal Go.

Le chiavi e i secret salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved credentials: spunta una chiave o un secret e clicca su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Pagamento

Default country: dLocal Go mostra i metodi di pagamento del paese del cliente, preso dall'indirizzo di fatturazione e poi da quello di spedizione. Questo paese viene usato quando il carrello non ha nessuno dei due. Predefinito: Uruguay.

Auto-complete orders: imposta gli ordini pagati su Delivered invece che su Payment accepted. Lo stato viene impostato subito, con un unico cambio di stato. Predefinito: disattivato.

Notifications (IPN): le notifiche informano il tuo negozio che un pagamento o un rimborso è cambiato. Il modulo invia gli URL di notifica a dLocal Go con ogni pagamento e ogni rimborso, quindi non c'è nulla da configurare nella dashboard di dLocal Go. Questo campo mostra entrambi gli URL:

Le notifiche vengono verificate con il tuo secret API (HMAC-SHA256). Le notifiche senza una firma valida vengono rifiutate. Una notifica deve essere firmata con le credenziali dell'ambiente in cui è stato effettuato il pagamento. Dopodiché stato, importo e valuta del pagamento vengono sempre riletti dall'API di dLocal Go; il contenuto della notifica non viene considerato attendibile. Senza notifiche, l'ordine viene creato solo quando il cliente torna nel negozio.

Avanzate

Debug log: scrive le richieste e le notifiche di dLocal Go in logs/dlocal_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Credenziali API e dati personali non vengono registrati. Errori e avvisi vengono sempre scritti; le altre voci solo mentre questa opzione è attiva. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il registro. I dati di pagamento degli ordini (pagamenti e rimborsi dLocal) e lo stato dell'ordine dLocal payment on hold restano sempre, così gli ordini esistenti continuano a funzionare. Predefinito: disattivato.

Checkout

Al momento del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita dLocal Go). In modalità sandbox il checkout mostra Sandbox mode: no real payment is made. sotto il metodo di pagamento. Dopo la conferma, il modulo crea un pagamento dLocal Go per il totale del carrello nella valuta del carrello, con il paese, il nome, l'email e il 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 compare sulla pagina di dLocal Go come Order # e il numero del carrello. In questo momento non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di dLocal Go: tramite la notifica firmata oppure tramite una richiesta lato server all'API di dLocal Go quando il cliente ritorna. L'ordine viene quindi creato e il cliente vede la normale pagina di conferma dell'ordine con Your payment with dLocal Go has been received. Se l'ordine è stato messo in sospeso, la pagina mostra Your dLocal Go payment has been received and is being reviewed by the store. You will be informed when your order is confirmed. Se dLocal Go non ha ancora confermato il pagamento (per esempio un voucher in contanti non ancora pagato, oppure dLocal Go non era raggiungibile), una pagina Payment confirmation chiede al cliente di non pagare di nuovo e offre Check again e Back to checkout. L'ordine viene creato appena dLocal Go conferma il pagamento.

Se il cliente lascia la pagina di dLocal Go senza pagare, torna al checkout 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. Il carrello viene conservato. Ogni nuovo tentativo crea un nuovo pagamento dLocal Go; un link di pagamento precedente dello stesso carrello può ancora essere pagato e crea l'ordine.

Se dLocal Go non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio dLocal could not start the payment: seguito dal motivo indicato da dLocal. Succede anche quando il paese del cliente e la valuta del carrello non sono abilitati nel tuo account dLocal Go. Se dLocal Go rifiuta le tue credenziali, il cliente vede This payment method is temporarily unavailable. Please choose another payment method or contact us. Il motivo tecnico viene scritto nel registro.

Le notifiche funzionano anche mentre il negozio è in modalità manutenzione e non vengono bloccate dalla restrizione per paese del tuo negozio.

Il modulo 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

Nessun ordine ancora: il cliente è stato inviato a dLocal Go e non ha pagato, oppure il pagamento è ancora in attesa su dLocal Go. Esiste solo il carrello.

Payment accepted or Delivered: il pagamento è stato confermato. L'ordine passa a Pagamento accettato, oppure a Consegnato se Auto-complete orders è attivo. Il pagamento viene registrato con l'ID del pagamento dLocal come ID transazione, e una nota mostra l'ambiente e l'ID del pagamento.

dLocal payment on hold: dLocal Go ha segnalato un importo o una valuta diversi dal totale del carrello (per esempio il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota lo spiega. Confronta con la dashboard di dLocal Go, poi evadi l'ordine oppure rimborsa il pagamento.

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

Un pagamento rifiutato, scaduto o annullato non modifica mai un ordine esistente. 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.

Blocco di pagamento dLocal Go

La pagina dell'ordine mostra un blocco dLocal Go payment con l'ID del pagamento dLocal, l'ambiente (con un badge Sandbox per i pagamenti di prova), lo stato del pagamento, l'importo addebitato da dLocal Go e l'importo rimborsato, il modulo di rimborso, lo storico dei rimborsi e le dLocal Go notes dell'ordine.

Rimborsi

Nel blocco dLocal Go payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via dLocal Go. Conferma la domanda Refund this amount through dLocal Go? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei Moduli. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da dLocal Go, quindi dopo una differenza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. 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, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso accettato viene aggiunto allo storico dei rimborsi e alle note con l'ID del rimborso, lo stato e il motivo. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non modifica lo stato.

dLocal Go comunica poi lo stato finale del rimborso tramite la notifica di rimborso, e viene aggiunto alle note. Se dLocal Go rifiuta o annulla in seguito un rimborso che aveva accettato, la nota avverte che il denaro non è stato restituito al cliente. Rimborsa di nuovo il cliente o con un altro metodo.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non rimandano denaro tramite dLocal Go. I rimborsi effettuati nella dashboard di dLocal Go non vengono registrati come rimborsi in PrestaShop e di solito non aggiungono alcuna nota. Aggiorna l'ordine manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox dLocal Payment è il primo blocco di Modules > Module Manager > VibeFox dLocal Payment > Configure, sopra le impostazioni. Incolla la chiave in License key e clicca 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-dlocal 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 inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca 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: il dominio del negozio principale, anche in una configurazione multinegozio. Rimuovere la chiave dal negozio non libera il suo slot di 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 avviato comunque, il cliente vede This payment method is not available. Please choose another one. Lo storefront 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 sono interessati: 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 a 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

dLocal Go non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la chiave API e il secret API dell'Environment selezionato siano inseriti. La pagina delle impostazioni mostra un avviso se mancano. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma nessun ordine è stato creato: dLocal Go non è riuscito a raggiungere l'URL di notifica (firewall, autenticazione di base, nessun indirizzo pubblico) e il cliente non è tornato nel negozio. Attiva Debug log, controlla il campo Log e verifica il pagamento nella dashboard di dLocal Go. Appena arriva una notifica o il cliente apre Check again, l'ordine viene creato.

La notifica risponde Missing signature o Invalid signature: la chiave API e il secret nelle impostazioni non appartengono all'account che ha inviato la notifica. Le notifiche vengono verificate con le credenziali dell'ambiente del pagamento, 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 del pagamento. Inseriscile; dLocal Go riproverà la notifica.

La notifica risponde API verification failed: non è stato possibile raggiungere l'API di dLocal Go per leggere il pagamento. dLocal Go riproverà la notifica.

La notifica risponde Temporarily unavailable: l'ordine era in conferma da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (per esempio il modulo è disattivato). dLocal Go riproverà la notifica. Il motivo è nel registro.

La notifica risponde Order not found: il pagamento non appartiene a un carrello di questo negozio, per esempio perché è 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 la chiave API o il secret. Controlla le credenziali dell'ambiente selezionato.

Il cliente vede Payment gateway is not properly configured: mancano le credenziali dell'ambiente selezionato.

L'ordine è dLocal payment on hold dopo il pagamento: leggi le note nel blocco dLocal Go payment. L'importo o la valuta pagati non corrispondevano al carrello, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Evadi l'ordine oppure rimborsa il pagamento.

Il rimborso fallisce con un messaggio su credenziali mancanti: il pagamento è stato effettuato nell'altro ambiente, e le sue credenziali non sono impostate. Inseriscile e riprova.

Per gli sviluppatori, la documentazione del modulo elenca gli hook actionWcpDlocalPaymentData e actionWcpDlocalCurrencyDecimals.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox dLocal Payment 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 successiva reinstallazione. I pagamenti e i rimborsi dLocal degli ordini e lo stato dell'ordine dLocal payment on hold vengono sempre conservati, così gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID di transazione.

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