VibeFox Paymob for WooCommerce — Guida

Requisiti

WordPress: 6.2 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Account Paymob: un account commerciante in uno dei Paesi supportati: Egitto, Emirati Arabi Uniti, Arabia Saudita, Oman o Pakistan. Ti servono quattro valori dalla dashboard di Paymob: la chiave API, l'ID dell'integrazione di un'integrazione di pagamento online, l'ID dell'iFrame della pagina di pagamento e il segreto HMAC.

Valuta: la valuta del negozio deve essere quella del tuo Paese Paymob: EGP per l'Egitto, AED per gli Emirati Arabi Uniti, SAR per l'Arabia Saudita, OMR per l'Oman, PKR per il Pakistan. Con un'altra valuta, il metodo di pagamento non viene mostrato al checkout.

Chiave di licenza VibeFox: acquistata 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_paymob_pay in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

5. Scegli il Paymob country e inserisci la chiave API, l'ID dell'integrazione, l'ID dell'iFrame e il segreto HMAC (vedi Configurazione).

6. Nella dashboard di Paymob, imposta gli URL di callback della tua integrazione con l'URL mostrato nella pagina delle impostazioni (vedi Callbacks).

7. Attiva Enable/Disable. Prova un pagamento con l'ID di un'integrazione di prova Paymob, poi inserisci l'ID della tua integrazione reale.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > Paymob. Sopra i campi, la pagina ti avvisa quando manca uno dei quattro valori Paymob (finché non viene inserito, Paymob non è visibile al checkout) e quando la valuta del negozio non è accettata dal Paese Paymob selezionato. Un riquadro mostra l'URL di callback con un pulsante Copy e un link alla dashboard Paymob del Paese selezionato.

Generale

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

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Paymob.

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

Account Paymob

Tutti i valori si trovano nella dashboard del tuo account commerciante Paymob. Non esiste una modalità di prova separata: per i pagamenti di prova inserisci l'ID dell'integrazione di un'integrazione in modalità di prova. Nessun'altra impostazione cambia.

Paymob country: il Paese del tuo account Paymob. Seleziona il server API e della pagina di pagamento, e la valuta del negozio deve essere quella di questo Paese. Predefinito: Egypt.

API key: nella dashboard di Paymob, in Settings > Account info > API Key.

Integration ID: nella dashboard di Paymob, in Developers > Payment Integrations: l'ID numerico dell'integrazione online per carta o portafoglio. I metodi di pagamento offerti sulla pagina Paymob sono quelli di questa integrazione.

iFrame ID: nella dashboard di Paymob, in Developers > iframes: l'ID numerico dell'iFrame di pagamento.

HMAC secret: nella dashboard di Paymob, in Settings > Account info > HMAC. Obbligatorio: gli ordini vengono segnati come pagati solo dai callback firmati con questo segreto.

Integration ID e iFrame ID devono contenere solo cifre. Gli spazi vengono rimossi. Qualsiasi altro valore viene rifiutato al salvataggio con il messaggio che il campo must contain digits only — the previous value was kept.

Callbacks

Paymob comunica ogni transazione al tuo negozio. Nella dashboard di Paymob apri Developers > Payment Integrations, scegli la tua integrazione, fai clic su Edit e imposta sia Transaction processed callback sia Transaction response callback con l'URL mostrato nella pagina delle impostazioni. Ha questo aspetto: https://your-site/wc-api/paymob_pay/. Copialo con il pulsante Copy. Imposta gli URL in ogni integrazione che usi, inclusa quella di prova.

Il callback di transazione elaborata viene inviato dal server Paymob. Il callback di risposta della transazione riporta il cliente nel tuo negozio. Entrambi sono firmati con il tuo segreto HMAC e vengono verificati dal plugin. I callback senza una firma valida vengono rifiutati e non modificano nulla. Se il callback del server arriva in ritardo o va perso, anche un ritorno firmato del cliente conferma il pagamento.

Avanzate

Debug log: Log payment steps and callbacks scrive i passaggi del pagamento e i callback in WooCommerce > Status > Logs, origine wcp_paymob_pay. Errori e callback rifiutati vengono sempre registrati. Chiavi, token e dati dei clienti non vengono mai scritti. Predefinito: disattivato.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Disattivare il plugin non cancella mai nulla. Gli ID Paymob salvati sugli ordini vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Paymob) e inoltra l'ordine. Il plugin registra un nuovo ordine Paymob per il totale dell'ordine nella valuta dell'ordine, passa a Paymob il nome, l'e-mail, il telefono e l'indirizzo di fatturazione del cliente e invia il cliente alla pagina di pagamento Paymob del tuo Paese. Lì il cliente paga con uno dei metodi della tua integrazione, ad esempio una carta o un portafoglio mobile.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Paymob lo conferma con una transazione firmata. Un pagamento riuscito, in sospeso o autorizzato porta il cliente alla pagina di ordine ricevuto.

