VibeFox ifthenpay 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: solo euro (EUR). Il metodo di pagamento viene nascosto quando la valuta del carrello non è EUR. ifthenpay accetta importi da 0,01 a 99.999,99 EUR.

Account ifthenpay: registrati su ifthenpay.com. Ti serve la chiave del metodo che offri: Multibanco, MB WAY o Credit Card (formato ABC-123456). Le chiavi sono visibili nel backoffice di ifthenpay (backoffice.ifthenpay.com) oppure vengono inviate da ifthenpay quando il metodo viene attivato per il tuo account. ifthenpay deve inoltre attivare il callback per la tua chiave (vedi Configurazione), e il tuo negozio deve essere raggiungibile da internet.

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 VibeFox ifthenpay Gateway più tardi nell'elenco dei moduli e fai clic su Configure. Il modulo genera la sua chiave anti-phishing durante l'installazione.

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

4. Scegli il Payment Method, inserisci la sua chiave ifthenpay e fai clic su Save, in modo che il Callback URL corrisponda al metodo scelto.

5. Copia la Anti-phishing Key e il Callback URL mostrati nelle impostazioni e chiedi a ifthenpay di attivare il callback per la tua chiave (nel backoffice oppure tramite il supporto ifthenpay).

6. Attiva Enable/Disable e fai clic su Save.

All'installazione il modulo crea due stati dell'ordine: Awaiting ifthenpay payment e ifthenpay payment on hold. PrestaShop attiva il nuovo modulo di pagamento per tutte le valute, tutti i paesi e tutti i gruppi di clienti. Puoi limitarli in Payment > Preferences; EUR deve restare consentito.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox ifthenpay Gateway > Configure. Ogni sezione con il pulsante Save salva l'intera pagina. Senza la chiave del metodo selezionato, il metodo di pagamento non viene mostrato al checkout. Finché il gateway è attivo senza quella chiave, la pagina mostra ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.

ifthenpay

Enable/Disable: Enable ifthenpay Payment attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il titolo del metodo di pagamento mostrato al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: ifthenpay.

Description: la descrizione del metodo di pagamento mostrata al checkout. Predefinito: Pay via Multibanco, MB WAY or Credit Card. Modificala in modo che corrisponda al metodo che offri.

Payment Method: il metodo proposto al checkout. È obbligatoria solo la chiave di questo metodo.

Chiavi ifthenpay

Le chiavi (formato ABC-123456) sono visibili nel backoffice di ifthenpay oppure vengono inviate da ifthenpay quando il metodo di pagamento viene attivato per il tuo account.

Multibanco Key: la tua chiave ifthenpay Multibanco (MB) per i riferimenti dinamici.

MB WAY Key: la tua chiave ifthenpay MB WAY.

Credit Card Key: la tua chiave ifthenpay Credit Card. Serve anche a verificare la firma del ritorno del cliente dalla pagina delle carte.

Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarla.

Clear saved keys: seleziona una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Callback (notifiche di pagamento)

Il callback comunica al tuo negozio che un pagamento è stato effettuato. Chiedi a ifthenpay di attivare il callback per ogni chiave che usi, con la chiave anti-phishing e il callback URL indicati qui sotto. Gli ordini Multibanco e MB WAY vengono confermati solo dal callback; i pagamenti con carta vengono confermati anche dal ritorno firmato dalla pagina delle carte.

Anti-phishing Key: generata dal modulo, mostrata per la copia. ifthenpay la rinvia in ogni callback; i callback senza di essa vengono rifiutati.

Callback URL: il callback URL del metodo di pagamento selezionato, con i segnaposto di ifthenpay, mostrato per la copia. Con gli URL parlanti inizia così: https://your-shop/module/wcp_ifthenpay_gateway/callback, eventualmente con un codice lingua come /en/, e prosegue con i parametri del metodo. Copia l'intero URL esattamente come appare nelle impostazioni.

La chiave anti-phishing di ogni callback viene confrontata con la tua. Una chiave mancante o errata riceve la risposta 403, e l'ordine non viene modificato. Il callback deve inoltre corrispondere a un pagamento di questo modulo: per Multibanco tramite entità e riferimento, per MB WAY tramite il carrello e una delle sue richieste MB WAY, per Credit Card tramite il carrello e una delle sue richieste di carta. Senza un callback funzionante, gli ordini Multibanco e MB WAY non vengono mai confermati e i pagamenti con carta vengono confermati solo dal ritorno firmato. Il callback funziona anche mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Avanzate

