VibeFox Moyasar for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Con una versione precedente di WooCommerce, il plugin mostra un avviso e non si carica.

PHP: 8.0 o successivo.

Valuta: la valuta del negozio o dell'ordine deve essere SAR, AED, USD, EUR, KWD, BHD o OMR. Per qualsiasi altra valuta il metodo di pagamento viene nascosto al 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 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_moyasar_payment_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Moyasar > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco di licenza in cima alla pagina e fai clic su Activate.

5. Incolla le chiavi segrete di Moyasar e salva. Configura il webhook in Moyasar Dashboard con l'URL e il secret condiviso mostrati nelle impostazioni (vedi Configurazione).

6. Attiva Enable/Disable. Effettua un ordine di prova in modalità test, poi deseleziona Test mode.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Moyasar. Il titolo della pagina mostra un distintivo TEST MODE o LIVE. Sopra i campi, la pagina ti avvisa quando la modalità corrente non ha una chiave segreta (in tal caso il metodo di pagamento viene nascosto al checkout) o quando la valuta del negozio non è supportata, e mostra Test mode is active: payments are simulated, no money is charged. mentre la modalità test è attiva. Nell'elenco dei metodi di pagamento, Moyasar risulta da configurare finché la modalità corrente non ha una chiave segreta. Al salvataggio, il plugin rifiuta una chiave pubblicabile, una chiave dell'altra modalità o una chiave con spazi, mantiene il valore precedente e mostra il motivo. Ti avvisa anche quando il gateway è attivo ma la chiave segreta della modalità corrente è vuota.

Generale

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Pay with Moyasar.

Description: il testo mostrato sotto il metodo di pagamento al 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: Enable test mode usa la chiave segreta di test: i pagamenti sono simulati e non viene addebitato nulla. 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_.

Notifiche di pagamento (webhook)

Il webhook è consigliato, ma non obbligatorio. Gli ordini vengono confermati anche quando il cliente torna nel negozio e tramite la 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 ti informa dei rimborsi effettuati in Moyasar Dashboard. In Moyasar Dashboard > Settings > Webhooks aggiungi un webhook con l'URL e il secret condiviso di questa sezione, metodo HTTP POST.

Webhook URL: mostrato in sola lettura con un pulsante Copy. Ha un aspetto simile a https://your-site/wp-json/moyasar_p/v1/webhook. Metodo HTTP: POST.

Webhook shared secret: inserisci lo stesso valore del Shared secret del webhook in Moyasar. Lascia il campo vuoto e salva per generare un secret casuale, poi fai clic su Show e copialo in Moyasar. I webhook senza il secret condiviso corretto vengono rifiutati.

Seleziona questi eventi per il webhook:

Nessun webhook o notifica viene considerato attendibile direttamente: per ciascuno, il plugin legge la fattura dalle API di Moyasar con la chiave segreta della modalità dell'ordine e verifica che sia stata creata per quell'ordine. I pagamenti di altre integrazioni sullo stesso account Moyasar vengono ignorati.

Ordini

Status after payment: lo stato dell'ordine impostato dopo un pagamento confermato. Lo stato viene impostato subito, senza un secondo cambio di stato.

Avanzate

Debug log: Log API calls and notifications scrive i dettagli in WooCommerce > Status > Logs, origine wcp_moyasar_payment_gateway. Gli errori vengono sempre registrati. Chiavi API, dati della carta e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. I dati di pagamento salvati sugli ordini (ID della fattura e del pagamento Moyasar) vengono conservati, così i rimborsi restano tracciabili. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Pay with Moyasar) e invia l'ordine. Il plugin crea una fattura Moyasar per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina di pagamento. Lì il cliente paga con un qualsiasi metodo attivo nel tuo account Moyasar, ad esempio mada, Visa, Mastercard, Apple Pay o STC Pay. La fattura mostra Order, il numero dell'ordine e il nome del tuo sito.

L'ordine viene segnato come pagato solo dopo la conferma di Moyasar: il plugin legge la fattura dalle API di Moyasar e verifica che sia pagata, che appartenga a questo ordine e che abbia esattamente l'importo e la valuta dell'ordine. Dopo il pagamento, il cliente torna alla pagina di ordine ricevuto del tuo negozio. Se il cliente torna senza aver pagato (ad esempio con il pulsante indietro della pagina di pagamento), torna al checkout o alla pagina Pay for order 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.

Un cliente può pagare di nuovo un ordine non pagato. Se la pagina di pagamento ancora aperta dell'ordine ha lo stesso importo e la stessa valuta, viene riutilizzata. Se il totale dell'ordine è cambiato, la vecchia pagina di pagamento viene annullata e ne viene creata una nuova, quindi la vecchia non può più essere pagata. Se la fattura precedente è già pagata, l'ordine viene confermato invece di creare un nuovo pagamento.

