VibeFox Przelewy24 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: il carrello deve essere in PLN, EUR, GBP o CZK. Con altre valute il metodo di pagamento è nascosto nel checkout. Il carrello viene addebitato nella sua valuta; il modulo non converte le valute.

Account Przelewy24: ti serve un account commerciante Przelewy24 e i suoi dati API: il Merchant ID, la chiave API (chiamata report key nel pannello Przelewy24), la chiave CRC e, se il tuo negozio ha un proprio ID, il POS ID (Shop ID). Li trovi nel pannello commerciante di Przelewy24 su panel.przelewy24.pl, in My data > API data and configuration. Le chiavi sandbox provengono da un account sandbox separato, su sandbox.przelewy24.pl/panel. Non c'è altro da configurare nel pannello Przelewy24: il modulo invia il proprio URL di notifica con ogni pagamento. Il tuo negozio deve essere raggiungibile da Internet, perché Przelewy24 gli invia le notifiche di pagamento.

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 Przelewy24 Payment più tardi nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la chiave di licenza VibeFox in License key nel blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci le chiavi sandbox (Merchant ID, chiave API, chiave CRC; il POS ID solo se diverso dal Merchant ID), attiva Enable/Disable, fai clic su Save ed effettua un pagamento di prova in modalità sandbox.

5. Inserisci le chiavi live, disattiva Test Mode e fai clic su Save per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine Przelewy24 payment on hold. PrestaShop propone quindi un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Przelewy24 Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina mostra avvisi quando manca qualcosa. Mentre la sandbox è attiva: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. Quando le chiavi della modalità corrente sono incomplete: Enter the Sandbox Merchant ID, API key and CRC key - until then Przelewy24 is not shown at checkout. (o lo stesso per le chiavi Live). Se Przelewy24 non accetta la valuta predefinita del tuo negozio, l'avviso indica la valuta e quelle supportate. Dopo il salvataggio, gli avvisi seguono subito la nuova modalità e le nuove chiavi. Spazi e interruzioni di riga copiati insieme alle chiavi dal pannello Przelewy24 vengono rimossi al salvataggio.

Przelewy24

Enable/Disable: Enable Przelewy24 Payment attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Przelewy24. Obbligatorio: salvando con il titolo vuoto compare Enter a title for the payment method.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with BLIK, online bank transfer or card via Przelewy24.

Credenziali API

La sezione spiega dove trovare le chiavi (My data > API data and configuration nel pannello commerciante di Przelewy24) e rimanda a panel.przelewy24.pl e sandbox.przelewy24.pl/panel.

Test Mode: usa la sandbox di Przelewy24 (sandbox.przelewy24.pl) e le chiavi Sandbox. Non viene addebitato denaro reale. Disattivalo per accettare pagamenti reali su secure.przelewy24.pl con le chiavi Live. Predefinito: attivo. Finché è attivo, i clienti vedono Sandbox mode - no real money is charged sotto il metodo di pagamento.

Chiavi Live

Live Merchant ID: il tuo ID commerciante Przelewy24, solo numeri.

Live POS ID (optional): lo Shop ID (posId). Lascialo vuoto se è uguale al Merchant ID.

Live API key (report key): la chiave API dal pannello Przelewy24. Serve per l'autenticazione API.

Live CRC key: serve per firmare le richieste a Przelewy24 e per verificare la firma delle notifiche di Przelewy24.

Chiavi Sandbox

Sandbox Merchant ID: il Merchant ID del tuo account sandbox Przelewy24.

Sandbox POS ID (optional): lo Shop ID (posId) dell'account sandbox. Lascialo vuoto se è uguale al Merchant ID.

Sandbox API key (report key): la chiave API dell'account sandbox.

Sandbox CRC key: la chiave CRC dell'account sandbox, usata per firmare le richieste e verificare le notifiche sandbox.

Le chiavi API e CRC salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved - leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

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

Le chiavi Live e quelle sandbox sono diverse. Il Merchant ID e il POS ID devono contenere solo cifre; finché non vengono inseriti il Merchant ID, la chiave API e la chiave CRC della modalità corrente, il metodo di pagamento non viene mostrato al checkout. Un pagamento avviato in una modalità viene sempre verificato e rimborsato con le chiavi di quella modalità, anche dopo il cambio: conserva quindi le chiavi della vecchia modalità finché i suoi pagamenti sono aperti o possono essere rimborsati.

Notifiche di pagamento

Notification URL: l'indirizzo che riceve le notifiche di pagamento da Przelewy24. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_przelewy24_payment/notify, eventualmente con un codice lingua come /en/. Il modulo invia questo URL a Przelewy24 con ogni pagamento e ogni rimborso, quindi nel pannello Przelewy24 non c'è nulla da configurare. L'URL deve essere raggiungibile da Internet: non devono esserci firewall né autenticazione HTTP davanti. Continua a funzionare mentre il negozio è in manutenzione e non è bloccato dalla restrizione per paese del tuo negozio. Senza notifiche, il pagamento viene comunque confermato quando il cliente torna al negozio (vedi Checkout); se il cliente non torna, non viene creato alcun ordine.

