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

Valuta del negozio: sol peruviano (PEN) o dollaro statunitense (USD). Culqi non accetta altre valute e il metodo di pagamento viene mostrato solo per i carrelli 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: 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 Culqi Payment nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua 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. Incolla le chiavi di integrazione e, per i pagamenti reali, le chiavi di produzione (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Mantieni Test Mode attivo mentre fai i test, poi disattivalo per accettare pagamenti reali.

6. Assicurati che PEN o USD sia una valuta attiva del tuo negozio.

All'installazione il modulo crea lo stato dell'ordine Culqi payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Culqi Payment > Configure. Ogni sezione ha il suo pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode is active: the integration keys are used and no real money is charged. mentre la modalità test è attiva. La pagina avvisa quando il gateway è attivo ma mancano le chiavi della modalità corrente, e quando nessuna valuta del negozio è supportata da Culqi. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Se la valuta predefinita non è PEN o USD, la pagina segnala che Culqi viene offerto solo per i carrelli nelle valute supportate.

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.

Description: il testo mostrato sotto il metodo di pagamento al 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) da integ-panel.culqi.com, quelle di produzione da 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 prefisso errato non viene salvata: la pagina mostra un errore, per esempio Live Secret Key must start with sk_live_ — the previous value was kept., e gli altri campi vengono salvati.

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. sotto il metodo di pagamento.

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 mai più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secret keys: spunta Test Secret Key o Live Secret Key e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Metodi di pagamento

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

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

Avanzate

Debug log: registra le richieste API e i passaggi del pagamento in logs/culqi_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori, inclusi i rifiuti delle carte con il loro codice, vengono sempre registrati. Chiavi, dati della carta e dati del cliente 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: quando attivo, la disinstallazione del modulo rimuove le impostazioni del gateway, i record degli addebiti e dei rimborsi Culqi del modulo e il registro. Lo stato dell'ordine e i dati Culqi sugli ordini (pagamenti, note) restano sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit/Debit Card or Yape (Culqi)) e fa clic sul pulsante per confermare l'ordine. Il popup di Culqi Checkout si apre nella stessa pagina con il nome del tuo negozio, il totale del carrello e la valuta. Lì il cliente inserisce i dati della carta o paga con Yape. Gli script di Culqi vengono caricati solo nella pagina del checkout.

Culqi trasforma i dati di pagamento in un token monouso, e il token viene inviato al tuo negozio. Il tuo server crea l'addebito con la Culqi Charges API per il totale del carrello nella valuta del carrello, catturato immediatamente. L'addebito compare in CulqiPanel come Cart e con il numero del carrello, insieme all'e-mail del cliente. Prima di questo punto non esiste alcun ordine. L'ordine viene segnato come pagato solo dopo la conferma di Culqi: l'ordine viene creato quando Culqi risponde con un addebito riuscito, e il cliente vede la normale pagina di conferma dell'ordine.

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ò confermare di nuovo l'ordine. Il carrello viene conservato in tutti questi casi. I tentativi non riusciti vengono scritti nel registro del modulo, perché non esiste ancora un ordine.

Un carrello non viene mai addebitato due volte. Se il cliente invia di nuovo mentre è in corso un pagamento dello stesso carrello, 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 l'ordine non può essere creato, 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 conservato e il tentativo successivo crea l'ordine a partire da esso, senza un nuovo addebito.

Il modulo accetta solo pagamenti singoli con carta e Yape, catturati 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

No order yet: la carta è stata rifiutata, il cliente ha chiuso la finestra di Culqi o Culqi non ha risposto. Esiste solo il carrello. Il registro del modulo contiene i dettagli.

Payment accepted: l'addebito è stato confermato e corrisponde al carrello. Il pagamento viene registrato con l'ID dell'addebito Culqi (chr_...) come ID transazione, e una nota indica la modalità (test o live) e se è stato usato 3-D Secure.