Test Mode: Credit Card e Multibanco usano gli endpoint sandbox di ifthenpay; non viene addebitato denaro reale e usi le chiavi di test fornite da ifthenpay. MB WAY non ha una sandbox: provalo con una chiave di test di ifthenpay. Il checkout mostra un badge TEST MODE. Predefinito: off.

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento confermato, con un unico cambio di stato.

Debug Log: le richieste API e i callback vengono scritti in logs/ifthenpay_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. Chiavi, chiave anti-phishing e numeri di telefono completi non vengono mai registrati. Predefinito: off.

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

Delete Data on Uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni del modulo, la chiave anti-phishing e il registro. Gli ordini e i record di pagamento ifthenpay restano sempre. Predefinito: off.

Checkout

Multibanco. Al checkout il cliente vede You will receive a Multibanco reference to complete the payment. Quando il cliente conferma, il modulo crea un riferimento Multibanco dinamico per il totale del carrello e l'ordine viene creato in Awaiting ifthenpay payment. La pagina di conferma dell'ordine mostra Multibanco Payment Details: entità, riferimento e importo, con Please use these details to pay at any Multibanco ATM or through your online banking. Gli stessi dati vengono aggiunti all'e-mail di conferma dell'ordine. L'ordine viene pagato quando ifthenpay invia il callback di pagamento.

