VibeFox OpenPay for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

HTTPS: il tuo sito deve usare HTTPS, perché il modulo della carta è nella tua pagina di checkout.

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

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un dominio.

La carta si inserisce 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 modulo della carta è nella tua pagina, il perimetro PCI DSS è SAQ A-EP; chiedi conferma al tuo acquirente.

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_openpay_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

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

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

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

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

7. Attiva Enable / Disable e salva. Prova un pagamento con le carte di test del sandbox di OpenPay, poi deseleziona Sandbox mode per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > OpenPay. Sopra i campi la pagina ti avvisa quando le chiavi della modalità attuale sono incomplete (in quel caso il metodo di pagamento viene nascosto al checkout), quando la valuta del negozio non è accettata dal paese dell'account selezionato, e mostra Sandbox mode is enabled — no real charges are made. finché la modalità sandbox è attiva. Nell'elenco dei metodi di pagamento, OpenPay risulta da configurare finché la modalità attuale non ha tutte e tre le chiavi, e un badge di modalità di prova viene mostrato finché 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, per 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.

Generali

Enable / Disable: Enable OpenPay card payments attiva o disattiva il metodo di pagamento. Predefinito: disattivo.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Credit or debit card (OpenPay).

Description: il testo mostrato sopra il modulo 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 di OpenPay, in Settings (Configuración). La sezione contiene link ai pannelli di sandbox e di produzione del Messico, della Colombia e del 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: Use the OpenPay sandbox (test keys, no real charges) passa al sandbox sia le chiavi sia l'API. Un badge SANDBOX MODE viene mostrato al checkout finché è attivo. Predefinito: attivo. Deseleziona per accettare pagamenti reali.

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

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

Sandbox Public Key: la chiave pubblica del 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 della versione 1.0 del plugin (un solo set di chiavi e un flag sandbox) vengono spostate automaticamente nei campi sandbox o produzione.

Webhook

Il webhook non è obbligatorio, ma è consigliato. Conferma i pagamenti quando il cliente non torna dalla pagina 3D Secure, per esempio se chiude il browser. Nel pannello di OpenPay vai su Settings > Webhooks e aggiungi l'URL mostrato in questa sezione delle impostazioni. Ha questo aspetto: https://your-site/wc-api/webhook_wc_openpay/. 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:

OpenPay non firma i webhook, quindi il plugin non si fida mai della notifica in sé. La usa solo per trovare l'addebito, poi rilegge l'addebito dalle API di OpenPay con la chiave privata della modalità in cui è stato pagato l'ordine. Una notifica relativa a un addebito che questo negozio non ha creato viene ignorata.

Avanzate

Debug log: Log payment steps (errors are always logged) scrive i passaggi del pagamento in WooCommerce > Status > Logs, origine wcp_openpay_gateway. Errori e avvisi vengono registrati anche quando è disattivato. Chiavi, dati della carta e dati del cliente non vengono mai registrati. Predefinito: disattivo.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Predefinito: disattivo.

Checkout

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). Al momento dell'ordine, openpay.js trasforma la carta in un token monouso nel browser, e la libreria antifrode di OpenPay aggiunge un ID di sessione del dispositivo. Solo questi due valori vengono inviati al tuo negozio.

Il plugin crea poi l'addebito con 3D Secure per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina 3D Secure della sua banca, servita da OpenPay. Ogni tentativo riceve un proprio riferimento ordine in OpenPay (il numero dell'ordine e un breve suffisso). La descrizione dell'addebito è Order #, il numero dell'ordine e il nome del tuo sito. Nome, e-mail e telefono del cliente vengono passati a OpenPay; non viene creato alcun account cliente in OpenPay. L'ordine resta In attesa di pagamento mentre il cliente è nella pagina 3D Secure.

Quando il cliente torna, il plugin legge l'addebito dalle API di OpenPay. L'ordine viene segnato come pagato solo dopo che OpenPay lo conferma: l'addebito deve appartenere a questo ordine, essere completato e corrispondere esattamente al totale e alla valuta dell'ordine. Se il risultato non è ancora noto, la pagina di ordine ricevuto mostra We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Poi il webhook aggiorna l'ordine.

