VibeFox Redsys 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.
Conto esercente Redsys: la tua banca (l'acquirer che ti ha fornito il POS virtuale Redsys) ti fornisce il codice esercente (FUC), il numero del terminale e l'accesso al pannello di amministrazione Redsys, dove è mostrata la chiave segreta SHA-256 di ciascun ambiente. La chiave dell'ambiente di prova è diversa da quella reale. La notifica online (HTTP) deve essere attiva per il tuo terminale. Chiedi alla tua banca se non sei sicuro.
Valuta del negozio: una delle valute supportate dal plugin (vedi Configurazione), e la tua banca deve aver abilitato il terminale Redsys per essa. La maggior parte dei terminali accetta solo EUR.
Sito raggiungibile: Redsys deve poter raggiungere il tuo sito da internet, senza login né blocchi del firewall, per recapitare le notifiche di pagamento.
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_redsys_gateway in /wp-content/plugins/ tramite FTP.
2. Fai clic su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Redsys > 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. Inserisci il codice esercente, il terminale e la chiave segreta di ciascun ambiente (vedi Configurazione).
6. Attiva Enable/Disable. Prova un pagamento con Test Mode attivo, poi deseleziona Test Mode per accettare pagamenti reali.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Redsys. Sopra i campi, la pagina ti avvisa quando il codice esercente manca o non è composto solo da cifre, quando una chiave segreta non è una chiave SHA-256 Redsys valida, quando la chiave della modalità attuale è vuota (in tal caso il metodo di pagamento viene nascosto al checkout) e quando la valuta del negozio non è supportata. Con la modalità di prova attiva mostra Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. Dopo il salvataggio, gli avvisi seguono subito le nuove impostazioni. Nell'elenco dei metodi di pagamento, Redsys risulta da configurare finché codice esercente, terminale e chiave della modalità attuale non sono validi.
Generali
Enable/Disable: Enable Redsys Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Credit/Debit Card (Redsys).
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with your credit or debit card via Redsys.
Conto Redsys
La tua banca ti fornisce il codice esercente, il terminale e l'accesso al pannello di amministrazione Redsys, dove è mostrata la chiave segreta SHA-256 di ciascun ambiente. La sezione include un link al pannello di amministrazione Redsys.
Merchant Code (FUC): il tuo codice esercente Redsys, fino a 9 cifre. Qualsiasi carattere che non sia una cifra viene rimosso al salvataggio.
Terminal Number: il numero del terminale assegnato dalla tua banca, fino a 3 cifre. Predefinito: 1. Un campo vuoto viene salvato come 1.
Secret Key (SHA-256) — live: la chiave SHA-256 in Base64 dell'ambiente reale (di produzione). Viene usata quando la modalità di prova è disattivata.
Modalità di prova (SIS-T)
L'ambiente di prova di Redsys ha una propria chiave segreta. La sezione mostra i dati pubblici di prova di Redsys: codice esercente 999008881, terminale 1, chiave sq7HjrUOBfKmC576ILgskD5srU870gJ7, carta 4548 8100 0000 0003, scadenza 12/49, CVV 123. In modalità di prova non viene addebitato denaro reale.
Test Mode: Enable test mode invia pagamenti e rimborsi all'ambiente di prova di Redsys (SIS-T) e li firma con la chiave di prova. Predefinito: attivo. Deselezionalo per accettare pagamenti reali. Quando è attivo, il checkout mostra TEST MODE: Redsys test environment, no real money is charged. sotto il metodo di pagamento.
Secret Key (SHA-256) — test: la chiave SHA-256 in Base64 dell'ambiente di prova. Usa la tua chiave di prova o la chiave pubblica di prova indicata sopra.
Pagina di pagamento e ordini
Commerce Name: il nome del negozio mostrato sulla pagina di pagamento Redsys, al massimo 25 caratteri. Predefinito: il nome del tuo sito, troncato a 25 caratteri.
Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito. Lo stato viene impostato una sola volta, così il cliente riceve una sola email.
Notifiche di pagamento
Redsys comunica ogni pagamento all'indirizzo di notifica del tuo negozio. Ha il formato https://your-site/wc-api/rdsg_redsys/ ed è mostrato in questa sezione. Il plugin lo invia a Redsys con ogni pagamento, quindi non c'è nulla da copiare nel pannello Redsys. La notifica online (HTTP) deve essere attiva per il tuo terminale. Chiedi alla tua banca se gli ordini restano in attesa di pagamento dopo un pagamento riuscito. Le notifiche senza firma valida vengono rifiutate. Senza la notifica, un ordine non viene segnato come pagato.
Avanzate
Debug log: Enable debug logging scrive i dettagli di pagamenti, notifiche e rimborsi in WooCommerce > Status > Logs, origine wcp_redsys_gateway. Gli errori vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, firme e dati della carta non vengono mai registrati. Predefinito: disattivato.
Delete Data: Delete the gateway settings when the plugin is deleted. Se attivo, eliminando il plugin vengono rimosse le impostazioni del gateway e i log del plugin. Predefinito: disattivato.
Valute supportate
EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD. Il metodo di pagamento viene nascosto per le altre valute. Nella pagina Pay for order conta la valuta dell'ordine.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card (Redsys)) e invia l'ordine. L'ordine passa allo stato in attesa di pagamento e il cliente vede Redirecting to Redsys for payment. Please wait..., poi viene portato alla pagina di pagamento Redsys della tua banca. Se il browser non prosegue da solo, il cliente fa clic su Pay via Redsys. Sulla pagina Redsys il cliente paga con carta tramite 3-D Secure, oppure con Bizum o un altro metodo abilitato dalla tua banca per il terminale. La pagina usa la lingua del tuo negozio (spagnolo, inglese, catalano, francese, tedesco, italiano, portoghese e altre), o l'inglese per le altre lingue.
L'importo viene inviato nelle unità minori della valuta dell'ordine, per esempio EUR 43,45 come 4345, e JPY o CLP senza decimali. Il pagamento viene descritto come Order con il numero d'ordine e il nome del tuo sito. Le scorte vengono ridotte quando il pagamento è confermato, non prima.
Dopo il pagamento, il cliente torna alla pagina «Ordine ricevuto» del tuo negozio. L'ordine viene segnato come pagato solo dopo che Redsys lo conferma con la notifica firmata. Finché non arriva, la pagina mostra Redsys is confirming your payment. If you completed the payment, your order will be updated in a few moments — please do not pay again.
Se il cliente annulla o il pagamento viene rifiutato, Redsys riporta il cliente nel tuo negozio. Per un ordine del checkout, l'ordine viene annullato nel modo standard di WooCommerce e il carrello viene conservato. Per un ordine creato da te nel pannello admin (un link di pagamento), il cliente torna alla pagina Pay for order con il messaggio The Redsys payment was not completed. You can try again or choose another payment method., e l'ordine non viene annullato. La pagina di reindirizzamento del tuo negozio offre anche Cancel order & restore cart oppure, per gli ordini creati nel pannello admin, Choose another payment method.
Un cliente può pagare di nuovo un ordine non pagato dalla pagina Pay for order. Ogni tentativo riceve un nuovo numero d'ordine Redsys, e un pagamento effettuato da uno qualsiasi di essi, per esempio da una seconda scheda del browser, viene comunque riconosciuto.
Se l'ordine non può essere inviato a Redsys, il cliente vede un breve messaggio e può scegliere un altro metodo di pagamento: Redsys payments are not configured correctly. Please choose another payment method or contact us., un messaggio che la valuta non è accettata, oppure The order total must be greater than zero.
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 pagamenti singoli, autorizzati e acquisiti subito nella pagina Redsys. Non ha un modulo carta sul tuo sito (InSite o iframe), né carte salvate, pagamenti con un clic o tokenizzazione, né abbonamenti o pagamenti ricorrenti, né preautorizzazione con acquisizione successiva, né notifiche SOAP.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Redsys e non ha ancora pagato, oppure la notifica di Redsys non è ancora arrivata. La nota dell'ordine dice Awaiting Redsys payment.
Processing, Completed or On Hold: il pagamento è stato confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra il numero d'ordine Redsys (Ds_Order), il codice di autorizzazione e il codice di risposta, contrassegnato con [TEST] per i pagamenti di prova. L'ID transazione dell'ordine è il numero d'ordine Redsys.
On hold after payment: Redsys ha comunicato un importo o una valuta diversi dal totale dell'ordine, un pagamento di prova è arrivato mentre il negozio è in live (non è stato addebitato denaro reale), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota dell'ordine lo spiega. Verifica il pagamento nel pannello di amministrazione Redsys, poi evadi l'ordine o rimborsa il pagamento.
Failed: il pagamento è stato rifiutato o annullato presso Redsys. La nota dell'ordine mostra il codice di risposta e, per i codici più frequenti, un breve motivo come Insufficient funds, Card expired o Cancelled by the customer. Solo un ordine che attende ancora il pagamento diventa Non riuscito. Un ordine pagato o chiuso non viene mai modificato da un tentativo rifiutato: il tentativo viene solo annotato.
Cancelled: il cliente ha annullato il pagamento, oppure l'ordine è stato annullato da te o dal timeout di blocco scorte di WooCommerce.
Se per un ordine già pagato o rimborsato arriva un secondo pagamento diverso, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato nel pannello di amministrazione Redsys. Se Redsys indica che un pagamento è ancora in corso, viene aggiunta una nota e l'ordine attende l'esito definitivo.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic sul pulsante di rimborso tramite il metodo di pagamento Redsys (per impostazione predefinita Refund via Credit/Debit Card (Redsys)). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato tramite la REST API di Redsys all'ambiente in cui è stato effettuato il pagamento (prova o live), firmato con la chiave di quell'ambiente, e viene verificata la firma della risposta. Se Redsys non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con il numero d'ordine Redsys e il motivo.
I rimborsi effettuati nel pannello di amministrazione Redsys non vengono registrati come rimborsi WooCommerce. Quando Redsys invia una notifica al riguardo, viene aggiunta una nota all'ordine. Se necessario, crea un rimborso manuale in WooCommerce senza usare il pulsante di rimborso Redsys.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Redsys. 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 dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.
Senza una chiave attiva, Redsys 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 collegati vedono ancora il metodo di pagamento, contrassegnato come (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 ancora 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
Redsys non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che codice esercente e terminale siano compilati e che la modalità attuale abbia una chiave valida: Secret Key (SHA-256) — test in modalità di prova, Secret Key (SHA-256) — live in modalità live. Controlla che la valuta del negozio (nella pagina Pay for order, la valuta dell'ordine) sia nell'elenco delle valute supportate. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: la notifica Redsys non è arrivata al tuo negozio. Chiedi alla tua banca di verificare che la notifica online (HTTP) sia attiva per il tuo terminale. Controlla che l'indirizzo mostrato in Notifiche di pagamento sia raggiungibile da internet senza login, senza pagina di manutenzione e senza blocchi del firewall. Attiva Debug log e consulta WooCommerce > Status > Logs, origine wcp_redsys_gateway.
La notifica risponde Forbidden: la firma non corrispondeva alla chiave segreta dell'ambiente in cui è stato avviato il pagamento, oppure il codice esercente nella notifica non è il tuo. Verifica che le chiavi segrete e il codice esercente nelle impostazioni siano quelli del tuo terminale.
La notifica risponde Order not found: la notifica era firmata correttamente, ma nessun ordine di questo negozio usa quel numero d'ordine Redsys.
La notifica risponde Busy: l'ordine era in elaborazione da un'altra notifica nello stesso momento. Redsys riprova la notifica.
La notifica risponde Bad request: la richiesta non aveva parametri Redsys o erano danneggiati. Non proveniva da Redsys nel formato previsto.
L'ordine è On hold after payment: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi dall'ordine, un pagamento di prova è arrivato mentre il negozio è in live, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Evadi l'ordine o rimborsa il pagamento.
I pagamenti di prova non confermano gli ordini in live: un pagamento di prova non paga mai un ordine finché Test Mode è disattivato. L'ordine viene invece messo in attesa con una nota. Usa la modalità di prova con la chiave di prova per i pagamenti di prova.
Il rimborso non riesce: leggi l'errore. Redsys refund: the merchant code or the TEST secret key is not configured. (o LIVE) indica che manca la chiave dell'ambiente del pagamento. I codici di errore Redsys sono spiegati nel messaggio, per esempio SIS0057 (l'importo supera quanto resta del pagamento), SIS0056 (il pagamento originale non è stato trovato, altro ambiente o terminale), SIS0042 (errore di firma, verifica la chiave di questo ambiente), SIS0026 (codice esercente o terminale sconosciuto) e SIS0027 (valuta non configurata per il terminale). Se Redsys non è raggiungibile, il rimborso non viene effettuato. Riprova più tardi.
Il tuo terminale accetta una valuta che non è nell'elenco: gli sviluppatori possono modificare l'elenco delle valute con il filtro rdsg_currency_codes. Aggiungi una valuta solo se la tua banca l'ha abilitata per il terminale.
Dopo l'aggiornamento dalla versione 1.0: la chiave che usavi in modalità di prova ora si trova in Secret Key (SHA-256) — test. Inserisci la chiave live prima di deselezionare Test Mode. Gli ordini creati con la versione 1.0 continuano a ricevere notifiche e rimborsi.
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 e i log del plugin vengono rimossi solo se Delete Data era attivo; altrimenti restano disponibili per una reinstallazione futura. I dati Redsys memorizzati sugli ordini vengono sempre conservati, perché documentano i pagamenti e sono necessari per i rimborsi. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.
Redsys è un marchio dei rispettivi proprietari. Questo plugin non è affiliato né approvato da Redsys.