VibeFox Worldline 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.

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 servono il Merchant ID (il tuo PSPID), un API Key ID con la relativa Secret API Key e una chiave webhook con il relativo secret. Tutti vengono creati nel Merchant Portal di Worldline (vedi Configurazione).

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

3. Incolla 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 credenziali di test, fai clic su Save e poi su Test credentials.

5. Aggiungi l'URL del webhook nel Merchant Portal dell'account di test e inserisci la chiave e il secret del webhook (vedi Configurazione).

6. 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 disattiva Test Mode.

All'installazione il modulo crea due stati dell'ordine: Awaiting Worldline capture e Worldline payment on hold. PrestaShop attiva un nuovo modulo di pagamento per i paesi attivi in quel momento. Controlla valute, paesi e gruppi di clienti in Payment > Preferences e seleziona lì i paesi che aggiungerai più avanti.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Worldline Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa se le credenziali della modalità corrente (Merchant ID, API Key ID, Secret API Key) sono incomplete, perché in quel caso il metodo di pagamento viene nascosto al checkout. Finché la modalità test è attiva, la pagina mostra Test mode is on (pre-production environment): no real money is charged.

Worldline (Ingenico)

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. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Worldline. Obbligatorio.

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 dell'account di test e di quello live. Il tuo PSPID è il Merchant ID. Developer > Payment API crea l'API Key ID e la Secret API Key, Developer > Webhooks la chiave e il secret del webhook. La sezione contiene collegamenti a entrambi i portali e alla documentazione di Worldline.

Test Mode: 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: attivo. Disattivala 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.

Le chiavi segrete e i secret dei webhook salvati non vengono più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: seleziona un secret e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Check credentials: 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 in cima alla pagina, per esempio Test credentials: connection successful., API credentials are not configured. oppure l'errore restituito da Worldline.

Webhook

Il webhook informa il tuo negozio sui 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 mostrato in Endpoint URL in questa sezione. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_worldline_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni: deve rispondere senza reindirizzamenti. Poi inserisci l'ID e il secret della chiave del webhook in Test Webhook Key ID e Test Webhook Secret. Fai lo stesso nell'account live con i campi live.

Il modulo risponde automaticamente alla richiesta di verifica dell'endpoint di Worldline. Gestisce gli eventi di pagamento (cambi di stato dei pagamenti) e gli eventi di rimborso (cambi di stato dei rimborsi). Gli altri eventi vengono accettati e ignorati. I webhook senza una firma valida vengono rifiutati. Un evento deve essere firmato con il secret dell'account in cui è stato effettuato il pagamento, quindi un webhook di test non conferma mai un pagamento live. Un webhook viene ignorato anche se proviene da un Merchant ID diverso da quello dell'account il cui secret lo ha firmato. Senza il webhook, un ordine viene creato 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 predefinita di Worldline.

Order Status After Payment: lo stato dell'ordine una volta che Worldline conferma il pagamento acquisito. I pagamenti vengono sempre richiesti come vendita diretta (autorizzazione e cattura).

I pagamenti autorizzati restano in Awaiting Worldline capture. Le discrepanze di importo o valuta vanno sempre in Worldline payment on hold.

Avanzate

Logging: scrive tutte le richieste API e i webhook in logs/wlg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi, dati della carta e dati personali sono mascherati. Predefinito: disattivato.

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

Delete Data: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo e il registro. Le transazioni e i rimborsi di Worldline e gli stati dell'ordine del modulo restano sempre, perché gli ordini esistenti ne hanno bisogno per i rimborsi. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Worldline) e conferma. Il modulo crea un checkout ospitato di Worldline per il totale del carrello nella valuta del carrello 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 passati a Worldline, e la pagina di pagamento si apre nella lingua del cliente quando Worldline la supporta. Ogni tentativo di pagamento riceve un proprio riferimento composto dall'ID del carrello e da una parte casuale. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna nel tuo negozio. Il modulo 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 di stato o con un webhook firmato. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with Worldline has been received. Se il pagamento è autorizzato ma non ancora acquisito, la pagina mostra Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. Se il pagamento di un ordine di questo tipo fallisce in seguito, la pagina mostra Your Worldline payment was not completed. Please contact us about this order.

Se il pagamento non è stato completato, non viene creato alcun ordine, il carrello viene conservato e il cliente torna al checkout con un messaggio:

Se lo stato non è ancora stato verificato, una pagina Payment confirmation mostra We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. con i pulsanti Check again e Back to checkout. Il webhook crea l'ordine non appena arriva.

Quando il cliente paga di nuovo lo stesso carrello, il modulo verifica prima il tentativo precedente. Se nel frattempo è stato pagato, il cliente passa direttamente alla conferma dell'ordine e non viene addebitato due volte. Se la pagina di pagamento precedente è ancora aperta per lo stesso importo e modalità ed è stata creata meno di 30 minuti fa, il cliente viene rimandato lì.

Se Worldline non può avviare il pagamento, il cliente resta al checkout con Payment error: Could not create checkout session. Please try again. Il motivo viene scritto nel registro. 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 webhook funziona anche mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Il modulo 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 PrestaShop, maggiorazioni né registrazione automatica dei webhook.

Ordini e rimborsi

