VibeFox OpenPay for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta l'installazione su versioni precedenti di PHP.

HTTPS: il tuo negozio deve usare HTTPS, perché il form della carta si trova sulla pagina di checkout.

Account OpenPay: un account OpenPay del Messico, della Colombia o del Perù. Ti servono il Merchant ID, la chiave privata (sk_...) e la chiave pubblica (pk_...). I pannelli sandbox e di produzione hanno Merchant ID e chiavi diversi, e il modulo li tiene separati.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo dominio.

La carta viene inserita nella tua pagina di checkout, ma viene letta e tokenizzata nel browser da openpay.js. I campi della carta non hanno un nome e non vengono mai inviati al tuo server. Poiché il form della carta si trova sulla tua pagina, il tuo ambito PCI DSS è SAQ A-EP; chiedilo al tuo acquirer.

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 OpenPay Gateway nell'elenco dei moduli e fai clic su Configure.

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

4. Scegli l'Account country e inserisci le chiavi sandbox e di produzione (vedi Configurazione).

5. Consigliato: aggiungi l'URL del webhook nel pannello di OpenPay (vedi Configurazione).

6. Attiva Enable / Disable e fai clic su Save. Prova un pagamento con le carte di test della sandbox di OpenPay, poi disattiva Sandbox mode per accettare pagamenti reali.

All'installazione il modulo crea due stati dell'ordine, Awaiting OpenPay payment e OpenPay payment on hold. PrestaShop offre un nuovo modulo di pagamento per le valute, i paesi e i gruppi di clienti del tuo negozio. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando le chiavi della modalità attuale sono incomplete (il metodo di pagamento viene quindi nascosto al checkout), quando la valuta predefinita del tuo negozio non è accettata dal paese dell'account selezionato, e mostra Sandbox mode is enabled — no real charges are made. mentre la modalità sandbox è attiva.

Al salvataggio, le chiavi vengono verificate. Un Merchant ID può contenere solo lettere e cifre, una chiave privata deve iniziare con sk_ e una chiave pubblica con pk_. Un valore non valido non viene salvato: resta il valore precedente e compare un errore, ad esempio Sandbox: The private key must start with sk_. Se il metodo di pagamento è attivo ma le chiavi della modalità attuale sono incomplete, vedi anche un messaggio che indica che il gateway resta nascosto al checkout. Un Title vuoto viene rifiutato con Enter a title for the payment method.

OpenPay

Enable / Disable: Enable OpenPay card payments 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: Credit or debit card (OpenPay). Obbligatorio.

Description: il testo mostrato sopra il form della carta al checkout. Predefinito: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

Account OpenPay

Il Merchant ID, la chiave privata (sk_) e la chiave pubblica (pk_) si trovano nel tuo pannello OpenPay, in Settings (Configuración). La sezione contiene collegamenti ai pannelli sandbox e di produzione di Messico, Colombia e Perù.

Account country: il paese del tuo account OpenPay. Determina l'API di OpenPay, la libreria openpay.js di quel paese e le valute accettate. Predefinito: Mexico.

Sandbox mode: usa la sandbox di OpenPay (chiavi di test, nessun addebito reale) e passa sia le chiavi sia l'API alla sandbox. Un badge SANDBOX MODE viene mostrato al checkout mentre è attivo. Predefinito: attivo. Disattivalo per accettare pagamenti reali.

Sandbox Merchant ID: il Merchant ID dal pannello sandbox, Settings (Configuración), chiavi API.

Sandbox Private Key: la chiave privata sandbox. Inizia con sk_. Viene usata solo sul server; non condividerla mai.

Sandbox Public Key: la chiave pubblica sandbox. Inizia con pk_. openpay.js la usa nel browser per tokenizzare la carta.

Live Merchant ID: il Merchant ID dal pannello di produzione, Settings (Configuración), chiavi API.

Live Private Key: la chiave privata di produzione (sk_...).

Live Public Key: la chiave pubblica di produzione (pk_...).

Le chiavi private 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 cambiarlo.

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

Webhook

Il webhook non è obbligatorio, ma consigliato. Conferma i pagamenti quando il cliente non torna dalla pagina del 3D Secure, ad esempio dopo aver chiuso il browser. Nel pannello di OpenPay vai su Settings > Webhooks e aggiungi l'URL mostrato in Webhook URL in questa sezione. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_openpay_gateway/webhook, eventualmente con un codice lingua come /en/. Copialo esattamente come lo mostrano le impostazioni. Aggiungi il webhook nel pannello di ogni modalità che usi (sandbox e produzione).

Quando aggiungi il webhook, OpenPay invia un codice di verifica a questo URL. Il codice compare in questa sezione con la data di arrivo, così puoi confermare il webhook nel pannello di OpenPay.

Seleziona questi eventi (sono elencati anche in questa sezione):

OpenPay non firma i webhook, quindi il modulo non si fida mai della notifica in sé. La usa solo per trovare l'addebito, poi legge l'addebito dall'API di OpenPay con la chiave privata della modalità e del paese dell'account con cui è stato effettuato il pagamento. Una notifica relativa a un addebito che questo negozio non ha creato viene ignorata. Il webhook funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Avanzate

