VibeFox Redsys for PrestaShop — Guida

Requisiti

PrestaShop: 8.0–9.x.

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

Conto esercente Redsys: la tua banca (l'acquirer che ti ha fornito il POS virtuale di Redsys) ti fornisce il codice esercente (FUC), il numero del terminale e l'accesso al pannello di amministrazione di Redsys, dove viene mostrata la chiave segreta SHA-256 di ogni ambiente. La chiave dell'ambiente di prova è diversa da quella reale. La notifica online (HTTP) deve essere attiva per il tuo terminale. Se non sei sicuro, chiedi alla tua banca.

Valuta del negozio: una delle valute supportate dal modulo (vedi Configuration), e il tuo terminale Redsys deve essere abilitato dalla banca per quella valuta. La maggior parte dei terminali accetta solo EUR.

Negozio raggiungibile: Redsys deve poter raggiungere il tuo negozio 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. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento clicca su Configure, oppure trova più tardi VibeFox Redsys Gateway nell'elenco dei moduli e clicca su Configure.

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

4. Inserisci il tuo codice esercente, il terminale e la chiave segreta di ogni ambiente (vedi Configuration).

5. Attiva Enable/Disable e clicca su Save. Prova un pagamento con Test Mode attivo, poi disattiva Test Mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine Redsys payment on hold. PrestaShop propone il nuovo modulo di pagamento per i paesi attivi in quel momento, e per tutte le valute e i gruppi di clienti. Puoi modificarlo in Payment > Preferences; i paesi che attiverai in seguito devono essere selezionati lì per il modulo.

Configuration

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Redsys Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa se il codice esercente manca o non è composto solo da cifre, se una chiave segreta non è una chiave SHA-256 Redsys valida, se la chiave della modalità attuale è vuota (in tal caso il metodo di pagamento viene nascosto al checkout) e se la valuta del negozio non è supportata. Mentre la modalità di prova è attiva, mostra Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. Se Title è vuoto, la pagina mostra Enter a title for the payment method. e non salva nulla.

Redsys

Enable/Disable: Enable Redsys Gateway 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: Credit/Debit Card (Redsys). Obbligatorio.

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 di Redsys, dove viene mostrata la chiave segreta SHA-256 di ogni ambiente. La sezione contiene un collegamento al pannello di amministrazione di 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), di solito di 32 caratteri. 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 di prova pubblici 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: pagamenti e rimborsi vanno all'ambiente di prova di Redsys (SIS-T) e vengono firmati con la chiave di prova. Predefinito: attivo. Disattivalo 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.

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 secrets: seleziona una chiave e clicca su Save per eliminarla. Un campo vuoto mantiene il valore salvato.

Pagina di pagamento e ordini

Commerce Name: il nome del negozio mostrato nella pagina di pagamento Redsys, al massimo 25 caratteri. Predefinito: il nome del tuo negozio, troncato a 25 caratteri.

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito.

Le mancate corrispondenze di importo o valuta, i pagamenti di prova mentre il negozio è in modalità reale e i pagamenti di tentativi annullati finiscono sempre in Redsys payment on hold.

Notifiche di pagamento

Notification URL: Redsys comunica ogni pagamento a questo indirizzo del tuo negozio. È mostrato in questa sezione e ha l'aspetto di https://your-shop/module/wcp_redsys_gateway/notify con URL parlanti. Il modulo 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 non viene creato alcun ordine dopo un pagamento riuscito. Le notifiche senza firma valida vengono rifiutate. Senza la notifica non viene creato alcun ordine.

Avanzate

Debug log: scrive i dettagli di pagamenti, notifiche e rimborsi in logs/rdsg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, firme e dati di carta non vengono mai registrati. Predefinito: disattivato.

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

Delete Data: se attiva, la disinstallazione del modulo rimuove le impostazioni del gateway e il log. I record dei pagamenti Redsys degli ordini (necessari per i rimborsi) e lo stato dell'ordine Redsys payment on hold vengono sempre conservati. 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 i carrelli in altre valute.

Checkout

Al momento del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card (Redsys)) e conferma l'ordine. Il cliente vede Redirecting to Redsys for payment. Please wait... e prosegue alla pagina di pagamento Redsys della tua banca. Se il browser non prosegue da solo, il cliente clicca su Pay via Redsys, oppure su Choose another payment method per tornare indietro. A questo punto l'ordine non esiste ancora.

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 carrello (spagnolo, inglese, catalano, francese, tedesco, italiano, portoghese e altre) o l'inglese per le altre lingue. L'importo è il totale del carrello nella valuta minore del carrello, per esempio EUR 43,45 diventa 4345, e JPY o CLP senza decimali. Il pagamento viene descritto come Cart con il numero del carrello e il nome del tuo negozio.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo che Redsys lo conferma con la notifica firmata: è la notifica a creare l'ordine, e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Redsys has been received. Se l'ordine è passato a Redsys payment on hold, la pagina mostra Your payment with Redsys has been received and is being reviewed by the store. Se la notifica non è ancora arrivata, una pagina Payment confirmation mostra Redsys is confirming your payment. If you completed the payment, your order will be created in a few moments — please do not pay again. con i pulsanti Check again e Back to checkout.

Se il cliente annulla o il pagamento viene rifiutato, Redsys riporta il cliente al checkout con The Redsys payment was not completed. You can try again or choose another payment method. Il carrello viene conservato e il cliente può pagare di nuovo. Ogni nuovo tentativo riceve un nuovo numero d'ordine Redsys, e un pagamento effettuato da uno di essi, per esempio da una seconda scheda del browser, viene comunque riconosciuto.

