VibeFox Przelewy24 for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza WooCommerce.

PHP: 8.0 o successivo.

Valuta: l'ordine deve essere in PLN, EUR, GBP o CZK. Con altre valute il metodo di pagamento non viene mostrato al checkout. L'ordine viene addebitato nella sua valuta; il plugin non converte le valute.

Account Przelewy24: ti servono 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 plugin invia il proprio URL di notifica con ogni pagamento. Il tuo sito deve essere raggiungibile da Internet, perché Przelewy24 vi invia le notifiche di pagamento.

Chiave di licenza VibeFox: si acquista 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_przelewy24_payment in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Przelewy24 > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Inserisci le chiavi sandbox (Merchant ID, API key, CRC key; il POS ID solo se diverso dal Merchant ID), attiva Enable/Disable, salva e fai un pagamento di prova in modalità sandbox.

6. Inserisci le chiavi live, deseleziona Test Mode e salva per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Przelewy24. 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). Quando Przelewy24 non accetta la valuta del negozio, l'avviso indica la valuta e quelle supportate. Dopo il salvataggio, gli avvisi seguono subito la nuova modalità e le nuove chiavi. Gli spazi e gli a capo copiati insieme alle chiavi dal pannello Przelewy24 vengono rimossi al salvataggio.

Checkout

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. Predefinito: Przelewy24.

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: Enable sandbox (test) mode. Quando è attiva, i nuovi pagamenti vanno alla sandbox di Przelewy24 (sandbox.przelewy24.pl) con le chiavi sandbox, e non viene addebitato denaro reale. Deselezionala per accettare pagamenti reali su secure.przelewy24.pl con le chiavi live. Predefinito: attiva.

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, insieme al POS ID.

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 live e sandbox sono diverse. Merchant ID e POS ID devono contenere solo cifre; finché Merchant ID, API key e CRC key della modalità corrente non sono inseriti, 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 modalità precedente finché i suoi pagamenti sono ancora aperti o possono essere rimborsati.

Notifiche di pagamento

Questa sezione mostra l'URL di notifica del tuo negozio. Ha questo aspetto: https://your-site/wc-api/wc_p24_payment/. Il plugin invia questo URL a Przelewy24 con ogni pagamento, quindi nel pannello Przelewy24 non va configurato nulla. Allo stesso URL arrivano anche i risultati dei rimborsi. L'URL deve essere raggiungibile da Internet: nessun firewall, modalità manutenzione o autenticazione HTTP davanti. Senza notifiche, il pagamento viene comunque confermato quando il cliente torna alla pagina di ordine ricevuto (vedi Checkout); se il cliente non torna, l'ordine resta in «In attesa di pagamento».

Avanzate

