VibeFox Culqi for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 6.0 o successivo, installato e attivo. Senza WooCommerce il plugin non si attiva.

PHP: 8.0 o successivo.

Valuta del negozio: sol peruviano (PEN) o dollaro statunitense (USD). Culqi non accetta altre valute e, con qualsiasi altra valuta del negozio, il metodo di pagamento viene nascosto nel checkout.

Account Culqi: ti servono la chiave pubblica e la chiave segreta del tuo account Culqi. Le chiavi di integrazione (test) si trovano su integ-panel.culqi.com, quelle di produzione (live) su mipanel.culqi.com, in CulqiPanel > Desarrollo > API Keys. La chiave pubblica è usata dal popup di Culqi nel browser. La chiave segreta è usata solo sul tuo server e non viene mai inviata al browser. Non serve alcun webhook.

Chiave di licenza VibeFox: acquistata 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 via FTP la cartella wcp_culqi_payment in /wp-content/plugins/.

2. Fai clic su Activate.

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

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

5. Incolla le chiavi di integrazione e, per i pagamenti reali, le chiavi di produzione (vedi Configurazione).

6. Attiva Enable/Disable. Lascia attivo Test Mode mentre provi, poi deseleziona la casella per accettare pagamenti reali.

7. Assicurati che la valuta del negozio sia PEN o USD.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Culqi. Sopra i campi la pagina mostra Test mode is active: the integration keys are used and no real money is charged. finché la modalità test è attiva. Ti avvisa quando il gateway è attivo ma mancano le chiavi della modalità corrente, e quando la valuta del negozio non è supportata da Culqi. In entrambi i casi il metodo di pagamento viene nascosto nel checkout. Nell'elenco dei metodi di pagamento, Culqi è indicato come da configurare finché non sono impostate entrambe le chiavi della modalità corrente.

Generale

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

Title: il nome del metodo di pagamento che i clienti vedono nel checkout. Predefinito: Credit/Debit Card or Yape (Culqi).

Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay securely with your credit/debit card or Yape via Culqi.

Chiavi API

Copia le chiavi da CulqiPanel > Desarrollo > API Keys: le chiavi di integrazione (test) su integ-panel.culqi.com, quelle di produzione su mipanel.culqi.com. La modalità test usa solo le chiavi di test, la modalità live solo le chiavi live. Ogni chiave deve iniziare con il prefisso del suo campo. Una chiave con un prefisso errato non viene salvata: la pagina mostra un errore e mantiene il valore precedente.

Test Mode: Use the Culqi integration (test) environment. Quando è attiva, vengono usate le chiavi di test (pk_test_ / sk_test_) e non viene addebitato denaro reale. Predefinito: attivo. Deseleziona la casella per accettare pagamenti reali con le chiavi live.

Test Public Key: la chiave pubblica dell'ambiente di integrazione. Inizia con pk_test_.

Test Secret Key: la chiave segreta dell'ambiente di integrazione. Inizia con sk_test_ e non viene mai condivisa con il browser.

Live Public Key: la chiave pubblica dell'ambiente di produzione. Inizia con pk_live_.

Live Secret Key: la chiave segreta dell'ambiente di produzione. Inizia con sk_live_ e non viene mai condivisa con il browser.

Se aggiorni dalla versione 1.0, l'unica coppia di chiavi di quella versione viene spostata nei campi test o live in base al suo prefisso. Controlla le chiavi dopo l'aggiornamento.

Metodi di pagamento

Le carte sono sempre offerte. Bonifico bancario, agenti, wallet e Cuotéalo richiedono la Culqi Orders API e non sono offerti da questo plugin.

Yape: Offer Yape in the Culqi popup mostra Yape accanto alle carte nella finestra di Culqi. Predefinito: attivo.

Avanzate

Debug log: Log API requests and payment steps scrive i dettagli in WooCommerce > Status > Logs, origine wcp_culqi_payment. Gli errori vengono sempre registrati. Chiavi, dati della carta e dati del cliente non vengono mai registrati. Predefinito: disattivato.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. Disattivare il plugin non elimina mai nulla. I dati di Culqi salvati negli ordini vengono sempre conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card or Yape (Culqi)) e fa clic sul pulsante per effettuare l'ordine. Il popup di Culqi Checkout si apre nella stessa pagina con il nome del tuo negozio, il totale dell'ordine e la valuta. Qui il cliente inserisce i dati della carta o paga con Yape. Finché la modalità test è attiva, il metodo di pagamento mostra TEST MODE: No real charges will be made.

Culqi trasforma i dati di pagamento in un token monouso e il checkout viene inviato al tuo negozio con quel token. Il tuo server crea l'addebito con la Culqi Charges API per il totale dell'ordine nella valuta dell'ordine, con il numero dell'ordine nella descrizione dell'addebito. L'ordine viene segnato come pagato solo dopo che Culqi ha confermato l'addebito e l'importo e la valuta addebitati corrispondono all'ordine. Poi il cliente passa alla pagina di ordine ricevuto.

Se la banca richiede 3-D Secure, il cliente vede Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. Dopo l'autenticazione l'addebito viene inviato di nuovo automaticamente. Se la verifica non viene completata, il cliente vede The 3-D Secure verification was not completed. Please try again or use another card.

