VibeFox Culqi for OpenCart — Guida

Requisiti

OpenCart: 3.0.x (testato con 3.0.5.0) o 4.0.2 e successive (testato con 4.1.0.3).

PHP: 8.0 o successivo.

Valuta del negozio: il sol peruviano (PEN) o il dollaro statunitense (USD) devono essere una valuta abilitata nel tuo negozio. Culqi non accetta altre valute, e il metodo di pagamento viene mostrato solo quando il cliente paga in PEN o USD.

Account Culqi: ti servono la chiave pubblica e la chiave segreta del tuo account Culqi. Le chiavi di integrazione (test) si ottengono da integ-panel.culqi.com, quelle di produzione (live) da mipanel.culqi.com, in CulqiPanel > Desarrollo > API Keys. La chiave pubblica viene usata dal popup di Culqi nel browser. La chiave segreta viene 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

Il download è un unico file zip con i pacchetti per entrambe le versioni di OpenCart. Decomprimilo sul tuo computer. Contiene README.txt, il pacchetto per OpenCart 3 wcp_culqi_payment-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 wcp_culqi_payment.ocmod.zip. Installa solo il pacchetto per la tua versione di OpenCart. La chiave di licenza è la stessa per entrambe le versioni.

OpenCart 3

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_culqi_payment-oc3-(version).ocmod.zip. L'estensione non ha modifiche OCMOD, quindi Extensions > Modifications non richiede un aggiornamento. Invece dell'installer, puoi anche copiare il contenuto della cartella upload di questo pacchetto nella cartella principale del tuo negozio.

2. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Culqi Payment e clicca su Install (il pulsante verde +). Il tuo utente amministratore deve avere il permesso di modificare l'elenco delle estensioni di pagamento.

3. Clicca su Edit (il pulsante con la matita) per aprire la pagina delle impostazioni. Incolla la tua chiave di licenza VibeFox in License key, nel blocco della licenza in cima alla pagina, e clicca su Activate (vedi Chiave di licenza).

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

5. Attiva Enable/Disable e clicca su Save. Mantieni Test Mode attivo mentre fai le prove, poi disattivalo per accettare pagamenti reali.

OpenCart 4

1. Nel pannello di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_culqi_payment.ocmod.zip. Non rinominare il file: OpenCart 4 ricava il codice dell'estensione dal nome del file, e un pacchetto rinominato non funziona.

2. Il pacchetto compare nell'elenco delle estensioni installate nella stessa pagina. Clicca su Install (il pulsante verde +) accanto a esso.

3. Vai su Extensions > Extensions e scegli il tipo Payments. Trova VibeFox Culqi Payment, clicca su Install (il pulsante verde +), poi su Edit (il pulsante con la matita).

4. Inserisci la chiave di licenza e le chiavi Culqi come nei passaggi 3–5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali nelle due versioni.

Una nuova installazione parte con il metodo di pagamento disattivato e la modalità test attiva.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit. Le sezioni sono elencate a sinistra; il pulsante Save sotto l'elenco salva l'intera pagina. Sopra le impostazioni 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 è abilitato ma mancano le chiavi della modalità corrente, e quando nessuna valuta abilitata del negozio è supportata da Culqi. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Se la tua valuta predefinita non è PEN né USD, la pagina segnala che Culqi viene offerto solo quando il cliente paga in una valuta supportata. Senza il permesso di modificare l'estensione, la pagina mostra le impostazioni ma non può salvarle.

Quando salvi, un valore errato non viene salvato e mantiene il valore precedente, mentre gli altri campi vengono salvati. La pagina mostra un errore per ciascun campo di questo tipo: una chiave con il prefisso sbagliato (per esempio Live Secret Key must start with sk_live_ — the previous value was kept.), un Title vuoto o più lungo di 128 caratteri, un Sort Order che non è un numero intero, un Total che non è un numero maggiore o uguale a 0, oppure una zona geografica o uno stato dell'ordine che non esiste.

Culqi

Enable/Disable: Enable Culqi Payment 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: Credit/Debit Card or Yape (Culqi). Obbligatorio, fino a 128 caratteri.

Description: il testo mostrato al cliente nel passaggio Confirm Order, sopra il pulsante di conferma. Predefinito: Pay securely with your credit/debit card or Yape via Culqi.

Sort Order: la posizione di Culqi tra i metodi di pagamento al checkout. Lascia il campo vuoto oppure inserisci un numero intero.

Geo Zone: offri Culqi solo per gli indirizzi di pagamento nella zona geografica selezionata. Predefinito: All zones. Le zone geografiche si configurano in System > Localisation > Geo Zones.