Avanzate

Debug Log: scrive eventi tecnici (numeri di carrello, ID transazione P24, errori) in logs/wc_p24_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi, come notifiche rifiutate o una verifica o un rimborso non riusciti, vengono sempre registrati; attiva l'interruttore per registrare anche ogni passaggio. Chiavi, corpi delle richieste e dati personali non vengono mai registrati. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le sue impostazioni e il registro. Gli ordini e i loro dati di pagamento Przelewy24 non vengono mai eliminati. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Przelewy24, con il logo P24) e conferma l'ordine. Il modulo registra una transazione Przelewy24 per il totale del carrello nella valuta del carrello, con l'e-mail, il nome e il paese di fatturazione del cliente, e la descrizione Cart # con il numero del carrello e il nome del tuo negozio. Ogni tentativo di pagamento riceve un proprio ID di sessione. Il cliente viene reindirizzato alla pagina di pagamento di Przelewy24 e paga con BLIK, bonifico bancario online, carta o un altro metodo attivato per il tuo account Przelewy24. La pagina di pagamento viene mostrata nella lingua del carrello del cliente, se Przelewy24 la supporta, altrimenti in inglese. A questo punto non esiste ancora alcun ordine.

L'ordine viene segnato come pagato solo dopo la conferma di Przelewy24. Przelewy24 invia al tuo negozio una notifica firmata. Il modulo verifica la firma con la chiave CRC, il Merchant ID e il POS ID; che la sessione sia stata registrata per questo carrello e nella stessa modalità; e che importo e valuta corrispondano al tentativo di pagamento e al totale attuale del carrello. Solo allora verifica la transazione con Przelewy24 (Przelewy24 accredita solo i pagamenti verificati) e crea l'ordine in Payment accepted. I webhook senza firma valida vengono rifiutati.

Dopo il pagamento il cliente torna al tuo negozio. Se la notifica non è ancora arrivata, il modulo chiede a Przelewy24 lo stato della transazione con una richiesta server-to-server autenticata (al massimo una volta ogni 10 secondi per carrello) e applica gli stessi controlli. La sola pagina di ritorno non segna mai un ordine come pagato. Quando il pagamento è confermato, il cliente vede la pagina standard di conferma dell'ordine. Finché non è confermato, una pagina Payment confirmation mostra We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: con un pulsante Check again e un pulsante Pay again che apre il checkout. Il carrello viene conservato, e un pagamento effettuato più tardi su una vecchia pagina Przelewy24 dello stesso carrello viene comunque accettato. Se l'ordine è in sospeso, la pagina di conferma mostra Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Se il pagamento non può essere avviato, il cliente resta al checkout con un breve messaggio: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (il motivo va nel registro), Payment gateway is not configured properly. Please contact the administrator. (chiavi della modalità corrente mancanti), un messaggio che indica che Przelewy24 non può accettare pagamenti nella valuta del carrello, oppure The order total must be greater than zero. Un carrello che ha già un ordine non viene inviato di nuovo a Przelewy24; il cliente va alla conferma dell'ordine.

Il modulo non prevede carte salvate o pagamenti con un clic, abbonamenti o pagamenti ricorrenti, non consente la scelta del metodo di pagamento P24 (ad esempio un campo per il codice BLIK) al checkout, non include widget di pagamento rateale e non invia il contenuto del carrello a Przelewy24.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato reindirizzato a Przelewy24 e non ha pagato, oppure il pagamento non è ancora confermato. Esiste solo il carrello.

Payment accepted: il pagamento è stato verificato. Viene registrato con l'ID ordine P24 come ID transazione, e una nota mostra l'ID ordine P24, l'importo e la modalità. Ogni pagamento viene applicato una sola volta.

Przelewy24 payment on hold: l'importo o la valuta comunicati da Przelewy24 differiscono dal carrello (ad esempio il carrello è stato modificato dopo l'avvio del pagamento); il pagamento non è stato confermato e la nota lo indica. Oppure il pagamento è arrivato ed è stato verificato per un ordine che era stato annullato; l'ordine non viene riaperto in silenzio, la nota ti chiede di spedirlo o di rimborsare il pagamento. Controlla il pagamento nel pannello Przelewy24. Se in seguito arriva un pagamento corretto di un altro tentativo per un ordine in sospeso dopo una discrepanza, l'ordine passa a Payment accepted.

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

Se arriva un secondo pagamento per un carrello il cui ordine è già pagato o rimborsato (un vecchio link di pagamento, due schede del browser), non viene confermato, quindi Przelewy24 non lo accredita. Una nota sull'ordine ti chiede di verificarlo nel pannello Przelewy24 e di restituirlo al cliente, se necessario.

Blocco pagamento Przelewy24

La pagina dell'ordine mostra un blocco Przelewy24 payment con l'ID ordine P24, la sessione, l'ambiente (un badge Sandbox per i pagamenti sandbox), lo stato del pagamento e come è stato verificato (notifica o ritorno), gli importi pagati e rimborsati, il modulo di rimborso, la cronologia dei rimborsi e le Payment notes dell'ordine.

