VibeFox Satispay 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 con l'estensione OpenSSL. Senza OpenSSL il plugin mostra un errore nell'area di amministrazione e il metodo di pagamento non viene caricato.

Valuta: EUR. Satispay accetta solo euro, quindi il metodo di pagamento viene nascosto quando la valuta del negozio (o, nella pagina Pay for order, la valuta dell'ordine) non è EUR.

Account Satispay: un account Satispay Business. Non copi alcuna chiave API: il plugin si collega con un codice di attivazione monouso che generi nel Satispay Business Dashboard (vedi Configurazione). Per i test ti serve un account sandbox Satispay, da richiedere a Satispay for developers.

Sito pubblico: il tuo sito deve essere raggiungibile da internet, così che Satispay possa richiamarlo quando cambia un pagamento. Non c'è nulla da configurare in Satispay per questo.

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

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Satispay > 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 l'ambiente: spunta Sandbox Mode per i test, lascialo deselezionato per i pagamenti reali.

6. Incolla in Activation Code un codice di attivazione di quell'ambiente e salva. Lo stato della connessione mostrerà poi il Key ID.

7. Attiva Enable/Disable e salva. Prova un pagamento in sandbox, poi deseleziona Sandbox Mode e collega l'ambiente live con un codice di attivazione live.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > Satispay. La sezione Satispay connection mostra lo stato di entrambi gli ambienti, per esempio Live: Connected con il Key ID oppure Sandbox: Not connected, e segnala l'ambiente in uso. Finché l'ambiente in uso non è collegato, la pagina indica: Satispay è nascosto al checkout finché l'ambiente in uso non è collegato. Nell'elenco dei metodi di pagamento di WooCommerce, Satispay risulta da configurare finché l'ambiente in uso non è collegato, e mostra un badge di modalità test mentre Sandbox Mode è attivo.

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

Checkout

Ciò che i clienti vedono nell'elenco dei metodi di pagamento.

Title: il nome del metodo di pagamento mostrato al checkout. Predefinito: Satispay.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

Satispay connection

Sandbox Mode: Use the Satispay sandbox (staging) environment. I pagamenti in sandbox non vengono addebitati. Predefinito: disattivato. Sandbox e live hanno chiavi separate: collega ogni ambiente con un codice di attivazione di quell'ambiente. Mentre la sandbox è in uso, i clienti vedono Modalità sandbox: non viene addebitato denaro reale. sotto il metodo di pagamento.

Activation Code: per collegare l'ambiente selezionato sopra, incolla un nuovo codice di attivazione a 6 caratteri e salva. I codici live si generano nel Satispay Business Dashboard, sezione Online shop. I codici sandbox si ottengono con un account sandbox Satispay. Il codice viene usato una sola volta e non viene memorizzato. Lascia il campo vuoto per mantenere la connessione attuale.

Quando salvi con un codice, il plugin crea una coppia di chiavi RSA, invia la chiave pubblica e il codice a Satispay e salva nel database di WordPress il Key ID e le chiavi di quell'ambiente. In caso di successo la pagina mostra, per esempio, Satispay Live connected. Key ID: seguito dall'ID. Se Satispay rifiuta il codice, la pagina mostra il messaggio di Satispay e ti chiede di verificare che il codice sia per questo ambiente e non sia già stato usato. Un codice con caratteri diversi da lettere e cifre viene rifiutato prima di inviare qualsiasi cosa. Salvare un nuovo codice per un ambiente sostituisce la sua connessione precedente.

Payment notifications

Non c'è nulla da configurare in Satispay. Ogni pagamento ha la propria URL di callback, che Satispay richiama quando il pagamento cambia, e il plugin rilegge il pagamento dalle API di Satispay prima di modificare un ordine. La sezione mostra un esempio di questa URL. Ha questo aspetto: https://your-site/wc-api/satispay_payment_callback/?action=callback&order_id={order}&payment_id={uuid}. La URL deve essere raggiungibile da internet: nessuna modalità manutenzione né protezione con password su /wc-api/.

Advanced

Debug log: Log API calls and payment events scrive in WooCommerce > Status > Logs, origine wcp_satispay_gateway, senza chiavi né dati dei clienti. Gli errori vengono sempre registrati, anche se questa opzione è disattivata. Predefinito: disattivato.

Delete data on uninstall: Remove the settings and Satispay keys when the plugin is deleted. I dati di pagamento salvati sugli ordini vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Satispay) e fa clic su Pay with Satispay. Il plugin crea un pagamento Satispay per il totale dell'ordine in euro, con il numero d'ordine come riferimento, e invia il cliente alla pagina di pagamento Satispay. Su un computer il cliente inquadra il codice QR con l'app Satispay. Su un telefono il cliente conferma il pagamento nell'app.

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo quando Satispay lo conferma: il plugin legge il pagamento dalle API di Satispay, verifica che sia stato creato per questo ordine e confronta stato, importo (in centesimi) e valuta con l'ordine. Ciò avviene sia quando Satispay richiama la URL di callback sia quando il cliente torna, a seconda di quale arriva per primo. Se il pagamento non è ancora confermato, la pagina di ricezione dell'ordine mostra: Satispay non ha ancora confermato il tuo pagamento. L'ordine verrà aggiornato automaticamente non appena arriverà la conferma.

