VibeFox Paymob for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni di PHP precedenti.

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: l'API key, l'integration ID di un'integrazione di pagamento online, l'iFrame ID della pagina di pagamento e l'HMAC secret.

Valuta: la valuta del carrello 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 viene nascosto al checkout. Gli account Paymob multivaluta non sono supportati.

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

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

4. Scegli il Paymob country e inserisci API key, integration ID, iFrame ID e HMAC secret (vedi Configurazione).

5. Nella dashboard di Paymob imposta gli URL di callback della tua integrazione sull'URL mostrato nella pagina Configure (vedi Callbacks).

6. Attiva Enable/Disable e fai clic su Save. Prova un pagamento con l'ID di un'integrazione di test di Paymob, poi inserisci l'ID della tua integrazione live.

All'installazione il modulo crea due stati dell'ordine: Awaiting Paymob payment e Paymob payment on hold. PrestaShop attiva di default un nuovo modulo di pagamento per tutte le valute, tutti i paesi e tutti i gruppi di clienti. Puoi limitarli in Payment > Preferences. Un paese che abiliterai in seguito nel negozio deve essere spuntato anche lì per questo modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Paymob Pay > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando manca uno dei quattro valori di Paymob (fino ad allora Paymob è nascosto al checkout) e quando la valuta predefinita del negozio non è accettata dal paese Paymob selezionato. Un riquadro Callbacks mostra l'URL di callback con un pulsante Copy e un link alla dashboard Paymob del paese selezionato.

Paymob

Enable/Disable: Enable Paymob 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: 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. Lascia vuoto il campo per non mostrare alcun testo.

Account Paymob

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

Paymob country: il paese del tuo account Paymob. Seleziona il server delle API e della pagina di pagamento, e la valuta del carrello 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 wallet. 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 creati come pagati solo da 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. Gli altri campi vengono salvati.

L'API key e l'HMAC secret salvati non vengono mai più mostrati. Il campo resta vuoto e riporta Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

Clear saved secrets: spunta API key o HMAC secret e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

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 sull'URL mostrato nel riquadro Callbacks. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_paymob_pay/callback, eventualmente con un codice lingua come /en/. L'URL viene generato nella lingua predefinita del negozio. Copialo con il pulsante Copy. Imposta gli URL in ogni integrazione che usi, inclusa quella di test.

Il transaction processed callback viene inviato dal server di Paymob. Il transaction response callback riporta il cliente nel tuo negozio. Entrambi sono firmati con il tuo HMAC secret e verificati dal modulo. I callback senza firma valida vengono rifiutati e non cambiano nulla. Se il callback server arriva in ritardo o si perde, anche un ritorno firmato del cliente conferma il pagamento. Il callback server funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Avanzate

Debug log: scrive i passaggi di pagamento e i callback in logs/paymob_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e callback rifiutati vengono sempre registrati, anche quando l'opzione è disattivata. Chiavi, token e dati dei clienti non vengono mai scritti. Predefinito: disattivato.

Log: mostra la dimensione 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 i registri. Gli ID Paymob salvati per gli ordini (tentativi di pagamento) e gli stati dell'ordine vengono sempre mantenuti. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Paymob) e conferma. Il modulo registra un nuovo ordine Paymob per il totale del carrello nella valuta del carrello, 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, per esempio una carta o un portafoglio mobile. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Paymob lo conferma con una transazione firmata. A quel punto l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine. Un pagamento in attesa (per esempio in contanti o al chiosco) o un pagamento autorizzato crea comunque l'ordine, in uno stato di attesa, e porta alla pagina di conferma.

Se l'ordine viene confermato dal callback di Paymob nello stesso momento, il cliente vede una pagina con Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. Per un pagamento in attesa il testo è Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. La pagina ha un pulsante Check again e un pulsante Back to checkout.

Se il pagamento è stato rifiutato, il cliente torna al checkout con lo stesso carrello e 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ò pagare di nuovo il carrello. Se la risposta di Paymob non può essere verificata, 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 riesce ad avviare il pagamento, il cliente resta al checkout con un messaggio breve, per 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 registro.

Il modulo gestisce pagamenti una tantum nella pagina Paymob. Non prevede carte salvate, abbonamenti, un modulo carta incorporato nel tuo sito né rimborsi dal back office.

Ordini

Stati dell'ordine

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

Payment accepted: Paymob ha confermato il pagamento. Il pagamento viene registrato con l'ID transazione Paymob come ID transazione, e una nota mostra la transazione, l'importo e il tipo di carta con le ultime quattro cifre.