Rimborsi

Nel blocco Przelewy24 payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Przelewy24. Conferma la domanda Refund this amount through Przelewy24? This cannot be undone. Sono supportati rimborsi totali e parziali, fino all'importo non ancora rimborsato. Ti serve il permesso di modificare gli ordini; l'accesso alle pagine dei moduli non è necessario. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento (sandbox o live), quindi devono essere impostate le chiavi di quella modalità. I rimborsi sono disponibili dopo che Przelewy24 ha verificato il pagamento.

Przelewy24 elabora i rimborsi in modo asincrono. Il blocco mostra Refund of … requested at Przelewy24. The result will be added as an order note., la cronologia dei rimborsi mostra lo stato requested e viene aggiunta una nota. Il risultato arriva più tardi all'URL di notifica: lo stato diventa completed con la nota Przelewy24: refund of … completed., oppure rejected con una nota che indica che il denaro non è stato restituito al cliente. Un rimborso totale imposta l'ordine su Refunded al momento della richiesta; un rimborso parziale non cambia lo stato. Se un rimborso viene rifiutato, controllalo nel pannello Przelewy24; lo stato dell'ordine non viene ripristinato automaticamente.

Se Przelewy24 non accetta la richiesta di rimborso, il blocco mostra Przelewy24 refund failed: con il motivo, e non viene registrato alcun rimborso. Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Przelewy24, e i rimborsi effettuati direttamente nel pannello Przelewy24 non vengono aggiunti all'ordine.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Przelewy24 Payment è il primo blocco di Modules > Module Manager > VibeFox Przelewy24 Payment > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad 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-przelewy24 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, ad 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 un posto 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: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Przelewy24 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 verificati e confermati, e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il 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. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Przelewy24 non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che il Merchant ID, la chiave API e la chiave CRC della modalità corrente siano inseriti (le chiavi Sandbox finché Test Mode è attivo, altrimenti le chiavi Live; Merchant ID e POS ID solo cifre) e che la valuta del carrello sia PLN, EUR, GBP o CZK. Gli avvisi in cima alle impostazioni indicano il problema. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente. Gli sviluppatori possono modificare l'elenco delle valute con l'hook actionWcpPrzelewy24SupportedCurrencies (solo valute con due decimali abilitate per il tuo account Przelewy24).

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: la notifica di Przelewy24 non è arrivata al tuo negozio e il cliente non è tornato al negozio. Verifica che il Notification URL sia raggiungibile da Internet (nessun firewall né autenticazione HTTP davanti) e che Merchant ID, POS ID e chiave CRC della modalità del pagamento siano corretti. Le notifiche rifiutate vengono scritte nel registro anche con Debug Log disattivato; guarda il campo Log nella pagina del modulo.

Come il negozio risponde alle notifiche: una notifica elaborata, ripetuta o sconosciuta riceve una risposta HTTP 200. Altrimenti Przelewy24 la rinvia più tardi: 400 (dati mancanti o malformati), 401 Invalid signature (chiave CRC errata, altro Merchant ID o POS ID), 401 Invalid signature for this payment (notifica firmata con le chiavi dell'altra modalità rispetto al pagamento), 405 (non è una richiesta POST), 500 Verification failed (la verifica con Przelewy24 non è riuscita; una nota viene aggiunta all'ordine una sola volta, se esiste), 500 Order could not be created (ad esempio il modulo è disattivato; la notifica successiva crea l'ordine senza una nuova verifica) e 503 Busy, retry later (il carrello era in fase di conferma da un'altra richiesta nello stesso momento).

Il cliente vede Payment error: Przelewy24 could not start the payment: Przelewy24 ha rifiutato la transazione, di solito per chiavi errate della modalità corrente (le chiavi sandbox funzionano solo in modalità sandbox, le chiavi live solo in modalità live). L'errore di Przelewy24 è nel registro.

L'ordine è in Przelewy24 payment on hold dopo il pagamento: leggi le note nel blocco Przelewy24 payment. L'importo o la valuta differivano dal carrello, oppure il pagamento è arrivato per un ordine che era stato annullato. Controlla il pagamento nel pannello Przelewy24, poi elabora l'ordine o rimborsa il pagamento.

Un rimborso non riesce: This order has no verified Przelewy24 payment. Cannot process refund. significa che l'ordine non è stato pagato con un pagamento Przelewy24 verificato. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (o lo stesso per Live) significa che le chiavi della modalità del pagamento sono state rimosse; inseriscile di nuovo. Invalid refund amount significa che l'importo è vuoto, non è un numero o è superiore all'importo non ancora rimborsato.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Przelewy24 Payment e scegli Uninstall. La chiave di licenza e lo stato di licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati di pagamento Przelewy24 degli ordini (sessioni, ID ordine P24, rimborsi) e lo stato dell'ordine Przelewy24 payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID transazione.

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