Debug log: registra i passaggi del pagamento in logs/wc_opy_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono registrati anche quando è disattivato. Chiavi, dati della carta e dati dei clienti 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, disinstallando il modulo vengono rimosse le impostazioni del gateway, il codice di verifica del webhook salvato e i registri. Gli addebiti OpenPay degli ordini sono cronologia dei pagamenti e vengono sempre conservati, quindi gli ordini possono ancora essere rimborsati dopo una reinstallazione. Predefinito: disattivato.

Checkout

Nel passaggio di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit or debit card (OpenPay)) e compila Cardholder name, Card number, Expiry (MM/YY) e Card code (CVV). In modalità sandbox il form mostra SANDBOX MODE — Test environment. No real charges will be made. Quando il cliente conferma, openpay.js trasforma la carta in un token monouso nel browser, e la libreria antifrode aggiunge un ID di sessione del dispositivo. Al tuo negozio vengono inviati solo questi due valori e il numero del carrello. Se il form è incompleto, sotto di esso compare Please fill in all card fields.

Il modulo crea quindi l'addebito con 3D Secure per il totale del carrello nella valuta del carrello e invia il cliente alla pagina 3D Secure della sua banca, servita da OpenPay. Ogni tentativo riceve un proprio riferimento ordine OpenPay. La descrizione dell'addebito è Cart #, il numero del carrello e il nome del tuo negozio. Nome, e-mail e telefono del cliente vengono passati a OpenPay; non viene creato alcun account cliente OpenPay. A questo punto non esiste ancora alcun ordine.

Quando il cliente torna, il modulo legge l'addebito dall'API di OpenPay. L'ordine viene segnato come pagato solo dopo la conferma di OpenPay: l'addebito deve appartenere a questo carrello, essere completato e corrispondere esattamente a totale e valuta del carrello. Poi l'ordine viene creato e il cliente vede la pagina di conferma dell'ordine con Your card payment has been received. Se OpenPay segnala l'addebito come in corso, l'ordine viene creato in Awaiting OpenPay payment e la pagina mostra We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Se il risultato non è ancora noto, una pagina Payment confirmation mostra lo stesso testo con un pulsante Check again e un pulsante Back to checkout; il webhook crea l'ordine appena arriva. Se un addebito in corso fallisce più tardi, la pagina di conferma dell'ordine mostra Your OpenPay card payment was not completed. Please contact us about this order.

Se la carta viene rifiutata o il 3D Secure fallisce, il cliente torna al checkout con The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. e può pagare di nuovo. Il carrello viene conservato. Prima di un nuovo tentativo, il modulo verifica l'addebito precedente del carrello: se è stato effettivamente pagato, l'ordine viene creato da esso senza un secondo addebito; se è ancora in corso, l'ordine viene creato in Awaiting OpenPay payment; se non è possibile verificarne lo stato, non viene effettuato alcun nuovo addebito e il cliente vede We could not confirm the status of your previous payment attempt. Please try again in a few minutes. Un carrello che ha già un ordine non viene mai addebitato di nuovo.

Le carte rifiutate ricevono un messaggio chiaro, ad esempio The card has insufficient funds. Please use another card., The card has expired. Please use another card. o The security code (CVV) is not valid. Please check it and try again. Gli errori tecnici di OpenPay non vengono mai mostrati ai clienti; finiscono nel registro.

Se un buono sconto nel carrello smette di essere valido tra il pagamento e la sua conferma, viene rimosso dall'ordine. L'ordine passa quindi a OpenPay payment on hold con una nota, perché il cliente ha pagato il prezzo con lo sconto.

Il metodo di pagamento viene nascosto al checkout quando è disattivato, quando le chiavi della modalità attuale sono incomplete o quando la valuta del carrello non è accettata dal paese dell'account.

Il modulo accetta solo pagamenti con carta, con cattura immediata. Non prevede carte salvate, abbonamenti, pagamenti senza interessi (MSI) o a rate, pagamenti con punti carta, contanti, SPEI, PSE o CoDi, né autorizzazione e cattura separate.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente si trova nella pagina del 3D Secure, non ha completato il pagamento oppure la carta è stata rifiutata. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID dell'addebito OpenPay come ID transazione, e una nota mostra l'ID dell'addebito e la modalità (produzione o sandbox).

Awaiting OpenPay payment: OpenPay segnala l'addebito come in corso (non ancora catturato). L'ordine passa a Payment accepted quando l'addebito viene completato, oppure a Payment error se fallisce.

