VibeFox DPO for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione SimpleXML. Il modulo non si installa senza di esse.

Account DPO Pay: ti servono il Company Token e il Service Type ID del tuo account commerciante DPO. DPO li rilascia all'apertura del tuo account; richiedili al tuo account manager DPO oppure su dpogroup.com. DPO può anche fornire un account di test con un proprio token e un proprio service type. Non esiste un server di test separato: DPO usa lo stesso indirizzo API per account di test e live, e l'account viene scelto in base al token.

Valuta: la valuta del negozio deve essere supportata dal tuo account DPO. DPO accetta al massimo 2 decimali, quindi i totali del carrello con 3 decimali (ad esempio KWD 12.345) non possono essere pagati.

Cron del server: un'attività cron che richiama ogni 15 minuti l'URL di ricontrollo del modulo (vedi Configurazione).

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 cerca VibeFox DPO Pay Gateway nell'elenco dei moduli più tardi e fai clic su Configure.

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

4. Inserisci il Company Token e il Service Type di test e/o live (vedi Configurazione).

5. Invia l'URL di notifica push mostrato nella pagina Configure al supporto DPO e chiedi che lo impostino per il tuo account. Aggiungi l'URL del cron alle attività cron del tuo server.

6. Attiva Enable/Disable e fai clic su Save. Effettua un ordine di prova in modalità test, poi disattiva Test mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine DPO 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 DPO Pay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Quando il modulo è attivo ma il Company Token o il Service Type della modalità selezionata sono vuoti, la pagina ti avvisa che il metodo di pagamento è nascosto al checkout, e al salvataggio compare lo stesso avviso. Finché la modalità test è attiva, la pagina mostra Test mode is on: payments are created with the test account credentials.

DPO Pay

Enable/Disable: Enable DPO Pay 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: DPO Pay. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely by card or mobile money on the DPO Pay payment page.

Credenziali API

DPO rilascia un Company Token e un Service Type ID per il tuo account commerciante, e altri separati per un account di test. Richiedili al tuo account manager DPO oppure su dpogroup.com.

Test mode: quando è attiva, i nuovi pagamenti vengono creati con il Company Token e il Service Type di test. Predefinito: attiva. Disattivala per accettare pagamenti reali con le credenziali live. I controlli di stato e le annullamenti dei pagamenti esistenti usano sempre l'account con cui il pagamento è stato creato.

Test Company Token: il Company Token del tuo account di test DPO.

Test Service Type: il Service Type ID numerico del tuo account di test DPO.

Live Company Token: il Company Token del tuo account commerciante DPO live.

Live Service Type: il Service Type ID numerico del tuo account commerciante DPO live.

I Company Token salvati non vengono mai più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarlo. Un Service Type deve essere un numero. Qualsiasi altro valore non viene salvato: la pagina mostra un avviso e mantiene il valore precedente.

Clear saved Company Tokens: spunta un token e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Notifiche di pagamento

Push notification URL: la notifica push avvisa subito il tuo negozio che un pagamento è stato effettuato, anche se il cliente chiude il browser dopo aver pagato. L'URL non si imposta in un pannello: chiedi al supporto DPO di impostare questo URL per il tuo account. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_dpo_pay/notify, eventualmente con un codice lingua. Copialo esattamente come lo mostra la pagina. Deve essere raggiungibile da internet, senza modalità manutenzione, firewall o autenticazione di base davanti.

Le notifiche push di DPO non hanno firma, quindi il loro contenuto non viene mai considerato attendibile. Il modulo le usa solo per trovare il pagamento tramite il suo token di transazione, poi verifica il risultato con DPO stesso. Un token che il tuo negozio non ha creato viene rifiutato senza alcuna richiesta a DPO.

Scheduled status re-check (cron): richiama questo URL ogni 15 minuti da un'attività cron del server, ad esempio con curl. I pagamenti non confermati vengono ricontrollati con DPO 15 minuti dopo il reindirizzamento e di nuovo dopo il limite di tempo per il pagamento. L'URL contiene un token segreto, quindi tienilo riservato. Senza l'URL push e il cron, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato.

Ordini

Successful payment status: lo stato dell'ordine dopo un pagamento riuscito e verificato.

Le differenze di importo o valuta, i pagamenti solo autorizzati e le transazioni sovra- o sottopagate finiscono sempre in DPO payment on hold.

Avanzate

Logging: scrive le chiamate API e le notifiche in logs/dpo_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. I token sono mascherati, nessun dato del cliente viene registrato. Predefinito: disattivato.

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

Delete data: quando è attiva, la disinstallazione del modulo rimuove le sue impostazioni e il registro. I dati DPO salvati per gli ordini e lo stato dell'ordine DPO payment on hold vengono sempre conservati. Disinstallare senza questa opzione non cancella mai dati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita DPO Pay) e vede la nota You will be redirected to the secure DPO Pay payment page. Dopo la conferma, il modulo crea una transazione DPO per il totale del carrello nella valuta del carrello, con il numero del carrello e il nome del tuo negozio come descrizione, e invia il cliente alla pagina di pagamento DPO. Nome, e-mail, telefono e indirizzo di fatturazione del cliente vengono trasmessi per precompilare la pagina. Lì il cliente paga con un qualsiasi metodo attivato sul tuo account DPO. Il link di pagamento è valido per 5 ore. 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 DPO lo conferma: il modulo chiede a DPO il risultato della transazione quando il cliente torna, quando arriva una notifica push e nei controlli programmati. Solo allora l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine.

Se il pagamento non viene confermato, il cliente torna al checkout con uno di questi messaggi. Il carrello viene conservato.