MB WAY. Il cliente inserisce il MB WAY phone number (912 345 678, +351 912 345 678 oppure 351#912345678 per altri paesi); il telefono dell'indirizzo di fatturazione viene precompilato. Il modulo invia una richiesta di pagamento al telefono e l'ordine viene creato in Awaiting ifthenpay payment. La pagina di conferma dell'ordine dice A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. L'ordine viene pagato quando ifthenpay invia il callback. Viene salvato solo un numero di telefono mascherato.

Carta di credito. Il cliente vede You will be redirected to a secure page to enter your card details. ed è reindirizzato alla pagina delle carte di ifthenpay. Non esiste ancora alcun ordine, e il carrello viene conservato. Dopo un pagamento riuscito il cliente torna nel tuo negozio. Il ritorno viene accettato solo con una firma ifthenpay valida, la chiave sicura del carrello, un segreto di quel tentativo e la richiesta di carta del carrello; a quel punto l'ordine viene creato come pagato e il cliente vede la pagina standard di conferma dell'ordine. Se il ritorno non può essere verificato, non cambia nulla e una pagina Payment confirmation mostra Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. con il pulsante Check again; il callback crea l'ordine appena arriva. Se il pagamento con carta non riesce o viene annullato, il cliente torna al checkout con The card payment was not completed. You can try again or choose another payment method. oppure The card payment was cancelled. You can try again or choose another payment method. Ogni tentativo di pagamento con carta del carrello viene conservato, quindi un pagamento effettuato in una scheda precedente viene comunque accettato.

L'ordine viene segnato come pagato solo dopo la conferma di ifthenpay, e l'importo viene verificato al centesimo rispetto al totale dell'ordine. Se il pagamento non può essere avviato, il cliente resta al checkout con un breve messaggio, per esempio The Multibanco reference could not be created. Please try again or choose another payment method., The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. oppure The payment service is temporarily unavailable. Please try again in a few minutes. Il motivo tecnico viene scritto nel registro.

Il modulo offre un metodo ifthenpay alla volta. Non prevede Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX o Pay-by-Link, né abbonamenti o carte salvate, né scadenza o annullamento automatico dei riferimenti Multibanco non pagati, né verifica dello stato del pagamento.

Ordini

Stati dell'ordine

No order yet: un pagamento con carta è stato avviato ma non è ancora confermato, oppure è fallito o è stato annullato. Esiste solo il carrello.

Awaiting ifthenpay payment: è stato emesso un riferimento Multibanco o è stata inviata una richiesta MB WAY. PrestaShop riduce le scorte quando l'ordine viene creato. I riferimenti non pagati e le richieste MB WAY rifiutate non annullano automaticamente l'ordine; annulla tu questi ordini, se necessario.

Payment accepted or Delivered: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con il riferimento Multibanco, l'ID della richiesta MB WAY o l'ID della richiesta di carta come ID transazione, e una nota indica come è stato confermato.

ifthenpay payment on hold: l'importo ricevuto era diverso dal totale dell'ordine (per esempio, il carrello è stato modificato dopo l'avvio di un pagamento con carta), oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota lo spiega, e al cliente non viene chiesto di pagare di nuovo. Verifica il pagamento nel backoffice di ifthenpay e completa o rimborsa l'ordine manualmente. Un successivo pagamento corretto per questo ordine non lo modifica.

Un secondo pagamento per un ordine già pagato aggiunge solo una nota, per controllare nel backoffice di ifthenpay un eventuale pagamento duplicato. Gli ordini rimborsati e gli ordini annullati dopo il pagamento non vengono mai riaperti.

Blocco dei pagamenti ifthenpay

La pagina dell'ordine mostra un blocco ifthenpay payment con i tentativi di pagamento dell'ordine (data, metodo, un badge Sandbox per i pagamenti di test, importo, entità e riferimento Multibanco oppure il numero MB WAY mascherato, ID richiesta ifthenpay e stato), un avviso Manual review mentre l'ordine è in ifthenpay payment on hold, e le ifthenpay notes dell'ordine.

Rimborsi

I rimborsi da PrestaShop non sono supportati. Rimborsa il pagamento nel backoffice di ifthenpay e registralo manualmente in PrestaShop. Un callback di rimborso (DEVOLVIDO) aggiunge solo una nota. Anche gli altri stati comunicati da ifthenpay aggiungono solo una nota.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox ifthenpay Gateway è il primo blocco in Modules > Module Manager > VibeFox ifthenpay Gateway > 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. Più sotto si trovano la riga Product: presta-payment-ifthenpay 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 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 solo dominio: quello 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, ifthenpay 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 alla settimana. Non serve alcun cron job. Disinstallando o reimpostando il modulo, vengono sempre rimossi la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

ifthenpay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la chiave del Payment Method selezionato sia compilata, che la valuta del carrello sia EUR e che il totale sia compreso tra 0,01 e 99.999,99 EUR. In Payment > Preferences verifica che il modulo sia consentito per EUR, per il paese del cliente e per il gruppo del cliente.

Il cliente ha pagato, ma l'ordine resta in Awaiting ifthenpay payment oppure non è stato creato alcun ordine: il callback non raggiunge il tuo negozio. Verifica che ifthenpay abbia attivato il callback URL e la chiave anti-phishing per la chiave che usi, e che l'URL sia quello del metodo selezionato. Il negozio deve essere raggiungibile da internet, non su localhost e non dietro un login. Cerca le righe Callback rejected nel campo Log nella pagina del modulo.

Il callback risponde 403 Forbidden: la chiave anti-phishing nel callback manca oppure è diversa da quella nelle impostazioni. Invia di nuovo a ifthenpay la chiave mostrata nelle impostazioni.

Il callback risponde 503 Not configured: la chiave anti-phishing non è ancora stata generata. Apri una volta le impostazioni del modulo; ifthenpay riproverà il callback.

Il callback risponde 503 Busy: lo stesso carrello era in elaborazione da un'altra richiesta in quel momento. ifthenpay riproverà il callback.

Il callback risponde Order not found: il riferimento o la richiesta non appartiene a un pagamento di questo modulo, oppure il carrello è stato ordinato con un altro metodo di pagamento.

Perché un ordine pagato è stato messo in attesa? L'importo ricevuto era diverso dal totale dell'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Leggi le note nel blocco ifthenpay payment, verifica il pagamento nel backoffice di ifthenpay e completa o rimborsa l'ordine manualmente.

Impossibile inviare la richiesta MB WAY: il numero di telefono non è collegato a MB WAY oppure è nel formato sbagliato. Usa 912 345 678, oppure 351#912345678 per i numeri di altri paesi.

Modalità test e MB WAY: ifthenpay non ha una sandbox MB WAY; usa una chiave di test fornita da ifthenpay.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox ifthenpay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni del modulo, la chiave anti-phishing e il registro; dopo una reinstallazione viene generata una nuova chiave anti-phishing, che va inviata di nuovo a ifthenpay. Se è disattivo, tutte le impostazioni vengono conservate per una futura reinstallazione. I record di pagamento ifthenpay (riferimenti e ID richiesta) e gli stati dell'ordine Awaiting ifthenpay payment e ifthenpay payment on hold restano sempre, così i callback per riferimenti emessi in precedenza trovano ancora i loro ordini dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

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