Debug Log: Enable logging scrive eventi tecnici (numeri d'ordine, ID transazione P24, errori) in WooCommerce > Status > Logs, origine wcp_przelewy24_payment. Errori e avvisi vengono sempre registrati. Chiavi, corpi delle richieste e dati personali non vengono mai registrati. Predefinito: disattivato.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Gli ordini e i loro dati di pagamento non vengono mai eliminati. Disattivare il plugin conserva tutto. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Przelewy24, con il logo P24 nel blocco Checkout) e completa l'ordine. In modalità sandbox il blocco Checkout mostra Sandbox mode — no real money is charged. Il plugin registra una transazione Przelewy24 per il totale dell'ordine nella valuta dell'ordine, con e-mail, nome e paese di fatturazione del cliente, e aggiunge una nota all'ordine con l'ID di sessione e la modalità (sandbox o live). Ogni tentativo di pagamento riceve un proprio ID di sessione. Il cliente viene inviato 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 sito se Przelewy24 la supporta, altrimenti in inglese.

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

Dopo il pagamento il cliente torna alla pagina di ordine ricevuto. Se la notifica non è ancora arrivata, il plugin chiede a Przelewy24 lo stato della transazione con una richiesta autenticata da server a server (al massimo una volta ogni 10 secondi per ordine) e applica gli stessi controlli. La sola pagina di ritorno non segna mai un ordine come pagato. Finché il pagamento non è confermato, la pagina 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 Pay again che apre la pagina Pay for order. Se l'ordine è in sospeso, la pagina mostra Your payment is being verified. We will send you an e-mail as soon as it is confirmed. Un pagamento effettuato più tardi su una vecchia pagina Przelewy24 dello stesso ordine viene comunque accettato.

Se il pagamento non può essere avviato, il cliente vede un breve messaggio: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (il motivo viene scritto nel registro), Payment gateway is not configured properly. Please contact the administrator. (mancano le chiavi della modalità corrente), un messaggio che indica che Przelewy24 non può accettare pagamenti nella valuta dell'ordine, oppure The order total must be greater than zero. Un ordine già pagato o in sospeso non viene inviato di nuovo a Przelewy24 (This order does not need a payment any more.).

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 non prevede carte salvate o pagamenti con un clic, abbonamenti o pagamenti ricorrenti, la scelta del metodo di pagamento P24 (ad esempio un campo per il codice BLIK) nella pagina di checkout, widget di pagamento rateale, e non invia il contenuto del carrello a Przelewy24.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Przelewy24 e non ha ancora pagato, oppure il pagamento non è ancora confermato.

Processing or Completed: il pagamento è stato verificato. WooCommerce imposta «In lavorazione», oppure «Completato» per gli ordini con solo prodotti virtuali scaricabili. La nota dell'ordine mostra l'ID ordine P24, l'importo e la modalità. L'ID transazione dell'ordine è l'ID ordine P24. Ogni pagamento viene applicato una sola volta.

On hold: l'importo o la valuta comunicati da Przelewy24 non corrispondono all'ordine (ad esempio, il totale dell'ordine è 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 annullato; l'ordine non viene riaperto in silenzio, e la nota ti chiede di spedirlo o di rimborsare il pagamento. Controlla il pagamento nel pannello Przelewy24.

Se arriva un secondo pagamento per un 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, se necessario, di restituirlo all'acquirente.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Przelewy24. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato nella modalità in cui è stato effettuato il pagamento (sandbox o live), quindi devono essere presenti le chiavi di quella modalità. Przelewy24 elabora i rimborsi in modo asincrono: la nota dell'ordine indica prima che il rimborso è stato richiesto, e il risultato arriva in seguito all'URL di notifica e viene aggiunto come nota: Przelewy24: refund of … completed. oppure una nota che indica che il rimborso è stato rifiutato e il denaro non è stato restituito. Se un rimborso viene rifiutato, controllalo nel pannello Przelewy24; il rimborso WooCommerce già registrato sull'ordine non viene rimosso automaticamente.

Se Przelewy24 non accetta la richiesta di rimborso, WooCommerce mostra Przelewy24 refund failed: con il motivo, e non viene registrato alcun rimborso. I rimborsi effettuati direttamente nel pannello Przelewy24 non vengono aggiunti all'ordine.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Przelewy24. 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. Libera lo slot 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. I gestori del negozio con accesso effettuato 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 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

Przelewy24 non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che Merchant ID, API key e CRC key della modalità corrente siano inseriti (le chiavi sandbox mentre Test Mode è attivo, altrimenti le chiavi live; Merchant ID e POS ID solo cifre) e che la valuta dell'ordine sia PLN, EUR, GBP o CZK. Gli avvisi in cima alle impostazioni indicano il problema. Gli sviluppatori possono modificare l'elenco delle valute con il filtro wc_p24_supported_currencies (solo valute con due decimali attive per il tuo account Przelewy24).

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: la notifica di Przelewy24 non è arrivata al tuo negozio e il cliente non è tornato alla pagina di ordine ricevuto. Verifica che l'URL mostrato in Payment notifications sia raggiungibile da Internet (nessuna modalità manutenzione, firewall o autenticazione HTTP davanti a /wc-api/wc_p24_payment/) e che Merchant ID, POS ID e CRC key della modalità del pagamento siano corretti. Le notifiche rifiutate vengono registrate in WooCommerce > Status > Logs, origine wcp_przelewy24_payment, anche con Debug Log disattivato.

Come il negozio risponde alle notifiche: una notifica elaborata, ripetuta o sconosciuta riceve una risposta HTTP 200. Altrimenti Przelewy24 la invia di nuovo più tardi: 400 (dati mancanti o malformati), 401 Invalid signature (chiave CRC errata, altro Merchant ID o POS ID, oppure una 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) e 503 Busy, retry later (l'ordine era in aggiornamento 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 è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta non corrispondevano all'ordine, oppure il pagamento è arrivato per un ordine 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 tramite un pagamento Przelewy24 verificato. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (o lo stesso per le chiavi live) significa che sono state rimosse le chiavi della modalità del pagamento; inseriscile di nuovo.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Ad 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, così come i marcatori temporanei della pagina di ritorno, vengono sempre rimossi. Le impostazioni del plugin e i suoi registri (file di log, inclusi quelli ruotati, e le voci di log nel database dell'origine wcp_przelewy24_payment) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una futura reinstallazione. Gli ordini esistenti conservano le loro note di pagamento, gli ID transazione e i dati di pagamento Przelewy24.

Przelewy24 è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Przelewy24 né approvato da Przelewy24.