VibeFox Worldline for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

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

PHP: 8.0 o successivo.

Account Worldline: un account commerciante Worldline Direct (in precedenza Ingenico Direct). Gli account di test e live sono separati e hanno credenziali diverse. Per ciascun account ti servono il Merchant ID (il tuo PSPID), un API Key ID con la sua Secret API Key e una chiave webhook con il suo secret. Tutti questi elementi vengono creati nel Merchant Portal di Worldline (vedi «Configuration»).

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

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina dei plugin.

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

5. Inserisci le credenziali di test, salva le impostazioni e fai clic su Test credentials.

6. Aggiungi l'URL del webhook nel Merchant Portal dell'account di test e inserisci la chiave e il secret del webhook (vedi «Configuration»).

7. Attiva Enable/Disable ed effettua un pagamento di prova. Poi inserisci le credenziali live, ripeti la configurazione del webhook nel tuo account live, fai clic su Live credentials e deseleziona Test Mode.

Configuration

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Worldline (Ingenico). Nell'elenco dei metodi di pagamento, Worldline è segnalato come da configurare finché la modalità corrente non ha un Merchant ID, un API Key ID e una Secret API Key. Nella pagina delle impostazioni, i campi delle credenziali della modalità non in uso sono attenuati.

General

Enable/Disable: Enable Worldline Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede al checkout. Predefinito: Worldline.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Worldline.

Worldline Direct API

Ottieni le credenziali nel Merchant Portal di Worldline, sia dell'account di test sia di quello live. Il tuo PSPID corrisponde al Merchant ID. Developer > Payment API crea l'API Key ID e la Secret API Key, mentre Developer > Webhooks crea la chiave e il secret del webhook. La sezione contiene i collegamenti a entrambi i portali e alla documentazione di Worldline.

Test Mode: Enable test mode (pre-production environment, no real money) cambia sia l'endpoint dell'API sia le credenziali. La modalità test usa l'ambiente di pre-produzione e le credenziali di test, la modalità live l'ambiente di produzione e le credenziali live. Predefinito: attivato. Deseleziona l'opzione per accettare pagamenti reali. Finché la modalità test è attiva, i clienti vedono Test mode — no real money is charged. sotto il metodo di pagamento.

Account di test (pre-produzione)

Test Merchant ID (PSPID): il PSPID del tuo account di test.

Test API Key ID: l'API Key ID creato in Developer > Payment API dell'account di test.

Test Secret API Key: la Secret API Key che appartiene a quell'API Key ID.

Test Webhook Key ID: facoltativo. Se impostato, vengono accettati solo i webhook inviati con questa chiave.

Test Webhook Secret: il secret del webhook dell'account di test. Serve a verificare la firma di ogni webhook.

Account live (produzione)

Live Merchant ID (PSPID): il PSPID del tuo account live.

Live API Key ID: l'API Key ID creato in Developer > Payment API dell'account live.

Live Secret API Key: la Secret API Key che appartiene a quell'API Key ID.

Live Webhook Key ID: facoltativo. Se impostato, vengono accettati solo i webhook inviati con questa chiave.

Live Webhook Secret: il secret del webhook dell'account live.

Verifica delle credenziali

I pulsanti Test credentials e Live credentials verificano le credenziali salvate di ciascun account con una chiamata di prova a Worldline. Salva prima le modifiche. La risposta compare accanto ai pulsanti, per esempio Test credentials: connection successful., API credentials are not configured. oppure l'errore restituito da Worldline.

Webhooks

Il webhook informa il tuo negozio dei pagamenti anche quando il cliente non torna nel negozio, per esempio dopo aver chiuso il browser o quando un pagamento viene confermato più tardi. Nel Merchant Portal apri Developer > Webhooks dell'account di test e aggiungi l'URL dell'endpoint mostrato in questa sezione delle impostazioni. Ha questo aspetto: https://your-site/wc-api/wlg_worldline_webhook/. Copia l'URL esattamente come lo mostrano le impostazioni: deve rispondere senza reindirizzamenti, quindi controlla i prefissi di lingua e i reindirizzamenti forzati a www o https. Poi inserisci l'ID e il secret della chiave webhook in Test Webhook Key ID e Test Webhook Secret. Fai lo stesso nell'account live con i campi live.

Il plugin risponde automaticamente alla richiesta di verifica dell'endpoint di Worldline. Gestisce gli eventi di pagamento (cambi di stato del pagamento) e gli eventi di rimborso (cambi di stato del rimborso). Gli altri eventi vengono accettati e ignorati. I webhook senza una firma valida vengono rifiutati. Un webhook viene ignorato anche quando proviene da un Merchant ID diverso da quello dell'account il cui secret ha firmato il webhook. Senza il webhook, un ordine viene confermato solo quando il cliente torna nel negozio dopo aver pagato.