Stati dell'ordine

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

Payment accepted or Delivered: il pagamento è stato acquisito. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID del pagamento Worldline come ID della transazione, e una nota mostra l'importo, l'ID del pagamento e come è stato confermato (webhook firmato o verifica dello stato).

Awaiting Worldline capture: Worldline segnala il pagamento come autorizzato o la cattura come richiesta, ma non ancora acquisita. Nessun pagamento è ancora registrato. L'ordine passa allo stato pagato quando il webhook conferma la cattura. Se la nota indica che il pagamento non è acquisito, acquisiscilo nel Merchant Portal di Worldline.

Worldline payment on hold: il pagamento non corrisponde al carrello, per esempio perché importo o valuta sono diversi (il carrello è 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. Verifica l'ordine ed evadilo, oppure rimborsa il pagamento.

Payment error: Worldline ha rifiutato o annullato il pagamento di un ordine che attendeva la cattura.

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

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 manualmente l'ordine. 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 cambia. Una nota ti chiede di rimborsare il secondo pagamento nel Merchant Portal di Worldline.

Blocco di pagamento Worldline

La pagina dell'ordine mostra un blocco Worldline payment con l'ID del pagamento, il riferimento del commerciante, il checkout ospitato, lo stato del tentativo, l'importo addebitato e l'importo rimborsato, un badge Test environment per i pagamenti di test, la cronologia dei rimborsi e le Payment notes dell'ordine.

Rimborsi

Nel blocco Worldline payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Worldline. Conferma la domanda Refund this amount through Worldline? This cannot be undone. Sono supportati rimborsi totali e parziali. Il pagamento deve essere acquisito. Ti serve il permesso di modificare gli ordini; l'accesso alle pagine dei moduli non è necessario. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Worldline, quindi dopo una discrepanza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non il totale dell'ordine. Il rimborso viene sempre inviato all'ambiente del pagamento originale (test o live) con le credenziali di quell'account, che quindi devono essere impostate. Un rimborso ritentato dopo un timeout non viene eseguito due volte, e per ciascun ordine viene eseguito un solo rimborso alla volta. Se Worldline rifiuta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso accettato viene aggiunto alla cronologia dei rimborsi e alle note, con l'ID e lo stato del rimborso Worldline. 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 Worldline.

I cambi di stato dei rimborsi da parte di Worldline arrivano via webhook, aggiornano la cronologia dei rimborsi e vengono aggiunti alle note. I rimborsi effettuati nel Merchant Portal non cambiano lo stato dell'ordine né creano note di credito. Aggiornali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Worldline Gateway è il primo blocco di Modules > Module Manager > VibeFox Worldline Gateway > Configure, sopra le impostazioni. Incolla 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 verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto compaiono la riga Product: presta-payment-worldline 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 spiega 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 che l'indirizzo del negozio cambia, o dopo aver liberato uno slot di 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 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. Lo storefront 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 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 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 alla settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

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. La pagina delle impostazioni mostra un avviso se mancano. 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: 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 in Endpoint URL, senza reindirizzamenti. Verifica che il secret del webhook di quell'account sia nel campo corrispondente (Test Webhook Secret o Live Webhook Secret) e che il campo dell'ID della chiave webhook sia vuoto o corrisponda alla chiave. L'ordine viene creato anche quando il cliente torna nel negozio dopo aver pagato.

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

Se il webhook risponde Invalid signature: il secret del webhook appartiene a un altro account o a un'altra chiave, oppure l'ID della chiave del webhook non corrisponde alla chiave che ha inviato il webhook. Verifica che i secret di test e live non siano scambiati.

Se il webhook risponde Missing signature, Empty body o Invalid JSON: la richiesta non è arrivata da Worldline nel formato previsto, oppure un proxy o un reindirizzamento l'ha modificata. Verifica che l'URL risponda senza reindirizzamenti.

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

Se il webhook risponde Retry later: l'ordine era in fase di conferma da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Worldline ritenta il webhook. Guarda il campo Log per il motivo.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'URL accetta solo richieste da Worldline.

Se 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 i valori live nei campi live.

Il cliente vede un errore quando sceglie Worldline: controlla il campo Log nella pagina del modulo. Gli errori vengono registrati anche quando Logging è disattivato. Per i dettagli completi delle richieste, attiva Logging e riprova.

I pagamenti di test non confermano un pagamento live: test e live sono separati. Imposta Test Mode sulla modalità che vuoi usare e utilizza le credenziali e il webhook di quell'account.

L'ordine è in Worldline payment on hold o Awaiting Worldline capture dopo il pagamento: leggi le note nel blocco Worldline payment (vedi Stati dell'ordine). Oppure Worldline non ha ancora confermato la cattura (il webhook completa l'ordine), oppure l'importo o la valuta pagati erano diversi da quelli del carrello.

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

Sviluppatori: l'hook actionWlgHostedCheckoutData modifica la richiesta di checkout ospitato prima dell'invio, per esempio per limitare i metodi di pagamento mostrati.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Worldline 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 modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi di Worldline e gli stati dell'ordine Awaiting Worldline capture e Worldline payment on hold restano sempre, così gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID delle transazioni.

Worldline è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Worldline né approvato da Worldline.