Se la carta viene rifiutata o il 3D Secure non riesce, il cliente torna alla pagina Pay for order con il messaggio The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. e può pagare di nuovo. Prima di un nuovo tentativo, il plugin controlla l'addebito precedente dell'ordine: se risultava davvero pagato, l'ordine viene segnato come pagato senza un secondo addebito; se è ancora in elaborazione, il cliente vede che un pagamento precedente è in corso e non deve pagare di nuovo; se il suo stato non può essere verificato, non viene fatto alcun nuovo tentativo e al cliente viene chiesto di riprovare tra qualche minuto.

Le carte rifiutate ricevono un messaggio chiaro, per 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; vanno nelle note dell'ordine e nel registro.

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). Viene nascosto al checkout quando è disattivato, quando le chiavi della modalità attuale sono incomplete o quando la valuta dell'ordine non è accettata dal paese dell'account.

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

Ordini e rimborsi

Stati dell'ordine

In attesa di pagamento: il cliente è nella pagina 3D Secure oppure non ha terminato il pagamento. Una nota mostra l'ID dell'addebito.

In lavorazione: il pagamento è stato confermato. È lo stato standard di WooCommerce dopo il pagamento; gli ordini con soli prodotti virtuali scaricabili diventano Completato. La nota dell'ordine mostra l'ID dell'addebito e la modalità (produzione o sandbox). L'ID della transazione è l'ID dell'addebito OpenPay.

In attesa: l'addebito è in corso e non ancora acquisito; oppure OpenPay segnala un addebito completato con un importo o una valuta diversi dall'ordine (l'ordine non viene segnato come pagato e la nota mostra la differenza); oppure è arrivato un pagamento per un ordine già annullato. Controlla l'ordine nel pannello di OpenPay e portalo a termine o rimborsa il pagamento lì.

Non riuscito: la carta è stata rifiutata alla creazione dell'addebito, oppure l'ultimo tentativo è fallito, è stato annullato o è scaduto. Il cliente può pagare di nuovo.

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

Rimborsi

Per gli account del Messico e del Perù: apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Credit or debit card (OpenPay) (il pulsante mostra il titolo del tuo metodo di pagamento). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato nella modalità e nel paese dell'account con cui è stato pagato l'ordine, quindi mantieni compilate le chiavi del sandbox finché hai ordini sandbox da rimborsare. Se OpenPay non accetta il rimborso, WooCommerce mostra l'errore, per esempio OpenPay refund failed: ..., e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID di rimborso OpenPay.

OpenPay Colombia non supporta i rimborsi delle carte tramite API, come nei plugin ufficiali di OpenPay. Per la Colombia il pulsante di rimborso non viene offerto; rimborsa l'addebito nel pannello di OpenPay.

I rimborsi e le contestazioni effettuati nel pannello di OpenPay arrivano tramite webhook e vengono aggiunti una sola volta alle note dell'ordine. Non vengono registrati automaticamente come rimborsi di WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza usare il pulsante di OpenPay.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > OpenPay. 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 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 posto per il dominio. Libera il posto 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. I gestori del negozio connessi continuano a vedere 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 controllato di nuovo automaticamente in background.

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: quelle del sandbox in modalità sandbox, quelle di produzione in modalità produzione. Verifica che la valuta del negozio 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.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: il cliente non è tornato dalla pagina 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 mostrano le impostazioni, con gli eventi elencati sopra. Verifica che siano compilate le chiavi della modalità in cui è stato pagato l'ordine: senza di esse il webhook risponde not configured e OpenPay riprova più tardi.

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

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

Il webhook risponde busy: l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. OpenPay riprova il webhook.

Il cliente vede «The secure card form could not be loaded»: openpay.js o la libreria antifrode di OpenPay non si sono caricati 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 è nelle note dell'ordine e nel registro, origine wcp_openpay_gateway. 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.

«This test card cannot be used for real payments»: è stata usata una carta di test del sandbox mentre la modalità sandbox è disattivata.

L'ordine è In attesa dopo il pagamento: leggi la nota dell'ordine. L'addebito è ancora in corso, l'importo o la valuta pagati non corrispondono all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine.

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 blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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 dalla pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, il codice di verifica del webhook memorizzato e i log del plugin vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. I dati degli ordini vengono sempre conservati: gli ordini esistenti mantengono le proprie note di pagamento, gli ID delle transazioni e i dati degli addebiti necessari per i rimborsi dopo una reinstallazione.

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