Se il cliente lascia la pagina Satispay senza pagare, il plugin annulla il pagamento presso Satispay, così la pagina abbandonata non può più essere pagata. Il cliente viene rimandato al checkout (o alla pagina Pay for order) con il messaggio Il tuo pagamento Satispay è stato annullato e non è stato addebitato nulla. Puoi riprovare o scegliere un altro metodo di pagamento. Lo stesso messaggio appare quando il cliente rifiuta il pagamento nell'app.

Un cliente può pagare di nuovo un ordine non pagato, per esempio dalla pagina Pay for order. Prima di creare un nuovo pagamento Satispay, quello precedente viene verificato: un pagamento in sospeso viene annullato presso Satispay e, se era già stato pagato, l'ordine viene segnato come pagato con quel pagamento e non viene creato un secondo addebito.

Se il pagamento non può essere avviato, il cliente vede un breve messaggio e può scegliere un altro metodo di pagamento: Satispay non è disponibile al momento. Scegli un altro metodo di pagamento. quando il negozio non è collegato o Satispay rifiuta le chiavi, oppure Impossibile creare il pagamento Satispay. Riprova o scegli un altro metodo di pagamento. per gli altri errori. Il motivo viene scritto nel log.

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 solo pagamenti singoli in euro. Non supporta abbonamenti, metodi di pagamento salvati, pre-autorizzazioni o buoni pasto. Non esiste un controllo programmato dei pagamenti in sospeso: se né la callback di Satispay né il ritorno del cliente raggiungono il tuo sito, l'ordine resta In attesa di pagamento, e il pagamento è visibile nel Satispay Dashboard.

Ordini e rimborsi

Order statuses

Pending payment: il cliente è stato inviato a Satispay e non ha ancora pagato, oppure Satispay non ha ancora confermato il pagamento. La nota dell'ordine mostra l'ID del pagamento Satispay, l'importo e l'ambiente (Live o Sandbox).

Processing or Completed: il pagamento è stato confermato. L'ordine segue la regola standard di WooCommerce: In elaborazione, oppure Completato per gli ordini con solo prodotti virtuali scaricabili. La nota dell'ordine mostra il pagamento Satispay, l'importo e come è stato verificato (callback, reindirizzamento o checkout). L'ID transazione è l'ID del pagamento Satispay.

On hold: Satispay ha segnalato un importo o una valuta diversi dal totale dell'ordine, oppure il pagamento è stato accettato dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega, e il pagamento viene salvato come ID transazione, così può essere rimborsato. Verifica il pagamento nel Satispay Dashboard, poi completa l'ordine oppure rimborsa il pagamento.

