VibeFox Moyasar 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.

Valuta: la valuta del carrello deve essere SAR, AED, USD, EUR, KWD, BHD o OMR. Per qualsiasi altra valuta il metodo di pagamento non viene mostrato nel checkout.

Account Moyasar: ti servono le chiavi API segrete del tuo account Moyasar (test e live). Vengono usate solo le chiavi segrete. La chiave pubblicabile non è necessaria, perché il pagamento avviene nella pagina di Moyasar. Si consiglia un webhook in Moyasar Dashboard (vedi Configurazione).

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un 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 Moyasar Payment Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in alto nella pagina Configure, poi fai clic su Activate (vedi Chiave di licenza).

4. Incolla le chiavi segrete di Moyasar e fai clic su Save. Configura il webhook in Moyasar Dashboard (vedi Configurazione).

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

All'installazione il modulo crea due stati dell'ordine: Awaiting Moyasar payment e Moyasar payment on hold. PrestaShop propone 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 Moyasar Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando la modalità corrente non ha una chiave segreta (il metodo di pagamento viene allora nascosto nel checkout), quando non è salvato un segreto condiviso del webhook (il webhook rifiuta allora ogni chiamata) o quando la valuta predefinita del negozio non è supportata. Mentre il modulo è attivo in modalità test, mostra Test mode is active: payments are simulated, no money is charged. Al salvataggio il modulo rifiuta una chiave pubblicabile, una chiave dell'altra modalità o una chiave con spazi, mantiene il valore precedente e mostra il motivo.

Moyasar

Enable/Disable: Enable Moyasar attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede nel checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Pay with Moyasar. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. In modalità test il checkout aggiunge (Test mode: no real payment is made.)

Chiavi API

Copia le chiavi segrete da Moyasar Dashboard > Settings > API Keys. Le chiavi di test e quelle live sono separate. La modalità test usa solo la chiave di test, la modalità live solo la chiave live.

Test mode: usa la chiave segreta di test: i pagamenti vengono simulati e non viene addebitato alcun importo. Predefinito: attivo. Disattivala per accettare pagamenti reali con la chiave segreta live.

Test secret key: la chiave segreta della modalità test. Inizia con sk_test_.

Live secret key: la chiave segreta della modalità live. Inizia con sk_live_.

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

Notifiche di pagamento (webhook)

Il webhook è consigliato, ma non obbligatorio. Gli ordini vengono confermati anche quando il cliente torna nel negozio e dalla notifica della fattura che Moyasar invia automaticamente al tuo negozio quando la fattura viene pagata. Il webhook copre i clienti che chiudono il browser prima di tornare e segnala i rimborsi effettuati in Moyasar Dashboard. Aggiungilo in Moyasar Dashboard > Settings > Webhooks.

Webhook URL: mostrato in sola lettura con un pulsante Copy. Con URL parlanti appare così: https://your-shop/module/wcp_moyasar_payment_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni. Metodo HTTP: POST.

Webhook shared secret: inserisci lo stesso valore di Shared secret del webhook in Moyasar. Se non c'è nulla di salvato, Save genera un segreto casuale; Generate a new secret sostituisce quello salvato. Un segreto generato viene mostrato una sola volta sopra le impostazioni dopo il salvataggio e mai più, quindi copialo subito in Moyasar. I webhook senza il segreto condiviso corretto vengono rifiutati.

Seleziona questi eventi per il webhook (sono elencati anche in questa sezione):

Nessun dato di un webhook o di una notifica viene considerato attendibile direttamente: per ciascuno, il modulo legge la fattura dalle API di Moyasar con la chiave segreta della modalità in cui la fattura è stata creata e verifica che sia stata creata per questo carrello. I pagamenti di altre integrazioni sullo stesso account Moyasar vengono ignorati. Un unico segreto condiviso serve entrambe le modalità.

Ordini

Status after payment: lo stato dell'ordine impostato dopo un pagamento confermato. L'ordine viene creato direttamente in questo stato.

Avanzate

Clear saved secrets: seleziona Test secret key, Live secret key o Webhook shared secret e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Debug log: registra le chiamate API e le notifiche in logs/moyasar_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Chiavi API, dati della carta e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Clean uninstall: se attivo, la disinstallazione del modulo elimina le impostazioni del modulo e il registro. I dati di pagamento salvati con gli ordini (ID di fattura e di pagamento Moyasar) vengono conservati, così i rimborsi restano tracciabili. Predefinito: disattivato.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Pay with Moyasar) e conferma. Il modulo crea una fattura Moyasar per il totale del carrello nella valuta del carrello e invia il cliente alla relativa pagina di pagamento. Lì il cliente paga con un metodo qualsiasi attivo nel tuo account Moyasar. La fattura mostra Order #, il numero del carrello e il nome del tuo negozio. A questo punto non esiste ancora alcun ordine.