Pagina di pagamento e ordini

Payment page template: nome facoltativo di un modello (variante) della pagina di pagamento ospitata caricato nel Merchant Portal, per esempio SimplifiedCustomPaymentPage. Lascialo vuoto per usare la pagina di pagamento predefinita di Worldline.

Order Status After Payment: lo stato dell'ordine una volta che Worldline conferma il pagamento catturato. Lo stato viene applicato subito, senza un secondo cambio di stato. I pagamenti vengono sempre richiesti come vendita diretta (autorizzazione e cattura).

Logging: Enable debug logging scrive tutte le richieste API e i webhook in WooCommerce > Status > Logs, origine wcp_worldline_gateway. Errori e avvisi vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, dati della carta e dati personali vengono mascherati. Predefinito: disattivato.

Delete Data: Delete the plugin settings and logs when the plugin is deleted. La disattivazione del plugin non cancella mai nulla. I dati di pagamento salvati negli ordini vengono conservati, perché servono per i rimborsi. Predefinito: disattivato.

Quando aggiorni dalla versione 1.0, il vecchio set unico di credenziali viene spostato nei campi di test o live, a seconda della modalità che usava il negozio.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Worldline) e invia l'ordine. Il plugin crea un checkout ospitato di Worldline per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina di pagamento di Worldline. Lì il cliente paga con carta, con un wallet o con un altro metodo di pagamento attivato nel tuo account Worldline. Nome di fatturazione, indirizzo, e-mail e telefono vengono trasmessi a Worldline, e la pagina di pagamento si apre nella lingua del tuo negozio quando Worldline la supporta. Ogni tentativo di pagamento riceve un proprio riferimento, composto dall'ID dell'ordine e da una parte casuale.

Dopo il pagamento, il cliente torna nel tuo negozio. Il plugin verifica il ritorno rispetto al tentativo salvato e legge lo stato del pagamento da Worldline lato server. L'ordine viene segnato come pagato solo dopo la conferma di Worldline: con questa verifica dello stato o con un webhook firmato. Poi il cliente vede la pagina di ordine ricevuto.

Se il pagamento non è stato completato, il cliente viene portato alla pagina Pay for order con un messaggio:

Un cliente può pagare di nuovo un ordine non pagato dalla pagina Pay for order. Se nel frattempo il tentativo precedente è stato pagato, il cliente va direttamente alla pagina di ordine ricevuto e non viene addebitato due volte. Se la pagina di pagamento precedente è ancora aperta per lo stesso importo e la stessa modalità ed è stata creata meno di 30 minuti fa, il cliente viene rimandato lì.

Se Worldline non riesce ad avviare il pagamento, il cliente vede Payment error: Could not create checkout session. Please try again. e può scegliere un altro metodo di pagamento. Il motivo viene aggiunto alle note dell'ordine e al log. Se mancano le credenziali della modalità corrente, il cliente vede This payment method is not available at the moment. Please choose another payment method.

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 come vendita diretta sulla pagina di Worldline. Non prevede carte salvate né tokenizzazione, abbonamenti, modulo di carta integrato, modalità solo autorizzazione con cattura o annullamento da WooCommerce, maggiorazioni né registrazione automatica dei webhook.

Ordini e rimborsi

Order statuses

Pending payment: il cliente è stato inviato a Worldline e non ha ancora pagato, oppure Worldline non ha ancora confermato il pagamento. Una nota mostra l'ID del checkout ospitato, il riferimento e la modalità (test o live).

Processing or Completed: il pagamento è stato catturato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra l'importo, l'ID del pagamento Worldline e come è stato confermato (webhook firmato o verifica dello stato). L'ID transazione dell'ordine è l'ID del pagamento Worldline.

On hold, waiting for capture: Worldline segnala il pagamento come autorizzato o la cattura come richiesta, ma non ancora catturata. La nota dell'ordine lo spiega. L'ordine viene segnato come pagato automaticamente quando il webhook conferma la cattura. Se la nota dice che il pagamento non è catturato, catturalo nel Merchant Portal di Worldline.

On hold, held for manual review: il pagamento non corrisponde all'ordine, per esempio importo o valuta sono diversi (l'ordine è stato modificato dopo l'avvio del pagamento) oppure il pagamento appartiene a un altro tentativo. La nota mostra l'importo pagato, il totale dell'ordine e il riferimento. Controlla l'ordine e completalo oppure rimborsa il pagamento.

Failed: Worldline ha rifiutato o annullato il pagamento dell'ultimo tentativo, oppure il cliente non era idoneo al metodo di pagamento selezionato.