Total: il totale del checkout, nella valuta predefinita del negozio, che un ordine deve raggiungere prima che Culqi venga offerto. Lascia il campo vuoto per offrire Culqi per qualsiasi totale.

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 pagina contiene i link). La modalità test usa solo le chiavi di test, la modalità live solo le chiavi live. Ogni chiave deve iniziare con il prefisso del proprio campo.

Test Mode: quando è attivo, vengono usate le chiavi di test (pk_test_ / sk_test_) e non viene addebitato denaro reale. Predefinito: attivo. Disattivalo per accettare pagamenti reali con le chiavi live. Finché è attivo, i clienti vedono TEST MODE: No real charges will be made. nel passaggio Confirm Order.

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.

Le chiavi segrete salvate non vengono più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarlo. Per rimuovere una chiave segreta salvata, spunta Clear the saved key on save sotto il campo e clicca su Save.

Metodi di pagamento

Le carte sono sempre offerte. Bonifico bancario, agenti, wallet e Cuotéalo richiedono l'API Culqi Orders e non vengono offerti da questa estensione.

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

Ordini

OpenCart crea l'ordine nel passaggio Confirm Order senza stato (un ordine mancante). L'ordine riceve uno stato solo dopo che Culqi ha confermato l'addebito. Ciascuno dei campi seguenti elenca gli stati degli ordini del tuo OpenCart.

Order Status After Payment: Culqi ha confermato l'addebito e il suo importo e la sua valuta corrispondono all'ordine. Predefinito: Processing.

On Hold (Review) Status: Culqi ha addebitato un importo o una valuta che non corrispondono all'ordine, oppure non ha acquisito il pagamento. Una nota spiega cosa controllare in CulqiPanel. Predefinito: Pending, perché OpenCart non ha lo stato On hold. Puoi creare un tuo stato in System > Localisation > Order Statuses e selezionarlo qui.

Refunded Status: il pagamento è stato rimborsato interamente dalla pagina dell'ordine. I rimborsi parziali aggiungono solo una nota. Predefinito: Refunded.

Avanzate

Debug log: registra le richieste API e i passaggi del pagamento in culqi_p_debug.log.php, nella cartella dei log di OpenCart (storage/logs). Il file non può essere aperto dal web e, al raggiungimento di 5 MB, viene spostato in culqi_p_debug.old.log.php. Gli errori, inclusi i rifiuti delle carte con il loro codice, vengono sempre registrati. Chiavi, dati delle carte e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Log: mostra la dimensione e le ultime voci del registro. Clicca su Clear log per svuotarlo.

Delete data on uninstall: quando è attivo, la disinstallazione dell'estensione rimuove le impostazioni del gateway e il registro. Gli addebiti e i rimborsi di Culqi vengono sempre mantenuti, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Predefinito: disattivato.

Importa / Esporta

Export: Download JSON salva le impostazioni in un file JSON. Le chiavi segrete non vengono esportate.

Import: incolla il JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni. Le chiavi segrete salvate vengono mantenute.

Checkout

Nel passaggio Payment Method il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card or Yape (Culqi)). Nel passaggio Confirm Order il cliente vede la tua descrizione, e OpenCart crea l'ordine, ancora senza stato. Quando il cliente clicca su Confirm Order, si apre sulla stessa pagina il popup Culqi Checkout con il nome del tuo negozio, il totale dell'ordine e la valuta. Lì il cliente inserisce i dati della carta oppure paga con Yape. Gli script di Culqi vengono sempre caricati da Culqi. Su OpenCart 4 il cliente sceglie il metodo di pagamento con il pulsante Choose del blocco del metodo di pagamento, nella finestra Payment method options, e clicca su Confirm Order nel blocco di conferma in fondo alla pagina di checkout. Se il negozio non chiede un indirizzo di pagamento (impostazione predefinita di OpenCart 4), i dati del cliente inviati con l'addebito vengono presi dall'indirizzo di spedizione e dal nome del cliente.

Culqi trasforma i dati di pagamento in un token monouso, e solo quel token viene inviato al tuo negozio. Il tuo server crea l'addebito con l'API Culqi Charges per il totale dell'ordine nella valuta dell'ordine, acquisito immediatamente. L'addebito compare in CulqiPanel come Order con il numero dell'ordine e l'e-mail del cliente. L'ordine viene segnato come pagato solo dopo la conferma di Culqi. Poi l'ordine riceve il suo stato nel modo standard di OpenCart, con le consuete e-mail d'ordine e l'aggiornamento delle scorte, e il cliente vede la pagina di successo dell'ordine di OpenCart.

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 dopo Payment failed: e può riprovare con un'altra carta nello stesso passaggio. 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. In questi casi l'ordine resta senza stato e una nota nella cronologia dell'ordine registra il tentativo. Se il cliente chiude la finestra di Culqi, non viene addebitato nulla e il pulsante Confirm Order può essere cliccato di nuovo. Il carrello viene conservato in tutti questi casi.