OpenPay payment on hold: OpenPay segnala un addebito completato con importo o valuta diversi da quelli del carrello (l'ordine non viene segnato come pagato e la nota mostra la differenza), un buono sconto è stato rimosso, oppure è arrivato un pagamento per un ordine già annullato o rimborsato (il pagamento viene registrato). Controlla l'ordine ed evadilo, oppure rimborsa il pagamento nel pannello di OpenPay.

Payment error: un addebito in corso è fallito, è stato annullato o è scaduto.

Refunded: l'addebito è stato rimborsato per intero tramite il modulo.

Se arriva un secondo addebito completato per un ordine già pagato, l'ordine non viene modificato. Una nota che inizia con WARNING ti chiede di rimborsare il duplicato nel pannello di OpenPay.

Blocco pagamento OpenPay

La pagina dell'ordine mostra un blocco OpenPay payment con l'ID dell'addebito, lo stato dell'addebito, l'ambiente e il paese dell'account, l'importo addebitato e il totale dell'ordine, l'importo rimborsato, un badge Sandbox per i pagamenti sandbox, la cronologia dei rimborsi e le OpenPay notes dell'ordine.

Rimborsi

Per gli account di Messico e Perù: nel blocco OpenPay payment inserisci l'importo (viene compilato quello non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via OpenPay. Conferma la domanda Refund this amount through OpenPay? This cannot be undone. Sono supportati rimborsi totali e parziali, fino all'importo addebitato da OpenPay. Ti serve il permesso di modificare gli ordini. Il rimborso viene inviato con le chiavi della modalità e del paese dell'account con cui è stato effettuato l'addebito, quindi le chiavi di quella modalità devono essere impostate: mantieni le chiavi sandbox finché puoi ancora rimborsare ordini sandbox. Se OpenPay non accetta il rimborso, il blocco mostra l'errore, ad esempio OpenPay refund failed: ..., e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note con l'ID del rimborso OpenPay. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili solo quando OpenPay ha confermato il pagamento; un ordine in attesa dopo una differenza di importo non viene rimborsato tramite il modulo.

OpenPay Colombia non supporta i rimborsi di carte tramite API, come nei plugin ufficiali di OpenPay. Per gli addebiti colombiani il blocco non offre un form di rimborso; rimborsa l'addebito nel pannello di OpenPay.

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

I rimborsi e le contestazioni effettuati nel pannello di OpenPay arrivano tramite webhook e vengono aggiunti alle note una sola volta. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente. Aggiornali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox OpenPay Gateway è il primo blocco di Modules > Module Manager > VibeFox OpenPay Gateway > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopo di ciò il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino a cui 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 di essi ci sono la riga Product: presta-payment-openpay 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 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. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, OpenPay 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 il rinnovo. Lo stato viene controllato di nuovo 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

OpenPay non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che la modalità attuale abbia tutte e tre le chiavi: le chiavi sandbox in modalità sandbox, quelle di produzione in modalità produzione. Verifica che la valuta del carrello sia accettata dall'Account country (Messico: MXN, USD; Colombia: COP, USD; Perù: PEN, USD). La pagina delle impostazioni mostra un avviso in ciascuno di questi casi. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo di clienti.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il cliente non è tornato dalla pagina del 3D Secure e il webhook non funziona. Verifica che l'URL del webhook sia aggiunto nel pannello di OpenPay della modalità che usi, esattamente come mostrato nelle impostazioni, con gli eventi elencati sopra. Verifica che le chiavi della modalità in cui è stato effettuato il pagamento siano compilate: senza di esse il webhook risponde not configured e OpenPay riprova più tardi. L'ordine viene creato anche quando il cliente torna nel negozio o quando tenta di pagare di nuovo lo stesso carrello.

Il webhook risponde ignored (unknown order): l'addebito non è stato creato da questo negozio, ad esempio un addebito di un altro negozio sullo stesso account OpenPay. Non viene modificato nulla.

Il webhook risponde verification failed: non è stato possibile raggiungere l'API di OpenPay per leggere l'addebito. OpenPay riprova il webhook.

Il webhook risponde busy: il carrello era in aggiornamento da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (ad esempio perché il modulo è disattivato). OpenPay riprova il webhook. Attiva il Debug log per vedere il motivo.

Il cliente vede The secure card form could not be loaded: openpay.js o la libreria antifrode di OpenPay non si è caricata nel browser, oppure non è stato possibile creare l'ID di sessione del dispositivo. Chiedi al cliente di ricaricare la pagina e riprovare.

Il cliente vede The payment could not be processed right now: OpenPay ha rifiutato la richiesta o non ha risposto. Il motivo è nel registro. Una causa tipica è un Merchant ID o una chiave privata errati. Se OpenPay non ha risposto, controlla l'addebito nel pannello di OpenPay prima che il cliente paghi di nuovo.

Il cliente vede This test card cannot be used for real payments: è stata usata una carta di test sandbox mentre la modalità sandbox era disattivata.

L'ordine è in OpenPay payment on hold dopo il pagamento: leggi le OpenPay notes nel blocco (vedi Stati dell'ordine), poi evadi l'ordine o rimborsa il pagamento.

Il rimborso non riesce con un messaggio sulla modalità: l'ordine è stato pagato in modalità sandbox o produzione, e le chiavi di quella modalità non sono impostate. Inseriscile e riprova.

Il rimborso non riesce con The order is being updated right now: un webhook o un'altra richiesta stava aggiornando l'ordine nello stesso momento. Riprova tra poco.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox OpenPay Gateway 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 gateway, il codice di verifica del webhook salvato e i registri. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione futura. I record di addebiti e rimborsi OpenPay e gli stati dell'ordine Awaiting OpenPay payment e OpenPay payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID di transazione.

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