Se Moyasar non riesce ad avviare il pagamento, il cliente vede un breve messaggio, ad 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 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 pagamenti una tantum solo nella pagina di Moyasar. Non prevede un modulo di pagamento con carta nel tuo checkout, carte salvate o tokenizzazione, WooCommerce Subscriptions, né autorizzazione e cattura separate.

Ordini e rimborsi

Stati dell'ordine

Pending payment: la fattura è stata creata e il cliente non ha ancora pagato. La nota dell'ordine mostra l'ID della fattura, l'importo e la modalità.

Processing, Completed or On hold: il pagamento è stato confermato. Lo stato segue Status after payment. La nota dell'ordine mostra 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. L'ID della transazione è l'ID del pagamento Moyasar.

On hold after payment: Moyasar ha segnalato un importo o una valuta diversi dal totale dell'ordine (l'ordine non viene segnato come pagato), oppure la fattura è stata pagata dopo l'annullamento dell'ordine. La nota dell'ordine lo spiega. Verifica il pagamento in Moyasar Dashboard, poi evadi l'ordine o rimborsa il pagamento.

On hold before payment: Moyasar trattiene il pagamento per una verifica. L'ordine viene aggiornato quando Moyasar decide.

Failed: l'ultima fattura di un ordine non pagato è fallita, è scaduta o è stata annullata. Il cliente può provare a pagare di nuovo.

Cancelled: l'ordine è stato annullato dal cliente, da te o dal timeout di riserva delle scorte di WooCommerce. Anche la fattura Moyasar aperta dell'ordine viene annullata, quindi non può più essere pagata.

Un ordine pagato, annullato o rimborsato non viene mai modificato da eventi successivi. Se una seconda fattura di un ordine già pagato viene pagata (ad esempio da due schede del browser), l'ordine non viene modificato di nuovo. Una nota ti invita a rimborsare il duplicato in Moyasar Dashboard.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Pay with Moyasar (il pulsante usa il titolo del metodo di pagamento). Sono supportati rimborsi totali e parziali per gli ordini con un pagamento Moyasar. Il rimborso totale di un pagamento con carta effettuato meno di 2 ore fa viene inviato come annullamento (annullamento prima della liquidazione); altrimenti è 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. Prima di rimborsare, il plugin verifica il pagamento in Moyasar: valuta, stato e importo ancora rimborsabile. Se Moyasar 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.

I rimborsi e gli annullamenti effettuati in Moyasar Dashboard arrivano tramite il webhook. Se Moyasar mostra più importo rimborsato di WooCommerce, viene aggiunta una nota all'ordine. Non vengono registrati automaticamente come rimborsi di WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza usare Refund via Pay with Moyasar.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco di licenza si trova in cima a WooCommerce > Settings > Payments > Moyasar. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, ad esempio la data fino alla quale la licenza è attiva e il tuo dominio. Usa Check now per controllare 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. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Moyasar 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 con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins 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 assistenza richiedono un rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Moyasar non compare al checkout: controlla 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 negozio o dell'ordine sia SAR, AED, USD, EUR, KWD, BHD o OMR. La pagina delle impostazioni mostra un avviso quando la chiave manca o la valuta non è supportata.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: le conferme non sono arrivate al tuo negozio. Configura il webhook: in Moyasar Dashboard verifica che esista, che il suo URL sia esattamente il Webhook URL delle impostazioni, che il metodo sia POST, che tutti e quattro gli eventi siano selezionati e che il suo secret condiviso sia uguale a Webhook shared secret. L'ordine viene confermato anche quando il cliente torna nel negozio e quando prova a pagare di nuovo lo stesso ordine.

Il webhook risponde Unauthorized: il secret condiviso in Moyasar è diverso da Webhook shared secret. Fai clic su Show, copia il valore e incollalo nel webhook di Moyasar.

Il webhook risponde Webhook secret not configured: le impostazioni non sono ancora state salvate con un secret condiviso. Salva le impostazioni per generarlo e copialo in Moyasar.

Il webhook risponde Key not configured: l'ordine è stato pagato 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, oppure l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Moyasar ripete il webhook.

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

Il cliente vede un errore quando effettua l'ordine: attiva Debug log e controlla WooCommerce > Status > Logs, origine wcp_moyasar_payment_gateway. 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 l'ordine ha già una fattura pagata che richiede la tua verifica.

L'ordine è On hold after payment: 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: 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, ad esempio in Moyasar Dashboard. Se Moyasar non ha confermato l'importo rimborsato, verifica il pagamento in Moyasar Dashboard prima di riprovare.

Il blocco di licenza mostra un errore: segui il messaggio nel blocco. Ad 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 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 Clean uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID di transazione.

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