Awaiting Paymob payment: il pagamento è in attesa presso Paymob, per esempio un pagamento in contanti o al chiosco. L'ordine passa a Payment accepted quando Paymob conferma il pagamento.

Paymob payment on hold: Paymob ha solo autorizzato l'importo senza catturarlo (cattura l'importo nella dashboard di Paymob; l'ordine passa a Payment accepted quando arriva il callback di cattura); oppure l'importo o la valuta pagati non corrispondono al carrello (per esempio il carrello è stato modificato dopo l'avvio del pagamento); oppure è arrivato un pagamento per un ordine annullato. La nota spiega il motivo. Controlla l'ordine ed evadilo, oppure rimborsa il pagamento nella dashboard di Paymob.

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

Blocco pagamento Paymob

La pagina dell'ordine mostra un blocco Paymob payment con ogni tentativo Paymob dell'ordine: l'ordine Paymob, l'ID ordine del commerciante e il paese, l'ID transazione Paymob, lo stato, l'importo richiesto, l'importo comunicato da Paymob con la carta e il messaggio di Paymob. Sotto ci sono le Notes del modulo per questo ordine.

Rimborsi

I rimborsi dal back office non sono supportati. Rimborsa o annulla il pagamento nella dashboard di Paymob. Quando Paymob comunica un rimborso o un annullamento, all'ordine viene aggiunta una nota e lo stato dell'ordine non cambia. Aggiorna l'ordine manualmente, per esempio il suo stato oppure con una nota di credito.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Paymob Pay è il primo blocco di Modules > Module Manager > VibeFox Paymob Pay > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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 ci sono la riga Product: presta-payment-paymob 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 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 o License expired on seguito da una data. Dopo un cambio dell'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 solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il relativo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Paymob non viene mostrato ai clienti al 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 hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

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 carrello sia quella del Paymob country selezionato. La pagina delle impostazioni mostra un avviso quando manca qualcosa. 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: i callback non raggiungono il tuo negozio. Verifica che Transaction processed callback e Transaction response callback dell'integrazione che usi siano esattamente l'URL mostrato nel riquadro Callbacks, e che l'HMAC secret sia quello dello stesso account Paymob. I callback rifiutati vengono scritti nel registro come avvisi, anche quando Debug log è disattivato. Controlla il campo Log nella pagina del modulo.

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

Il callback risponde Not configured: l'HMAC secret è vuoto. Inserisci il segreto; Paymob riproverà il callback.

Il callback risponde locked o retry: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento, per esempio il ritorno del cliente, oppure l'ordine non è stato creato (per esempio perché il modulo è disattivato). Paymob riproverà il callback. Il motivo viene scritto nel registro.

Aprire nel browser l'URL del callback porta al checkout con il messaggio could not verify: è normale. L'URL accetta solo richieste firmate da Paymob.

Il cliente vede un errore quando sceglie Paymob: attiva Debug log e controlla il registro. Paymob payments are temporarily unavailable indica un'API key errata o un valore mancante. Paymob could not start the payment indica che Paymob ha rifiutato la richiesta, per esempio per un integration ID errato o dati di fatturazione incompleti. This order cannot be paid with Paymob indica che il totale dell'ordine è zero. Paymob does not accept payments in seguito da una valuta indica che la valuta del carrello non è quella del paese Paymob selezionato.

L'ordine è in Paymob payment on hold o in Awaiting Paymob payment dopo il pagamento: leggi le note nel blocco Paymob payment. Il pagamento è in attesa (contanti o chiosco), la transazione è stata solo autorizzata (catturala nella dashboard di Paymob), l'importo o la valuta non corrispondevano, oppure il pagamento è arrivato dopo l'annullamento dell'ordine.

Pagamenti di test: inserisci l'ID di un'integrazione di test di Paymob in Integration ID e imposta gli URL di callback in quell'integrazione. Per i pagamenti reali inserisci di nuovo l'ID della tua integrazione live.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Paymob Pay 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. I tentativi di pagamento Paymob degli ordini e gli stati dell'ordine Awaiting Paymob payment e Paymob payment on hold vengono sempre mantenuti. Gli ordini esistenti conservano le loro note di pagamento, gli ID transazione e gli ID Paymob.

Paymob è un marchio del rispettivo titolare. Questo modulo non è affiliato a Paymob né approvato da Paymob.