Un ordine non viene mai addebitato due volte. Se il cliente invia di nuovo mentre è in corso un pagamento dello stesso ordine, vede This order is already being paid. Please wait a moment and check your email before trying again. Se Culqi ha incassato il denaro ma non è stato possibile impostare lo stato dell'ordine, il cliente vede Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. L'addebito viene mantenuto, e il tentativo successivo con lo stesso carrello imposta lo stato dell'ordine a partire da esso, senza un nuovo addebito. Un carrello viene pagato una sola volta: se un altro ordine dello stesso carrello (OpenCart 3 crea un nuovo ordine ogni volta che viene mostrato il passaggio Confirm Order) è già pagato, il cliente va alla pagina di successo e non viene addebitato di nuovo. OpenCart 4 mantiene un solo ordine per il checkout e lo aggiorna, quindi dopo una carta rifiutata il cliente paga lo stesso ordine.

OpenCart 4 mantiene l'ordine nel checkout finché non viene mostrata la pagina di successo. Se quell'ordine è stato chiuso dal negozio nel frattempo (per esempio annullato o rimborsato), oppure è già pagato e il carrello è cambiato da allora (altri prodotti o quantità), Confirm Order rimanda il cliente al checkout, che crea un nuovo ordine del carrello con un pagamento proprio. Un ordine pagato e poi chiuso non trattiene più il carrello.

L'estensione accetta solo pagamenti unici con carta e Yape, acquisiti immediatamente. Non prevede app bancaria, agenti, wallet o Cuotéalo, né carte salvate, abbonamenti o rate, né webhook di Culqi, né autorizzazione e acquisizione separate.

Ordini e rimborsi

Stati degli ordini

No status (missing order): il cliente non ha ancora pagato, la carta è stata rifiutata o Culqi non ha risposto. In Sales > Orders questi ordini vengono mostrati solo con il filtro Order Status impostato su Missing Orders. Le note nella cronologia dell'ordine spiegano i tentativi non riusciti.

Order Status After Payment (default Processing): l'addebito è stato confermato e corrisponde all'ordine. Una nota mostra Culqi payment successful con la modalità (test o live), 3-D Secure se utilizzato, e l'ID dell'addebito Culqi (chr_...).

On Hold (Review) Status (default Pending): Culqi ha segnalato un addebito il cui importo o la cui valuta non corrispondono all'ordine, oppure un pagamento autorizzato ma non acquisito. La nota lo spiega e mostra l'ID dell'addebito. Controlla l'addebito in CulqiPanel, poi evadi l'ordine oppure rimborsa il pagamento.

Refunded Status (default Refunded): il pagamento è stato rimborsato interamente tramite l'estensione.

Le note sono voci della History dell'ordine che il cliente non vede.

Scheda VibeFox Culqi Payment

In Sales > Orders apri un ordine pagato con Culqi. In fondo alla pagina dell'ordine, accanto a History e Additional, la scheda VibeFox Culqi Payment mostra il Charge ID con l'etichetta Test per i pagamenti di test, l'Amount addebitato (con 3-D Secure se utilizzato), un suggerimento Review per gli ordini in sospeso, gli importi Paid / refunded, il modulo di rimborso, la cronologia dei rimborsi e le Culqi notes dell'ordine. La scheda viene mostrata agli utenti che hanno accesso all'estensione.

Rimborsi

Nella scheda VibeFox Culqi Payment inserisci l'Amount (viene compilato l'importo non ancora rimborsato), facoltativamente un Reason (optional), e clicca su Refund via Culqi. Conferma la domanda Refund this amount through Culqi? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare l'estensione (impostato in System > Users > User Groups). I rimborsi vengono effettuati nell'importo e nella valuta che Culqi ha addebitato, quindi dopo una discrepanza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non al totale dell'ordine. Il rimborso viene inviato con le chiavi della modalità in cui è stato fatto 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, la scheda mostra l'errore e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note, con l'ID del rimborso Culqi, l'importo e il tuo motivo. Un rimborso totale imposta l'ordine su Refunded Status senza avvisare il cliente e senza rimettere i prodotti in magazzino, come una modifica manuale dello stato. Un rimborso parziale non cambia lo stato.