L'ordine viene segnato come pagato solo dopo la conferma di Moyasar: il modulo legge la fattura dalle API di Moyasar e verifica che sia pagata, che appartenga a questo carrello e che abbia esattamente l'importo e la valuta del carrello. Solo a quel punto l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Moyasar has been received. Se Moyasar trattiene il pagamento per una verifica, la pagina mostra Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. Se l'ordine è in attesa per la tua verifica, la pagina indica che il pagamento è stato ricevuto e che l'ordine è in revisione. Se un pagamento in revisione fallisce in seguito, o se l'ordine non pagato viene annullato, la pagina mostra Your Moyasar payment was not completed. Please contact us about this order.

Se il cliente torna senza pagare (per esempio con il pulsante indietro della pagina di pagamento), ritrova il checkout con uno di questi messaggi: The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method. oppure, quando il pagamento non può ancora essere verificato, We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again. Il carrello viene conservato.

Il cliente può riprovare. Se la pagina di pagamento aperta del carrello ha ancora lo stesso importo e la stessa valuta, viene riutilizzata. Se il totale del carrello è cambiato, la vecchia pagina di pagamento viene annullata in Moyasar e ne viene creata una nuova, quindi quella vecchia non può più essere pagata. Se la fattura precedente risulta già pagata, viene creato l'ordine invece di un nuovo pagamento.

Se Moyasar non riesce ad avviare il pagamento, il cliente resta nel checkout con un breve messaggio, per esempio The Moyasar payment service is not responding. Please try again in a few minutes., e può scegliere un altro metodo di pagamento. I dettagli vengono scritti nel registro.

Il webhook e la notifica della fattura funzionano anche quando il negozio è in modalità manutenzione e non vengono bloccati dalla restrizione per paese del tuo negozio.

Il modulo accetta solo pagamenti una tantum sulla pagina di Moyasar. Non prevede un modulo di pagamento con carta nel tuo checkout, carte salvate o tokenizzazione, abbonamenti né autorizzazione e cattura separate.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Moyasar e non ha pagato, oppure Moyasar non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted, Delivered o Moyasar payment on hold: il pagamento è stato confermato. Lo stato segue Status after payment. Il pagamento viene registrato con l'ID del pagamento Moyasar come ID della transazione, e una nota indica come è stato confermato il pagamento (webhook, notifica della fattura, ritorno del cliente o checkout), l'ID della fattura, l'ID del pagamento e il metodo di pagamento.

Awaiting Moyasar payment: Moyasar trattiene il pagamento per una verifica. L'ordine passa allo stato pagato quando Moyasar conferma il pagamento.

Errore di pagamento: il pagamento in revisione non è riuscito.

Moyasar payment on hold after payment: Moyasar 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 la fattura è stata pagata dopo che avevi annullato l'ordine. L'ordine non viene segnato come pagato, ma l'importo effettivamente ricevuto viene registrato quando è nella valuta dell'ordine. La nota lo spiega. Verifica il pagamento in Moyasar Dashboard ed evadi l'ordine oppure rimborsa il pagamento.

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

Un ordine pagato non viene mai riportato indietro da eventi successivi. Se anche una seconda fattura di un carrello già pagato viene pagata (per esempio da due schede del browser), l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato in Moyasar Dashboard.

Blocco pagamento Moyasar

La pagina dell'ordine mostra un blocco Moyasar payment con l'ID della fattura Moyasar, l'ID del pagamento, il metodo (per esempio il marchio della carta e le ultime quattro cifre), lo stato, gli importi pagati e rimborsati, un badge Test mode per i pagamenti di prova, la cronologia dei rimborsi e le Moyasar notes dell'ordine.

Rimborsi

Nel blocco Moyasar payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Moyasar. Conferma la domanda Refund this amount through Moyasar? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine dei Moduli. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Moyasar, quindi dopo una discrepanza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso totale di un pagamento con carta effettuato meno di 2 ore fa viene inviato come annullamento (void): un annullamento prima del regolamento, senza commissioni. In caso contrario si tratta di un rimborso. Il rimborso usa la chiave segreta della modalità in cui è stato effettuato il pagamento (test o live), quindi quella chiave deve essere impostata. Il modulo verifica prima in Moyasar la valuta, lo stato e l'importo rimborsabile del pagamento. Se Moyasar non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso o un annullamento riusciti vengono aggiunti alla cronologia dei rimborsi e alle note. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili dopo che Moyasar ha confermato il pagamento.

