VibeFox ifthenpay for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.
PHP: 8.0 o successivo.
Valuta: solo euro (EUR). Il metodo di pagamento viene nascosto quando la valuta del negozio o dell'ordine non è EUR. ifthenpay accetta totali 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 mostrate nel backoffice di ifthenpay (backoffice.ifthenpay.com) oppure 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: 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. In alternativa puoi caricare la cartella wcp_ifthenpay_gateway in /wp-content/plugins/ via FTP.
2. Fai clic su Activate. Il plugin genera la sua chiave anti-phishing.
3. Apri le impostazioni: WooCommerce > Settings > Payments > ifthenpay > 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 alto nella pagina e fai clic su Activate.
5. Scegli il Payment Method e inserisci la sua chiave ifthenpay. Salva, così che il Callback URL corrisponda al metodo scelto.
6. 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 o tramite il supporto ifthenpay).
7. Attiva Enable/Disable.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > ifthenpay. Senza la chiave del metodo selezionato il metodo di pagamento non viene mostrato al checkout, e nell'elenco dei metodi di pagamento risulta come da completare. Quando salvi un 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.
Enable/Disable: Enable ifthenpay Payment attiva o disattiva il metodo di pagamento. Predefinito: disattivo.
Title: il titolo del metodo di pagamento mostrato al checkout. 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 offerto al checkout. È richiesta solo la chiave di questo metodo.
Chiavi ifthenpay
Le chiavi (formato ABC-123456) sono mostrate nel backoffice di ifthenpay oppure 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 della carta.
Callback (notifiche di pagamento)
Il callback comunica al negozio che un pagamento è stato effettuato. Chiedi a ifthenpay di attivare il callback per ogni chiave che usi, con la chiave anti-phishing e l'URL del callback 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 della carta.
Anti-phishing Key: generata dal plugin, mostrata per la copia. ifthenpay la rimanda in ogni callback; i callback senza di essa vengono rifiutati.
Callback URL: l'URL del callback per il metodo di pagamento selezionato, con i segnaposto di ifthenpay, mostrato per la copia. Inizia con https://your-site/wc-api/ifthenpay_payment_callback/ e prosegue con i parametri del metodo. Copia l'URL completo esattamente come lo mostrano le 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 cambia. Il callback deve inoltre corrispondere a un ordine di questo gateway: per Multibanco tramite entità e riferimento, per MB WAY tramite l'ordine e una delle sue richieste MB WAY, per la carta di credito tramite l'ordine e la sua richiesta 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.
Avanzate
Test Mode: Enable test/sandbox mode. Carta di credito 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 sandbox: provalo con una chiave di test di ifthenpay. Il checkout mostra un badge TEST MODE. Predefinito: disattivo.
Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento confermato, con un solo cambio di stato e una sola e-mail al cliente. Gli ordini che contengono solo prodotti digitali scaricabili vengono sempre completati da WooCommerce.
Debug Log: Enable logging. Le richieste API e i callback vengono scritti in WooCommerce > Status > Logs, origine wcp_ifthenpay_gateway. Gli errori vengono sempre registrati. Chiavi, chiave anti-phishing e numeri di telefono non vengono mai registrati. Predefinito: disattivo.
Delete Data on Uninstall: Remove the plugin settings, the anti-phishing key and the logs when the plugin is deleted (orders are kept). Predefinito: disattivo.
Checkout
Multibanco. Al checkout il cliente vede You will receive a Multibanco reference to complete the payment. Quando l'ordine viene effettuato, il plugin crea un riferimento Multibanco dinamico per il totale dell'ordine. L'ordine passa In attesa, le scorte vengono ridotte e il carrello viene svuotato. La pagina di ringraziamento e le e-mail dell'ordine inviate mentre l'ordine è In attesa mostrano Multibanco Payment Details: entità, riferimento e importo, con Please use these details to pay at any Multibanco ATM or through your online banking. Se il cliente effettua di nuovo l'ordine con lo stesso importo, viene riutilizzato lo stesso riferimento. L'ordine viene confermato quando ifthenpay invia il callback di pagamento.
MB WAY. Il cliente inserisce il MB WAY phone number (912 345 678, +351 912 345 678 o 351#912345678 per altri paesi); il telefono di fatturazione viene compilato. Il plugin invia una richiesta di pagamento al telefono, l'ordine passa In attesa, le scorte vengono ridotte e il carrello viene svuotato. La pagina di ringraziamento indica A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. Tutte le richieste dell'ordine vengono conservate, quindi una richiesta precedente approvata nell'app viene comunque accettata. L'ordine viene confermato dal callback.
Carta di credito. Il cliente vede You will be redirected to a secure page to enter your card details. ed è inviato alla pagina delle carte di ifthenpay. L'ordine resta In attesa di pagamento finché non viene pagato, e le scorte non vengono ridotte prima. Dopo un pagamento riuscito il cliente torna nel tuo negozio. Il ritorno viene accettato solo con una firma valida di ifthenpay, la chiave dell'ordine, un segreto di quel tentativo e la richiesta di carta dell'ordine; a quel punto l'ordine viene segnato come pagato. Se il ritorno non può essere verificato, l'ordine non cambia e la pagina di ringraziamento mostra Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. Un pagamento con carta non riuscito imposta l'ordine su Non riuscito, e uno annullato lo lascia In attesa di pagamento. In entrambi i casi il cliente va alla pagina Pay for order con The card payment was not completed. You can try again or choose another payment method. o The card payment was cancelled. You can try again or choose another payment method.
L'ordine viene segnato come pagato solo dopo che ifthenpay conferma il pagamento, e l'importo viene verificato al centesimo rispetto al totale dell'ordine. Se il pagamento non può essere avviato, il cliente vede 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 metodo di pagamento funziona nel checkout classico, nei blocchi Carrello e Checkout (con il campo telefono MB WAY) e nella pagina Pay for order. È compatibile con l'archiviazione degli ordini ad alte prestazioni di WooCommerce (HPOS).
Il plugin 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
On hold (waiting for payment): è stato emesso un riferimento Multibanco oppure è stata inviata una richiesta MB WAY. I riferimenti non pagati non vengono annullati automaticamente; annulla tu questi ordini, se necessario.
Pending payment: è stato avviato un pagamento con carta non ancora confermato, oppure è stato annullato.
Processing or Completed: il pagamento è stato confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra l'entità e il riferimento Multibanco, la transazione MB WAY o l'ID della richiesta di carta.
On hold after payment: l'importo ricevuto era diverso dal totale dell'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega. Verifica il pagamento nel backoffice di ifthenpay e completa o rimborsa l'ordine manualmente.
Failed: il cliente è tornato dalla pagina della carta con un errore.
Una seconda notifica di pagamento per un ordine già pagato aggiunge solo una nota, per controllare un possibile pagamento duplicato nel backoffice di ifthenpay. Gli ordini rimborsati e quelli annullati dopo il pagamento non vengono mai riaperti.
Rimborsi
I rimborsi da WooCommerce non sono supportati. Rimborsa il pagamento nel backoffice di ifthenpay e registralo manualmente in WooCommerce. Un callback di rimborso (DEVOLVIDO) aggiunge solo una nota all'ordine. Anche gli altri stati comunicati da ifthenpay aggiungono solo una nota.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in alto in WooCommerce > Settings > Payments > ifthenpay. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per 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. 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. I gestori del negozio con l'accesso vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare 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.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.
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 sia EUR e che il totale sia compreso tra 0,01 e 99.999,99 EUR. Nella pagina Pay for order conta la valuta dell'ordine.
Il cliente ha pagato, ma l'ordine resta On hold o Pending payment: il callback non raggiunge il tuo negozio. Verifica che ifthenpay abbia attivato l'URL del callback e la chiave anti-phishing per la chiave che usi, e che l'URL sia quello del metodo selezionato. Il sito deve essere raggiungibile da internet, non su localhost e non dietro un login. Cerca le righe Callback rejected in WooCommerce > Status > Logs, origine wcp_ifthenpay_gateway.
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 è stata ancora generata. Apri una volta la pagina delle impostazioni; ifthenpay riproverà il callback.
Il callback risponde Order not found: il riferimento o la richiesta non appartiene a un ordine di questo gateway, per esempio perché il metodo di pagamento è stato cambiato dopo l'ordine.
Perché un ordine pagato è stato messo On hold? L'importo ricevuto era diverso dal totale dell'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. Leggi la nota dell'ordine, 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 ha un formato errato. Usa 912 345 678, oppure 351#912345678 per i numeri di altri paesi.
Modalità test e MB WAY: ifthenpay non ha una sandbox per MB WAY; usa una chiave di test fornita da ifthenpay.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per 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, la chiave anti-phishing e i log vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini e i loro dati ifthenpay (riferimenti, ID delle richieste) vengono sempre conservati. Gli ordini esistenti conservano le loro note di pagamento e gli ID delle transazioni.
ifthenpay è un marchio del suo rispettivo titolare. Questo plugin non è affiliato a ifthenpay né approvato da ifthenpay.