Se il cliente fa clic sul pulsante della pagina DPO per tornare al negozio, la transazione viene controllata prima. Se è stata pagata, l'ordine viene creato. Altrimenti viene annullata presso DPO e il cliente torna al checkout con il carrello.

Quando il cliente paga di nuovo per lo stesso carrello, la transazione DPO precedente viene controllata per prima. Se è stata pagata, l'ordine viene creato senza un secondo addebito. Se è ancora in elaborazione, il cliente vede Your previous payment for this order is still being processed by DPO. Please wait a few minutes before trying again. Altrimenti la vecchia transazione viene annullata presso DPO e ne viene creata una nuova.

Se DPO non riesce ad avviare il pagamento, il cliente resta al checkout con un messaggio breve scelto in base al codice di errore DPO, ad esempio DPO Pay does not support the currency of this order. Please choose another payment method. oppure The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. Altri errori mostrano DPO Pay is temporarily unavailable. Please try again or choose another payment method. Il motivo tecnico viene scritto nel registro.

La notifica push e l'URL del cron funzionano mentre il negozio è in modalità manutenzione e non sono bloccati dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti singoli sulla pagina DPO. Non prevede rimborsi dal negozio, carte salvate, abbonamenti o pagamenti ricorrenti, campi carta sul tuo sito né acquisizione di pagamenti solo autorizzati.

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a DPO e non ha pagato, il pagamento è stato rifiutato o annullato, oppure DPO non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted, Delivered or DPO payment on hold: il pagamento è stato verificato. Lo stato segue Successful payment status. Il pagamento viene registrato con il token della transazione DPO come ID di transazione. Una nota privata nella pagina dell'ordine mostra l'importo, la valuta, il codice di approvazione e l'inizio del token.

DPO payment on hold after payment: DPO ha confermato un pagamento, ma l'importo o la valuta differiscono dal carrello, il pagamento è solo autorizzato e non acquisito, la transazione è stata sovra- o sottopagata, oppure il cliente aveva annullato il pagamento o l'ordine era già stato annullato. La nota privata spiega il motivo. Controlla la transazione nel portale DPO. Acquisisci o annulla un pagamento solo autorizzato nel portale DPO, poi aggiorna lo stato dell'ordine.

Cancelled: quando annulli un ordine non pagato del modulo (ad esempio uno in attesa per un pagamento solo autorizzato), anche la sua transazione DPO aperta viene annullata presso DPO.

Un successivo esito di rifiuto non modifica mai un ordine, e gli esiti di transazioni precedenti non fanno mai fallire il tentativo in corso. Se DPO conferma un secondo pagamento riuscito per un ordine già pagato, l'ordine non viene modificato e riceve una nota su un possibile doppio pagamento, così puoi rimborsarlo nel portale DPO. Un ordine pagato o rimborsato non viene mai riaperto.

Rimborsi

I rimborsi dal negozio non sono disponibili in questa versione. Rimborsa il pagamento nel portale commerciante DPO, poi cambia lo stato dell'ordine in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox DPO Pay Gateway è il primo blocco di Modules > Module Manager > VibeFox DPO Pay Gateway > 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-dpo 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, DPO Pay 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.

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

DPO Pay does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che il Company Token e il Service Type della modalità selezionata siano impostati: i campi di test in modalità test, i campi live altrimenti. La pagina delle impostazioni mostra un avviso quando mancano. 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: probabilmente l'URL di notifica push non è impostato per il tuo account DPO e il cliente non è tornato nel negozio. Chiedi al supporto DPO di impostare l'URL mostrato nelle impostazioni e verifica che il cron richiami l'URL di ricontrollo ogni 15 minuti. Attiva Logging e controlla il campo Log nella pagina del modulo.

Push notification answers Unknown transaction: il token di transazione non appartiene a un pagamento DPO Pay di questo negozio, ad esempio perché la notifica arriva da un altro negozio sullo stesso account DPO.

Push notification answers Verification failed: non è stato possibile contattare DPO per verificare il pagamento, il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). DPO ripete la notifica e anche il controllo programmato conferma l'ordine. Il motivo è nel registro.

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

The cron URL answers Forbidden: il token nell'URL è errato. Copia di nuovo l'URL dalla pagina Configure. Una chiamata riuscita risponde OK checked= e il numero di pagamenti controllati.

The Service Type is not saved: deve essere il Service Type ID numerico fornito da DPO.

The customer sees DPO Pay is temporarily unavailable: DPO ha rifiutato di creare la transazione, ad esempio per un Company Token o Service Type errato, o un token dell'altra modalità. Il codice di esito DPO è nel registro.

The customer sees that DPO accepts at most 2 decimal places: il totale del carrello ha 3 decimali. DPO non può addebitare questi importi.

The customer sees This order has already been paid with DPO Pay: DPO ha rifiutato un secondo pagamento per lo stesso carrello. Controlla il pagamento nel portale DPO e l'ordine in PrestaShop.

Order is DPO payment on hold after payment: leggi la nota privata nella pagina dell'ordine (vedi Stati dell'ordine), poi controlla la transazione nel portale DPO.

Gli sviluppatori possono modificare i dati del cliente inviati a DPO con l'hook actionWcpDpoPayCustomerData e il limite di tempo per il pagamento con actionWcpDpoPayPaymentTimeLimit.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox DPO Pay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data è attiva, vengono rimosse le impostazioni del modulo e il registro. Se è disattiva, tutte le impostazioni vengono conservate per una reinstallazione successiva. I dati DPO salvati per gli ordini e lo stato dell'ordine DPO payment on hold vengono sempre conservati, quindi le notifiche tardive per i pagamenti vecchi continuano a funzionare dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.

DPO Pay è un marchio registrato del proprio titolare. Questo modulo non è affiliato né approvato da DPO Pay.