Cancelled: l'ultimo pagamento Satispay dell'ordine è stato annullato o è scaduto, per esempio perché il cliente ha lasciato la pagina Satispay. Un pagamento precedente che scade non annulla un ordine con un pagamento più recente in corso. Gli ordini creati nell'area di amministrazione (link di pagamento) non vengono annullati: restano In attesa di pagamento con una nota, così il cliente può ancora pagarli.

Se per un ordine già pagato viene accettato un secondo pagamento, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato dal Satispay Dashboard. Una conferma ripetuta non riapre mai un ordine annullato o rimborsato.

Refunds

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Satispay. Sono supportati rimborsi totali e parziali per gli ordini pagati con Satispay. Il rimborso viene inviato all'ambiente in cui è stato effettuato il pagamento (live o sandbox), quindi quell'ambiente deve restare collegato. Un rimborso è considerato completato solo quando Satispay lo accetta: un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID del rimborso Satispay e il motivo. Se Satispay non accetta il rimborso, WooCommerce mostra l'errore e non viene registrato alcun rimborso.

I rimborsi effettuati nel Satispay Dashboard non vengono trasformati in rimborsi WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza usare Refund via Satispay.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Satispay. 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 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 suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Satispay non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. Gli amministratori del negozio collegati continuano a vedere il metodo di pagamento, contrassegnato come (senza licenza: visibile solo agli amministratori), 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 e i rimborsi funzionano.

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

Risoluzione dei problemi

Satispay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che l'ambiente in uso sia collegato (la sezione Satispay connection mostra Connected per esso) e che la valuta sia EUR.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: l'ordine viene aggiornato quando Satispay richiama il tuo sito oppure quando il cliente torna. Verifica che il sito sia raggiungibile da internet, senza modalità manutenzione né protezione con password su /wc-api/, e controlla WooCommerce > Status > Logs, origine wcp_satispay_gateway. Il pagamento è visibile nel Satispay Dashboard.

La callback risponde Payment status unavailable, retry later oppure Not configured: il plugin non è riuscito a leggere il pagamento da Satispay, oppure l'ambiente dell'ordine non è collegato. L'ordine non viene modificato. Controlla lo stato della connessione e il log.

La callback risponde Busy, retry later: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Questa callback non modifica l'ordine. Verrà aggiornato dalla callback successiva oppure quando il cliente torna.

La callback risponde Unknown payment oppure Missing or invalid payment_id: il pagamento non è stato creato per questo ordine, oppure la richiesta non è una callback di Satispay. L'ordine non viene modificato.

L'attivazione non riesce: i codici di attivazione possono essere usati una sola volta. Verifica che il codice appartenga all'ambiente selezionato in Sandbox Mode (un codice live per il live, un codice sandbox per la sandbox), genera un nuovo codice e salva di nuovo. Se la pagina dice che non è stato possibile generare una coppia di chiavi RSA, chiedi al tuo hosting di attivare l'estensione PHP OpenSSL.

Satispay è scomparso dal checkout dopo il passaggio da sandbox a live: sandbox e live usano chiavi diverse. Incolla un codice di attivazione live con Sandbox Mode deselezionato e salva.

L'ordine è On hold e la nota non corrisponde all'ordine: Satispay ha segnalato un importo o una valuta diversi dal totale dell'ordine, per esempio perché l'ordine è stato modificato dopo l'avvio del pagamento. Verifica il pagamento nel Satispay Dashboard, poi completa l'ordine oppure rimborsa il pagamento.

Il rimborso non riesce perché l'ambiente non è più collegato: il pagamento è stato effettuato in live o in sandbox, e quell'ambiente non ha più chiavi. Ricollegalo con un codice di attivazione, oppure rimborsa il pagamento dal Satispay Dashboard.

Il rimborso non riesce con Satispay did not accept the refund: Satispay ha restituito uno stato diverso da accepted. WooCommerce non ha registrato il rimborso. Verificalo nel Satispay Dashboard.

Il blocco della 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, le chiavi Satispay di entrambi gli ambienti e i log del plugin vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

Satispay è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Satispay.