I resi di prodotti in Sales > Returns non restituiscono denaro tramite Culqi. I rimborsi effettuati in CulqiPanel non vengono sincronizzati con OpenCart. Aggiorna l'ordine manualmente se necessario.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Culqi Payment è il primo blocco di Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per 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 si trovano la riga Product: opencart-payment-culqi e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo gli utenti amministratori con il permesso Modify per l'estensione possono modificare la chiave. I testi del blocco seguono la lingua dell'amministrazione (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco spiega il motivo, per 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 è cambiato, o dopo aver liberato uno slot di dominio nel tuo account, clicca su Check now. Se il server delle licenze non è raggiungibile, l'estensione continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: l'indirizzo del negozio dalla configurazione di OpenCart. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Culqi 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. Un utente amministratore che ha effettuato l'accesso all'amministrazione nello stesso browser vede ancora il metodo di pagamento nel negozio, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare l'estensione prima di acquistare una chiave. Su OpenCart 4 questa anteprima non è disponibile: il negozio non vede l'accesso all'amministrazione, quindi senza una chiave attiva il metodo di pagamento è nascosto a tutti. Dopo aver aperto una volta la pagina Edit, nella Dashboard dell'amministrazione compare un promemoria. Chiudilo con × per nasconderlo per 7 giorni. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati, e i rimborsi funzionano.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato di nuovo automaticamente quando apri la Dashboard o la pagina Edit dell'amministrazione: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione dell'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Culqi non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che siano impostate entrambe le chiavi della modalità corrente (Test Public Key e Test Secret Key in modalità test, Live Public Key e Live Secret Key in modalità live) e che il cliente paghi in PEN o USD. La pagina delle impostazioni mostra un avviso quando mancano delle chiavi. Verifica anche che l'indirizzo di pagamento sia nella Geo Zone selezionata e che l'ordine raggiunga il Total impostato nelle impostazioni.

Il pagamento è andato a buon fine, ma l'ordine resta senza stato: l'estensione non usa webhook. L'addebito viene confermato solo dalla risposta di Culqi al tuo server. Se Culqi non ha risposto in tempo, l'ordine riporta la nota Culqi did not confirm the charge. Cerca l'addebito di questo ordine in CulqiPanel. Se il cliente ha visto il messaggio che l'ordine non poteva essere completato, il tentativo di pagamento successivo nella stessa sessione del cliente imposta lo stato senza addebitare di nuovo.

L'ordine è nello stato di revisione dopo il pagamento: leggi le note nella scheda VibeFox Culqi Payment. L'importo o la valuta addebitati erano diversi dall'ordine, oppure il pagamento non è stato acquisito. Controlla l'addebito in CulqiPanel, poi evadi l'ordine oppure rimborsa il pagamento.

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 proveniente dalla finestra di Culqi appartiene all'altra modalità, per esempio dopo aver cambiato Test Mode mentre la pagina di 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. Verifica che gli script da js.culqi.com e 3ds.culqi.com non siano bloccati nella pagina di checkout, per esempio da un'estensione di cache o di ottimizzazione.

Il cliente vede Security check failed. Please reload the page and try again.: la pagina di checkout era aperta in un'altra sessione. Ricaricare la pagina risolve il problema.

Il cliente vede This payment method is not available.: la sessione di checkout non ha più un ordine Culqi, oppure nel frattempo il metodo di pagamento è stato disattivato. Il cliente ricarica il checkout.

Una carta è stata rifiutata e vuoi conoscere il motivo: leggi la nota sull'ordine oppure il campo Log nella pagina dell'estensione. I rifiuti vengono registrati con il codice di rifiuto di Culqi anche quando Debug log è disattivato.

Nella scheda non c'è il modulo di rimborso: la scheda indica il motivo: il pagamento è rimborsato interamente, il tuo gruppo utenti non ha il permesso di modificare l'estensione, oppure manca la chiave segreta della modalità di pagamento.

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

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Payments e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Culqi Payment. La chiave di licenza e lo stato della licenza di questa estensione vengono sempre rimossi. OpenCart rimuove sempre le proprie impostazioni dell'estensione: Enable/Disable, Sort Order, Geo Zone, Total e gli stati degli ordini della sezione Orders, che tornano ai valori predefiniti in caso di reinstallazione. Se Delete data on uninstall è attivo, vengono rimosse anche le altre impostazioni del gateway (titolo, descrizione, modalità test, chiavi, Yape, registrazione) e il registro. Se è disattivo, vengono conservate per una reinstallazione successiva. Gli addebiti e i rimborsi di Culqi vengono sempre mantenuti, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento.

Su OpenCart 4, per rimuovere anche i file dell'estensione, vai su Extensions > Installer dopo la disinstallazione e clicca su Uninstall (il pulsante arancione −) accanto a VibeFox Culqi Payment nell'elenco delle estensioni installate, poi su Delete (il pulsante rosso con il cestino) per rimuovere il pacchetto caricato.

Culqi è un marchio registrato del rispettivo proprietario. Questa estensione non è affiliata né approvata da Culqi.