Se il pagamento è stato rifiutato, il cliente torna al checkout (oppure alla pagina Pay for order, se il pagamento era stato avviato lì) con il messaggio Your Paymob payment was not completed. Please try again or choose another payment method. Ogni nuovo tentativo registra un proprio ordine Paymob, quindi il cliente può riprovare lo stesso ordine. Se il ritorno da Paymob non può essere verificato, il cliente vede We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.

Se Paymob non può avviare il pagamento, il cliente vede un messaggio breve e può scegliere un altro metodo di pagamento, ad esempio Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. oppure Could not connect to Paymob. Please try again in a moment. Il motivo tecnico viene scritto nel log.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. Nella pagina Pay for order viene verificata la valuta dell'ordine invece di quella del negozio. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta pagamenti una tantum sulla pagina Paymob. Non prevede carte salvate, abbonamenti, un modulo della carta incorporato nel tuo sito né rimborsi da WooCommerce.

Ordini

Stati dell'ordine

Pending payment: il cliente è stato inviato a Paymob e non ha ancora pagato, oppure Paymob non ha ancora confermato il pagamento.

Processing: Paymob ha confermato il pagamento. Gli ordini con soli prodotti virtuali scaricabili passano a Completato, il valore predefinito di WooCommerce. La nota dell'ordine mostra la transazione Paymob, l'importo e il tipo di carta con le ultime quattro cifre. L'ID della transazione è l'ID transazione Paymob.

On hold: il pagamento è in sospeso presso Paymob, ad esempio un pagamento in contanti o al chiosco; oppure Paymob ha solo autorizzato l'importo senza acquisirlo (acquisiscilo nella dashboard di Paymob: l'ordine viene completato quando arriva il callback di acquisizione); oppure l'importo o la valuta pagati non corrispondono all'ordine; oppure è arrivato un pagamento per un ordine annullato. La nota dell'ordine spiega il motivo.

Failed: Paymob ha rifiutato il pagamento di un ordine in sospeso. Il cliente può pagare di nuovo.

Se arriva un secondo pagamento riuscito per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nella dashboard di Paymob. Un pagamento per un ordine annullato che era stato pagato in precedenza, oppure per un ordine rimborsato, aggiunge solo una nota: l'ordine non viene riaperto.

Rimborsi

I rimborsi da WooCommerce non sono supportati. Rimborsa o annulla il pagamento nella dashboard di Paymob. Quando Paymob segnala un rimborso o un annullamento, all'ordine viene aggiunta una nota e lo stato dell'ordine non cambia. Aggiorna l'ordine manualmente, ad esempio con un rimborso manuale in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Paymob. 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 verificare 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 dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Liberalo dal tuo account vibefox.net.

Senza una chiave attiva, Paymob 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 continuano a vedere il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.

Risoluzione dei problemi

Paymob non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che tutti e quattro i valori (API key, Integration ID, iFrame ID, HMAC secret) siano compilati e che la valuta del negozio sia quella del Paymob country selezionato. La pagina delle impostazioni mostra un avviso quando manca qualcosa. Gli sviluppatori con un account Paymob multivaluta possono estendere le valute accettate con il filtro paymob_p_supported_currencies.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: i callback non raggiungono il tuo negozio. Verifica che Transaction processed callback e Transaction response callback dell'integrazione che usi coincidano esattamente con l'URL mostrato nella pagina delle impostazioni e che il HMAC secret sia quello dello stesso account Paymob. I callback rifiutati vengono registrati come avvisi in WooCommerce > Status > Logs, origine wcp_paymob_pay, anche quando il registro di debug è disattivato.

Il callback risponde Invalid signature: il segreto HMAC nelle impostazioni non corrisponde all'account Paymob, oppure è selezionato l'account di un altro Paese. Copia di nuovo il segreto HMAC.

Il callback risponde Not configured: il segreto HMAC è vuoto. Inserisci il segreto; Paymob ripeterà il callback.

Il callback risponde locked: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento, ad esempio il ritorno del cliente. Paymob ripeterà il callback.

Il cliente vede un errore quando invia l'ordine: attiva il Debug log e controlla il registro. Paymob payments are temporarily unavailable indica una chiave API errata o un valore mancante. Paymob could not start the payment indica che Paymob ha rifiutato la richiesta, ad esempio per un ID dell'integrazione errato o dati di fatturazione incompleti. This order cannot be paid with Paymob indica che il totale dell'ordine è zero.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. Il pagamento è in sospeso (contanti o chiosco), la transazione è stata solo autorizzata (acquisiscila nella dashboard di Paymob), l'importo o la valuta non corrispondevano, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota dell'ordine spiega il motivo.

Pagamenti di prova: inserisci l'ID di un'integrazione di prova Paymob in Integration ID e imposta i callback in quell'integrazione. Per i pagamenti reali, inserisci di nuovo l'ID della tua integrazione reale.

Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Ad 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.

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 log vengono rimossi solo se Clean uninstall era attivo. Altrimenti restano per una reinstallazione successiva. Gli ordini esistenti conservano le note di pagamento, gli ID delle transazioni e gli ID Paymob.

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