Se il pagamento non può essere inviato a Redsys, il cliente resta al checkout con un breve messaggio: Redsys payments are not configured correctly. Please choose another payment method or contact us., un messaggio che indica che la valuta non è accettata, oppure The order total must be greater than zero.

La notifica funziona anche quando il negozio è in modalità manutenzione e non è bloccata dalla restrizione per paese del tuo negozio.

Il modulo accetta pagamenti singoli, autorizzati e acquisiti subito sulla 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é link di pagamento per gli ordini creati nel back office.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Redsys e non ha pagato, il pagamento è stato rifiutato o annullato, oppure la notifica di Redsys non è ancora arrivata. Esiste solo il carrello.

Payment accepted, Delivered or Redsys payment on hold: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con il numero d'ordine Redsys (Ds_Order) come ID transazione, e una nota mostra il numero d'ordine Redsys, il codice di autorizzazione e il codice di risposta, con la dicitura [TEST] per i pagamenti di prova.

Redsys payment on hold after payment: Redsys ha comunicato un importo o una valuta diversi dal totale del carrello (per esempio, il carrello è stato modificato in un'altra scheda dopo l'avvio del pagamento), è arrivato un pagamento di prova mentre il negozio è in modalità reale (non è stato addebitato denaro reale e non viene registrato alcun pagamento), oppure il cliente ha pagato dopo aver annullato quel pagamento sulla pagina Redsys. La nota lo spiega. Verifica il pagamento nel pannello di amministrazione di Redsys, poi gestisci l'ordine o rimborsa il pagamento.

Refunded: il pagamento è stato rimborsato interamente tramite il modulo.

Un pagamento rifiutato non modifica mai un ordine esistente. Per i codici di risposta più frequenti, il log e le note indicano un motivo breve, come Insufficient funds, Card expired o Cancelled by the customer. Se arriva un secondo pagamento diverso per un carrello che ha già un ordine, l'ordine non viene modificato. Una nota ti chiede di rimborsare il pagamento duplicato nel pannello di amministrazione di Redsys. Se Redsys segnala che un pagamento è ancora in corso, viene aggiunta una nota e l'ordine attende l'esito definitivo.

Blocco pagamento Redsys

La pagina dell'ordine mostra un blocco Redsys payment con il numero d'ordine Redsys (Ds_Order), il codice e la risposta di autorizzazione, l'ambiente (reale o di prova), l'importo pagato e rimborsato, un badge Test mode per i pagamenti di prova, un suggerimento di verifica per gli ordini in attesa, lo storico dei rimborsi, le Redsys notes dell'ordine e tutti i numeri d'ordine Redsys emessi per il carrello.

Rimborsi

Nel blocco Redsys payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Redsys. Conferma la domanda Refund this amount through Redsys? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il diritto di modificare gli ordini; non serve l'accesso alle pagine dei moduli. I rimborsi vengono effettuati nell'importo e nella valuta che Redsys ha addebitato, quindi dopo una mancata corrispondenza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato tramite la REST API di Redsys all'ambiente in cui è stato effettuato il pagamento (prova o reale), firmato con la chiave di quell'ambiente, e la firma della risposta viene verificata. Se Redsys non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con il numero d'ordine Redsys e il motivo. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Redsys.

I rimborsi effettuati nel pannello di amministrazione di Redsys non vengono registrati come rimborsi del modulo. Quando Redsys invia una notifica al riguardo, viene aggiunta una nota all'ordine. Lo stato dell'ordine non cambia automaticamente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Redsys Gateway è il primo blocco nella pagina Modules > Module Manager > VibeFox Redsys Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca 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 si trovano la riga Product: presta-payment-redsys 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 aver cambiato l'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, clicca 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 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, Redsys 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. La vetrina di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento è nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo 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, e i rimborsi funzionano.

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

Redsys non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che il codice esercente e il 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à reale. Verifica che la valuta del carrello sia nell'elenco delle valute supportate. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi. 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: la notifica di Redsys non ha raggiunto il 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 Notification URL sia raggiungibile da internet senza login né blocchi del firewall. Attiva Debug log e controlla il campo Log nella pagina del modulo.

La notifica risponde Forbidden: la firma non corrisponde 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 carrello di questo negozio usa quel numero d'ordine Redsys.

La notifica risponde Busy: il carrello era in elaborazione da un'altra notifica nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Redsys ripete la notifica. Il log mostra il motivo.

La notifica risponde Bad request: la richiesta non aveva parametri Redsys o li aveva corrotti. Non proveniva da Redsys nel formato previsto.

L'ordine è Redsys payment on hold dopo il pagamento: leggi le note nel blocco Redsys payment (vedi Stati dell'ordine), poi gestisci l'ordine o rimborsa il pagamento.

I pagamenti di prova non confermano gli ordini in modalità reale: 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) significa che manca la chiave dell'ambiente del pagamento. I codici di errore Redsys sono spiegati nel messaggio, per esempio SIS0057 (l'importo supera ciò che resta del pagamento), SIS0056 (pagamento originale non 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 l'hook actionRdsgCurrencyCodes. Aggiungi una valuta solo se la tua banca l'ha abilitata per il terminale.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Redsys Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete Data è attivo, vengono rimosse le impostazioni del gateway e il log. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I record dei pagamenti e dei rimborsi Redsys e lo stato dell'ordine Redsys payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento e gli ID di transazione.

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