Cancelled: l'ordine è stato annullato da te o dal timeout di blocco dello stock di WooCommerce. Se arriva un pagamento per un ordine annullato o rimborsato, l'ordine non viene riaperto. Una nota ti chiede di rimborsare o annullare il pagamento nel Merchant Portal di Worldline oppure di ripristinare l'ordine manualmente. Il cliente che torna vede Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment.

Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato di nuovo. Una nota ti chiede di rimborsare il secondo pagamento nel Merchant Portal di Worldline.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Worldline (Ingenico). Sono supportati rimborsi totali e parziali. Il pagamento deve essere catturato. Il rimborso viene sempre inviato all'ambiente del pagamento originale (test o live) con le credenziali di quell'account, quindi devono essere configurate. Un rimborso ritentato dopo un timeout non viene eseguito due volte. Se Worldline rifiuta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso accettato viene aggiunto alle note dell'ordine con l'ID e lo stato del rimborso Worldline.

Gli aggiornamenti di stato dei rimborsi arrivano da Worldline tramite webhook e vengono aggiunti alle note dell'ordine. I rimborsi effettuati nel Merchant Portal non vengono registrati automaticamente come rimborsi di WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza usare Refund via Worldline (Ingenico).

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 > Worldline (Ingenico). Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui la licenza è attiva, e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il collegamento 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, Worldline 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 connessi vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina dei plugin e sulle pagine di WooCommerce compare un promemoria. 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 per aggiornamenti e assistenza serve il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Worldline non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia un Merchant ID, un API Key ID e una Secret API Key: i campi di test in modalità test, i campi live in modalità live. Se mancano, l'elenco dei pagamenti segnala il metodo come da configurare.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: il webhook non funziona. Nel Merchant Portal dell'account che usi (test o live) verifica che l'endpoint esista e che il suo URL sia esattamente quello mostrato nelle impostazioni, senza reindirizzamenti. Controlla che il secret del webhook di quell'account sia nel campo corrispondente (Test Webhook Secret o Live Webhook Secret) e che Webhook Key ID sia vuoto oppure corrisponda alla chiave. L'ordine viene confermato anche quando il cliente torna nel negozio dopo aver pagato.

Il webhook risponde Webhook secret not configured: nessun secret del webhook è impostato. Inserisci il secret del webhook nelle impostazioni. Worldline ripete il webhook.

Il webhook risponde Invalid signature: il secret del webhook appartiene a un altro account o a un'altra chiave, oppure Webhook Key ID non corrisponde alla chiave che ha inviato il webhook.

Il webhook risponde Missing signature, Empty body o Invalid JSON: la richiesta non è arrivata da Worldline nella forma prevista, oppure un proxy o un reindirizzamento l'ha modificata. Verifica che l'URL risponda senza reindirizzamenti.

Il webhook risponde Ignored: il webhook proviene da un Merchant ID diverso da quello indicato nelle impostazioni di quella modalità. Controlla Test Merchant ID (PSPID) o Live Merchant ID (PSPID).

Il webhook risponde Retry later: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Worldline ripete il webhook.

Test credentials o Live credentials mostra un errore: salva prima le impostazioni, poi verifica che Merchant ID, API Key ID e Secret API Key provengano dallo stesso account e che i valori di test siano nei campi di test e quelli live nei campi live.

Il cliente vede un errore quando effettua l'ordine: apri le note dell'ordine oppure WooCommerce > Status > Logs, origine wcp_worldline_gateway. Gli errori vengono registrati anche con il debug logging disattivato. Per i dettagli completi delle richieste, attiva Logging e riprova.

I pagamenti di test non confermano un ordine live: test e live sono separati. Un webhook firmato con il secret di test non conferma mai un tentativo di pagamento live, e viceversa. Imposta Test Mode sulla modalità che vuoi usare e utilizza le credenziali e il webhook di quell'account.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. O Worldline non ha ancora confermato la cattura (il webhook completa l'ordine), oppure l'importo o la valuta pagati non corrispondevano all'ordine.

Il rimborso non riesce con un messaggio sull'ambiente: il pagamento è stato effettuato nell'ambiente di test o live, e le credenziali di quell'ambiente non sono impostate. Inseriscile e riprova.

Sviluppatori: il filtro wlg_hosted_checkout_data modifica la richiesta del checkout ospitato, per esempio per limitare i metodi di pagamento mostrati, e wlg_gateway_icon cambia l'icona del metodo di pagamento.

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

La disattivazione del plugin mantiene 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 vengono rimossi solo se Delete Data era attivo. Altrimenti restano per un'eventuale reinstallazione successiva. I dati di pagamento Worldline salvati negli ordini vengono sempre conservati, perché servono per i rimborsi. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

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