Culqi payment on hold: Culqi ha segnalato un addebito il cui importo o la cui valuta non corrisponde al carrello, oppure un pagamento autorizzato ma non catturato. La nota lo spiega e mostra l'ID dell'addebito. Un addebito catturato nella valuta del carrello viene registrato come pagamento per l'importo effettivamente addebitato. Controlla l'addebito in CulqiPanel, poi evadi l'ordine o rimborsa il pagamento.

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

Se arriva un secondo addebito per un carrello che ha già un ordine, l'ordine non viene modificato. Una nota ti chiede di controllare l'addebito in CulqiPanel e di rimborsarlo se necessario.

Blocco Culqi payment

La pagina dell'ordine mostra un blocco Culqi payment con l'ID dell'addebito, l'importo addebitato (con 3-D Secure se usato), un badge Test per i pagamenti di test, un suggerimento di verifica per gli ordini in sospeso, gli importi pagati e rimborsati e la cronologia dei rimborsi.

Rimborsi

Nel blocco Culqi payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic 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 gli ordini; non serve l'accesso ai moduli. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Culqi, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. 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, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note dell'ordine, con l'ID del rimborso Culqi, l'importo e il tuo motivo. 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 Culqi. I rimborsi effettuati in CulqiPanel non vengono sincronizzati con PrestaShop. Aggiorna l'ordine manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Culqi Payment è il primo blocco della pagina Modules > Module Manager > VibeFox Culqi Payment > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic 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 controllare 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-culqi e il collegamento 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, per esempio Key not found, This key belongs to another product, Domain limit reached o License expired on seguito da una data. Dopo un cambio dell'indirizzo del negozio, o dopo aver liberato un posto 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Liberalo 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. La vetrina di PrestaShop non sa che sei connesso 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 ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Culqi non appare al checkout: verifica 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 carrello sia PEN o USD. La pagina delle impostazioni mostra un avviso quando mancano delle chiavi. 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 nessun ordine è stato creato: il modulo non usa webhook. L'addebito viene confermato solo dalla risposta di Culqi al tuo server. Se Culqi non ha risposto in tempo, il registro del modulo riporta Culqi did not confirm the charge con il numero del carrello. Cerca l'addebito con questo cart_id in CulqiPanel. Se il cliente ha visto il messaggio che l'ordine non è stato completato, il tentativo di pagamento successivo dello stesso carrello crea l'ordine senza addebitare di nuovo.

L'ordine è Culqi payment on hold dopo il pagamento: leggi la nota nell'ordine. L'importo o la valuta addebitati erano diversi dal carrello, oppure il pagamento non è stato catturato. Controlla l'addebito in CulqiPanel (il suo ID è nella nota), poi evadi l'ordine o rimborsa il pagamento.

La chiave non viene salvata: l'errore dice 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 dalla 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. Verifica che gli script di js.culqi.com e 3ds.culqi.com non siano bloccati nella pagina del checkout, per esempio da un modulo di cache o ottimizzazione.

Il cliente vede Security check failed. Please reload the page and try again.: la pagina del checkout è rimasta aperta troppo a lungo o in un'altra sessione. Ricaricare la pagina risolve il problema.

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

Una carta è stata rifiutata e vuoi il motivo: controlla il campo Log nella pagina del modulo. I rifiuti vengono registrati con il codice di rifiuto di Culqi anche quando Debug log è disattivato.

Il rimborso fallisce con 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.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Culqi Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, vengono rimosse le impostazioni del gateway, i record degli addebiti e dei rimborsi Culqi del modulo e il registro. Gli ordini pagati in precedenza non possono più essere rimborsati dalla pagina dell'ordine. Se è disattivo, tutto viene conservato per una futura reinstallazione. Lo stato dell'ordine Culqi payment on hold viene sempre conservato. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID delle transazioni.

Culqi è un marchio di proprietà del rispettivo titolare. Questo modulo non è affiliato a Culqi né approvato da Culqi.