Se la carta viene rifiutata, il cliente vede il messaggio di Culqi, per esempio Payment failed: seguito dal motivo, e può riprovare con un'altra carta. Se Culqi non risponde, il cliente vede We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Se il cliente chiude la finestra di Culqi, non viene addebitato nulla, il cliente vede The payment window was closed before the payment was completed. e può effettuare di nuovo l'ordine.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con l'High-Performance Order Storage (HPOS) di WooCommerce.

Il plugin accetta solo pagamenti singoli con carta e Yape, acquisiti immediatamente. Non prevede codici PagoEfectivo o CIP, app bancaria, agenti, wallet o Cuotéalo, né carte salvate, abbonamenti o pagamenti rateali, né webhook di Culqi, né autorizzazione e acquisizione separate.

Ordini e rimborsi

Stati dell'ordine

Pending payment: l'ordine è stato creato ma non ancora addebitato, oppure Culqi non ha risposto. In tal caso una nota riporta Culqi did not confirm the charge. Cerca in CulqiPanel un addebito di questo ordine prima di accettare un altro pagamento.

Processing: il pagamento è stato confermato (impostazione predefinita di WooCommerce; gli ordini con soli prodotti virtuali scaricabili passano a Completato). La nota dell'ordine mostra l'ID dell'addebito Culqi, la modalità (test o live) e se è stato usato 3-D Secure. L'ID transazione è l'ID dell'addebito Culqi.

On hold: Culqi ha segnalato un addebito il cui importo o la cui valuta non corrisponde all'ordine, oppure un pagamento autorizzato ma non acquisito. La nota dell'ordine lo spiega e mostra l'ID dell'addebito. Controlla l'addebito in CulqiPanel e completa o rimborsa l'ordine manualmente.

Failed: la carta è stata rifiutata. La nota dell'ordine mostra il motivo, il codice del rifiuto e l'ID dell'addebito. Il cliente può pagare di nuovo con un'altra carta.

Un ordine già pagato o che ha già un addebito Culqi, compreso un ordine in sospeso, non viene mai addebitato di nuovo. Per ogni ordine viene elaborata una sola richiesta di pagamento alla volta.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Culqi. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato con le chiavi della modalità in cui è stato effettuato il pagamento (test o live), anche se nel frattempo hai cambiato modalità, quindi la chiave segreta di quella modalità deve essere impostata. Se Culqi non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID del rimborso Culqi, l'importo e il motivo.

I rimborsi effettuati in CulqiPanel non vengono sincronizzati con WooCommerce. Se serve, crea un rimborso manuale in WooCommerce senza Refund via Culqi.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Culqi. 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 su vibefox.net.

Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera il suo posto per il dominio. Libera il posto nel tuo account su vibefox.net.

Senza una chiave attiva, Culqi non viene mostrato ai clienti nel checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio che hanno effettuato l'accesso vedono comunque il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i rimborsi continuano a funzionare.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Culqi non compare nel checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivo, che entrambe le chiavi della modalità corrente siano impostate (Test Public Key e Test Secret Key in modalità test, Live Public Key e Live Secret Key in modalità live) e che la valuta del negozio sia PEN o USD. La pagina delle impostazioni mostra un avviso in ciascuno di questi casi.

Il pagamento è andato a buon fine, ma l'ordine resta in Pending payment: il plugin non usa webhook. L'addebito viene confermato solo dalla risposta di Culqi al tuo server. Se Culqi non ha risposto in tempo, la nota dell'ordine riporta Culqi did not confirm the charge. Trova l'addebito di questo ordine in CulqiPanel e, se esiste, completa l'ordine manualmente.

L'ordine è in On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta addebitati erano diversi da quelli dell'ordine, oppure il pagamento non è stato acquisito. Controlla l'addebito in CulqiPanel (il suo ID è nella nota), poi completa o rimborsa l'ordine.

La chiave non viene salvata: l'errore indica che il campo deve iniziare con un prefisso, per esempio sk_live_. Ogni campo accetta solo chiavi del proprio tipo e della propria modalità: pk_test_, sk_test_, pk_live_ o sk_live_.

Il cliente vede Payment gateway misconfiguration. Please contact the store owner.: mancano le chiavi della modalità corrente, oppure Culqi ha rifiutato la chiave segreta. Controlla le chiavi nelle impostazioni.

Il cliente vede Payment token is invalid. Please try again.: il token della finestra di Culqi appartiene all'altra modalità, per esempio dopo aver cambiato Test Mode mentre la pagina del checkout era aperta. Il cliente deve ricaricare la pagina e pagare di nuovo.

La finestra di Culqi non si apre: il cliente vede The Culqi payment window could not be loaded. Please reload the page and try again. Controlla che gli script di js.culqi.com e 3ds.culqi.com non siano bloccati nella tua pagina del checkout, per esempio da un plugin di ottimizzazione.

Il cliente vede This order is already being paid: in quel momento era in corso un'altra richiesta di pagamento per lo stesso ordine. Il cliente deve attendere e controllare l'e-mail prima di riprovare.

Il rimborso non riesce e mostra un messaggio sulle chiavi: il pagamento è stato effettuato in modalità test o live e la chiave segreta di quella modalità non è impostata. Inseriscila e riprova.

Il blocco della 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 su 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.

Per gli sviluppatori, la documentazione del plugin elenca i filtri culqi_p_supported_currencies, culqi_p_charge_data, culqi_p_icon e culqi_p_lock_timeout.

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 e i registri vengono rimossi solo se Delete Data on Uninstall era attivo. In caso contrario restano per una reinstallazione successiva. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

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