Il modulo non crea note di credito. I pulsanti standard di rimborso di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Moyasar.

I rimborsi e gli annullamenti effettuati in Moyasar Dashboard arrivano tramite il webhook. Se Moyasar mostra più importo rimborsato di quanto registrato dal modulo, viene aggiunta una nota all'ordine. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente. Aggiornali manualmente se necessario, senza usare Refund via Moyasar.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Moyasar Payment Gateway è il primo blocco nella pagina Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, 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 ricontrollare 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-moyasar 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 modificare la chiave. I testi del blocco seguono la lingua del back office (sono incluse 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 o 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, 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 dominio: il dominio 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, Moyasar non viene mostrato ai clienti nel checkout. Se comunque viene avviato un pagamento, 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 puoi provarlo nel 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 il 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Moyasar non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia una chiave segreta (Test secret key in modalità test, Live secret key in modalità live) e che la valuta del carrello sia SAR, AED, USD, EUR, KWD, BHD o OMR. La pagina delle impostazioni mostra un avviso quando la chiave manca o la valuta del negozio non è supportata. 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 non è stato creato alcun ordine: le conferme non sono arrivate al tuo negozio. Configura il webhook: in Moyasar Dashboard verifica che esista, che il suo URL sia esattamente la Webhook URL delle impostazioni, che il metodo sia POST, che siano selezionati i quattro eventi e che il suo segreto condiviso sia uguale a quello salvato in Webhook shared secret. L'ordine viene creato anche quando il cliente torna nel negozio o tenta di pagare di nuovo lo stesso carrello.

Il webhook risponde Unauthorized: il segreto condiviso in Moyasar è diverso da quello salvato. Inserisci il segreto del webhook di Moyasar in Webhook shared secret e salva, oppure seleziona Generate a new secret, salva e incolla in Moyasar il segreto mostrato.

Il webhook risponde Webhook secret not configured: non è salvato alcun segreto condiviso, per esempio dopo averlo rimosso con Clear saved secrets. Fai clic su Save per generarne uno e copialo in Moyasar.

Il webhook risponde Key not configured: la fattura è stata creata in una modalità (test o live) la cui chiave segreta è vuota. Inserisci quella chiave.

Il webhook risponde Verification failed o Try again later: la fattura non è stata letta dalle API di Moyasar, il carrello era in aggiornamento da un'altra richiesta nello stesso momento, oppure l'ordine non può essere creato (per esempio perché il modulo è disattivato). Moyasar ripete il webhook. Attiva Debug log per vedere il motivo.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste POST da Moyasar.

Errore al salvataggio per la chiave: è stata incollata una chiave pubblicabile (pk_...) o una chiave dell'altra modalità, oppure la chiave contiene spazi. È stato mantenuto il valore precedente. Le chiavi di test iniziano con sk_test_, quelle live con sk_live_.

Il cliente vede un errore quando sceglie Moyasar: attiva Debug log e controlla il campo Log nella pagina del modulo. This payment method is temporarily unavailable. Please choose another payment method or contact us. di solito indica una chiave segreta errata o mancante. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. significa che il carrello ha già una fattura pagata che non è stato possibile trasformare in ordine; controlla il registro.

Order is Moyasar payment on hold after payment: leggi le Moyasar notes nel blocco Moyasar payment. L'importo o la valuta pagati erano diversi dal carrello, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Evadi l'ordine oppure rimborsa il pagamento.

Il rimborso non riesce: leggi il messaggio. Se il pagamento è stato effettuato nell'altra modalità, inserisci la chiave segreta di quella modalità. Se l'importo è superiore a quello ancora rimborsabile in Moyasar, una parte del pagamento è già stata rimborsata, per esempio in Moyasar Dashboard. Se Moyasar non ha confermato l'importo rimborsato, verifica il pagamento in Moyasar Dashboard prima di riprovare.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Moyasar Payment Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Clean uninstall è attivo, vengono rimosse le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. Le fatture, i pagamenti e i rimborsi di Moyasar e gli stati dell'ordine Awaiting Moyasar payment e Moyasar payment on hold vengono sempre conservati, così i vecchi ordini possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID delle transazioni.

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