VibeFox Khipu for OpenCart — Guida

Requisiti

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

PHP: 8.0 o successivo.

Valuta: peso cileno (CLP), peso argentino (ARS) o sol peruviano (PEN). La valuta deve esistere in System > Localisation > Currencies. Khipu viene offerto solo mentre il cliente paga in una di queste valute; per le altre valute il metodo di pagamento viene nascosto al checkout.

Account Khipu: ti servono il Receiver ID ("Id de cobrador"), la API key e la secret key del tuo account di incasso Khipu. Li trovi nel tuo account Khipu, nel profilo commerciante (khipu.com/merchant/profile). Tutti e tre sono obbligatori: senza di essi Khipu non viene offerto al checkout, e senza la secret key nessun pagamento può essere confermato. Non c'è nulla da configurare nell'account Khipu.

Negozio raggiungibile: Khipu conferma i pagamenti chiamando il tuo negozio, quindi l'URL di notifica deve essere raggiungibile da internet, senza protezione con password né firewall che blocchi Khipu. La modalità manutenzione del negozio non lo blocca.

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

Installazione

L'archivio da scaricare è 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_khipu_gateway-oc3-(version).ocmod.zip e il pacchetto per OpenCart 4 wcp_khipu_gateway.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. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_khipu_gateway-oc3-(version).ocmod.zip. L'estensione non ha modifiche OCMOD, quindi Extensions > Modifications non deve essere aggiornato. 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 Khipu Gateway 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 License key).

4. Inserisci il Receiver ID, la API key e la Secret key del tuo account di incasso Khipu (vedi Configuration).

5. Attiva Enable / Disable e clicca su Save. Per provare prima, usa le chiavi di un account sviluppatore Khipu, poi sostituiscile con le chiavi del tuo account di produzione.

OpenCart 4

1. Nell'area di amministrazione vai su Extensions > Installer, clicca su Upload e scegli il file wcp_khipu_gateway.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 ad esso.

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

4. Inserisci la chiave di licenza e le chiavi Khipu come nei passaggi 3–5 per OpenCart 3. La pagina delle impostazioni e i suoi campi sono uguali in entrambe le versioni. Cambia solo l'URL di notifica (vedi Notifiche di pagamento).

Una nuova installazione parte con il metodo di pagamento disattivato.

Configurazione

Tutte le impostazioni si trovano nella pagina dell'estensione: Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit. Le sezioni sono elencate a sinistra; il pulsante Save sotto l'elenco salva l'intera pagina. Sopra le impostazioni la pagina ti avvisa quando mancano il Receiver ID, la API key o la secret key (in quel caso Khipu non viene offerto al checkout) e quando la valuta predefinita del negozio non è supportata da Khipu (Khipu viene allora offerto solo mentre il cliente paga in CLP, ARS o PEN). Senza il permesso di modificare l'estensione, la pagina mostra le impostazioni ma non può salvarle.

Al salvataggio, Title non deve essere vuoto né superare i 128 caratteri, Sort Order deve essere un numero intero, Total deve essere un numero pari o superiore a 0, e la zona geografica e gli stati ordine devono esistere. Altrimenti non viene salvato nulla e la pagina indica il campo. Le chiavi mancanti non bloccano il salvataggio.

Khipu

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

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Khipu. Obbligatorio, da 1 a 128 caratteri.

Description: il testo mostrato al cliente nel passaggio Confirm Order, sopra il pulsante di conferma. Predefinito: Paga con bonifico bancario tramite Khipu.

Sort Order: la posizione di Khipu tra i metodi di pagamento al checkout. Lascialo vuoto oppure inserisci un numero intero.

Geo Zone: offri Khipu 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 venga offerto Khipu. Lascialo vuoto per offrire Khipu per qualsiasi totale.

Account Khipu

Copia il Receiver ID, la API key e la secret key dal tuo account di incasso Khipu (la sezione rimanda a khipu.com/merchant/profile). Khipu non ha un server sandbox separato e l'estensione non ha un interruttore di modalità test. Per provare, usa le chiavi di un account di incasso sviluppatore ("desarrollo"): paga tramite la banca di prova DemoBank e non viene spostato denaro reale. Passa alle chiavi del tuo account di incasso di produzione quando vai in produzione.

Receiver ID: il tuo ID del ricevente ("cobrador") Khipu. I pagamenti di altri account Khipu vengono rifiutati.

API key: serve per creare i pagamenti e per verificare ogni pagamento con Khipu.

Secret key: serve per verificare la firma (HMAC-SHA256) delle notifiche di pagamento Khipu. Senza di essa non si può confermare alcun pagamento.

Le chiavi 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 modificarlo. Per rimuovere una chiave salvata, spunta Clear the saved value sotto il campo e clicca su Save.

Notifiche di pagamento

Notification URL: Khipu conferma i pagamenti chiamando l'URL mostrato qui. Su OpenCart 3 ha questo formato: https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook, su OpenCart 4 così: https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook. È costruito dall'indirizzo della vetrina della tua installazione di OpenCart. L'URL viene inviato automaticamente con ogni pagamento, quindi non c'è nulla da configurare nel tuo account Khipu, ma l'URL deve essere raggiungibile da internet.

Ogni notifica deve avere una firma valida creata con la tua Secret key. Le notifiche senza firma valida vengono rifiutate. L'estensione non si fida mai del contenuto della notifica: chiede a Khipu lo stato del pagamento e agisce in base a ciò che Khipu comunica:

Status after payment: lo stato che riceve l'ordine quando Khipu conferma il pagamento. Lo stato viene impostato subito, con un unico cambio di stato.

OpenCart crea l'ordine nel passaggio Confirm Order senza stato (un ordine mancante). Riceve uno stato solo dopo che Khipu ha confermato il pagamento. Ogni campo sotto elenca i tuoi stati ordine di OpenCart.

Paid Order Status: lo stato dopo un pagamento confermato quando Status after payment è Processing. Predefinito: In lavorazione.

Complete Order Status: lo stato dopo un pagamento confermato quando Status after payment è Completed. Predefinito: Completato.

On Hold (Review) Status: i pagamenti il cui importo o valuta non corrispondono all'ordine, oppure che arrivano dopo l'annullamento dell'ordine, ricevono questo stato e una nota che ne spiega il motivo. Predefinito: In attesa, perché OpenCart non ha lo stato "On hold". Puoi creare un tuo stato in System > Localisation > Order Statuses e selezionarlo qui.

Avanzate

Debug log: registra le chiamate API e le notifiche in wc_khp_debug.log.php, nella cartella dei log di OpenCart (storage/logs). Il file non può essere aperto dal web e, al raggiungimento dei 5 MB, viene spostato in wc_khp_debug.old.log.php. Gli errori vengono sempre registrati, anche con l'interruttore disattivato. Chiavi e dati del pagatore non vengono mai scritti. Predefinito: disattivo.

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

Delete data on uninstall: se attivo, disinstallando l'estensione vengono rimosse le impostazioni del gateway e il log. I dati degli ordini (gli ID dei pagamenti Khipu degli ordini) vengono sempre conservati. Predefinito: disattivo.

Importazione / Esportazione

Export: Download JSON salva le impostazioni in un file JSON. La API key e la secret key non vengono esportate.

Import: incolla un JSON esportato in precedenza e clicca su Import per ripristinare le impostazioni. La API key e la secret key salvate vengono mantenute.

Checkout

Nel passaggio Payment Method il cliente sceglie il metodo di pagamento (per impostazione predefinita Khipu). Nel passaggio Confirm Order il cliente vede la tua descrizione sopra il pulsante di conferma. OpenCart crea l'ordine in questo passaggio, ancora senza stato. Quando il cliente clicca su Confirm Order, l'estensione crea un pagamento Khipu per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina di pagamento Khipu. Su Khipu il pagamento appare come Order # con il numero dell'ordine e il nome del negozio, insieme all'elenco dei prodotti. L'e-mail del cliente viene passata a Khipu quando è valida. Sulla pagina di Khipu il cliente paga con bonifico bancario dalla propria banca.

Su OpenCart 4 il cliente sceglie il metodo di pagamento con il pulsante Choose nel blocco del metodo di pagamento, nella finestra Payment method options, e clicca su Confirm Order in fondo alla pagina di checkout.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Khipu lo conferma: tramite la notifica firmata, oppure con una richiesta di stato a Khipu quando il cliente torna. Il ritorno in sé non segna mai nulla come pagato. L'ordine riceve poi il suo stato nel modo standard di OpenCart, con le consuete e-mail d'ordine e l'aggiornamento del magazzino, e il cliente vede la pagina di conferma ordine di OpenCart. Se la banca sta ancora verificando il bonifico o Khipu non è raggiungibile, una pagina Payment confirmation mostra Khipu is confirming your bank transfer. Your order will be confirmed automatically as soon as Khipu confirms the payment, and you will receive an e-mail. con i pulsanti Check again e Back to checkout. Se l'ultimo pagamento Khipu dell'ordine non può essere abbinato ad esso (per esempio perché appartiene a un altro Receiver ID), il cliente torna al checkout con il messaggio We could not match this payment to an order. If you paid, please contact us.

Se il cliente annulla nella pagina di Khipu, o il pagamento non è stato completato, il cliente torna al checkout con il messaggio The Khipu payment was not completed. You can try again or choose another payment method. Il carrello viene conservato. Su OpenCart 4 questi messaggi vengono mostrati sopra la pagina del checkout. Ogni nuovo tentativo (OpenCart 3 crea un nuovo ordine ogni volta che viene mostrato il passaggio Confirm Order; OpenCart 4 aggiorna l'ordine del checkout e lo paga con un nuovo pagamento Khipu) elimina il precedente pagamento Khipu non pagato dell'ordine o del carrello, così il vecchio link non può più essere pagato. Se Khipu ha già ricevuto il pagamento precedente, questo viene applicato e il cliente va alla pagina di successo, senza alcun nuovo pagamento. Se il bonifico precedente è ancora in verifica presso la banca, il cliente vede Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again. Se il pagamento precedente è in revisione, al cliente viene chiesto di contattare il negozio prima di pagare di nuovo. Una modifica del carrello, compresa una nuova quantità, conta come un nuovo carrello che richiede un proprio pagamento.

Su OpenCart 4 l'ordine resta nel checkout fino a quando non viene mostrata la pagina di successo. Se nel frattempo l'ordine è stato chiuso senza pagamento (per esempio l'hai annullato), il cliente torna al checkout con il messaggio Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Se l'ordine è già stato inserito e il carrello è cambiato da allora, il messaggio è Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. In entrambi i casi, il successivo clic su Confirm Order paga un nuovo ordine del carrello.

Se Khipu non riesce a creare il pagamento, il cliente resta al passaggio Confirm Order con un breve messaggio sopra il pulsante, per esempio Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. oppure Khipu is temporarily unavailable. Please try again in a few minutes. I dettagli vengono scritti nel log.

La notifica funziona anche mentre il negozio è in manutenzione: OpenCart 3 lascia passare le richieste delle estensioni di pagamento, e su OpenCart 4 l'estensione aggiunge un'azione di avvio (startup action) che lascia passare la notifica e il ritorno del cliente.

L'estensione accetta solo pagamenti una tantum con bonifico bancario. I rimborsi non vengono inviati a Khipu da OpenCart, e non sono previsti abbonamenti, metodi di pagamento salvati o pre-autorizzazioni. I pagamenti non completati non sono legati a una prenotazione di magazzino.

Ordini

Stati degli ordini

Nessuno stato (ordine mancante): il cliente è stato inviato a Khipu e non ha pagato, oppure Khipu non ha ancora confermato il bonifico. In Sales > Orders questi ordini vengono mostrati solo con il filtro Order Status impostato su Missing Orders.

Paid Order Status o Complete Order Status (predefinito In lavorazione o Completato): Khipu ha confermato il pagamento. Lo stato segue Status after payment. Una nota mostra Khipu payment verified. Payment ID: con l'ID del pagamento e l'importo.

On Hold (Review) Status (predefinito In attesa): Khipu ha confermato un pagamento il cui importo o valuta non corrisponde all'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato o rifiutato. Una nota lo spiega. Controlla il pagamento nel tuo account Khipu, poi completa l'ordine o rimborsa il cliente. Se più tardi arriva per lo stesso ordine un pagamento dell'importo giusto, l'ordine passa allo stato pagato e il cliente viene avvisato via e-mail. Se il pagamento arriva dopo che l'ordine è stato portato a un altro stato di lavorazione, lo stato non cambia e viene aggiunta solo una nota.

Se arriva un pagamento per un ordine già pagato, o per un altro ordine di un carrello già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsarlo al cliente se si tratta di un secondo pagamento. Se Khipu segnala come stornato un pagamento già pagato, l'ordine riceve una nota e il suo stato non cambia.

Le note sono voci della History dell'ordine che il cliente non vede. Iniziano con la parola Khipu.

Scheda VibeFox Khipu Gateway

In Sales > Orders apri un ordine pagato con Khipu. In fondo alla pagina dell'ordine, accanto a History e Additional, la scheda VibeFox Khipu Gateway mostra i tentativi di pagamento Khipu dell'ordine (data, importo, ID del pagamento Khipu, stato e risultato su Khipu), un avviso Manual review finché l'ordine è nello stato di revisione, e le Khipu notes dell'ordine. La scheda è di sola lettura e viene mostrata agli utenti che hanno accesso all'estensione.

Rimborsi

I rimborsi non vengono inviati a Khipu da OpenCart, perché Khipu non offre alcun rimborso tramite la sua API. La scheda lo indica. Rimborsa il cliente dal tuo account Khipu o con bonifico bancario, poi cambia manualmente lo stato dell'ordine in OpenCart.

Chiave di licenza

L'estensione funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco di licenza License — VibeFox Khipu Gateway è il primo blocco di Extensions > Extensions > Payments > VibeFox Khipu Gateway > 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 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: opencart-payment-khipu 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 cambiare la chiave. I testi del blocco seguono la lingua dell'amministrazione (sono incluse le versioni inglese e russa).

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 aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto 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 posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Khipu 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 continua a vedere il metodo di pagamento nel negozio, contrassegnato come (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 il login dell'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 continuano a essere confermati.

Quando una licenza scade, l'estensione continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato 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 a settimana. Non serve alcun cron job. Disinstallare l'estensione rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Khipu non compare al checkout: verifica che la licenza sia attiva, che Enable / Disable sia attivo e che siano inseriti Receiver ID, API key e Secret key. Il cliente deve pagare in CLP, ARS o PEN. La pagina delle impostazioni mostra un avviso quando manca qualcosa. Controlla 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: Khipu conferma un bonifico dopo che la banca lo ha verificato. L'ordine riceve il suo stato quando arriva la notifica di Khipu o quando il cliente clicca su Check again. Verifica che il tuo negozio sia raggiungibile da internet all'URL mostrato in Notification URL (nessuna protezione con password né firewall che blocchi Khipu), e controlla il campo Log nella pagina dell'estensione.

La notifica risponde Secret key not configured: la Secret key è vuota. Inseriscila. Khipu invia di nuovo la notifica.

La notifica risponde Invalid signature, Missing signature o Malformed signature: la Secret key non appartiene all'account di incasso di cui usi le chiavi, oppure la richiesta non proveniva da Khipu.

La notifica risponde Order not found, Payment not found for this account o Payment does not belong to this order: il pagamento è stato fatto a un altro Receiver ID, con altre chiavi o per un altro ordine. Controlla il Receiver ID e le chiavi.

La notifica risponde Payment not final yet o Verification unavailable: il bonifico è ancora in verifica, oppure Khipu non è stato raggiungibile. Khipu invia di nuovo la notifica.

La notifica risponde Busy, retry later o Order could not be updated, retry later: l'ordine era in conferma da un'altra richiesta nello stesso momento, oppure non è stato possibile impostare lo stato dell'ordine. Khipu invia di nuovo la notifica. Il motivo è nel log.

L'ordine è nello stato di revisione dopo il pagamento: leggi le note nella scheda VibeFox Khipu Gateway. L'importo o la valuta non corrispondevano all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine.

Il cliente vede "Khipu payments are not available right now": la API key manca o è errata. Controlla le chiavi nel tuo account Khipu.

Per gli sviluppatori: l'estensione attiva gli eventi OpenCart wc_khp_supported_currencies (per aggiungere una valuta accettata dal tuo account Khipu, per esempio EUR per Khipu Spagna), wc_khp_currency_decimals e wc_khp_payment_data.

Disinstallazione

Vai su Extensions > Extensions, scegli il tipo Payments e clicca su Uninstall (il pulsante rosso −) accanto a VibeFox Khipu Gateway. 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 i tre stati ordine, che tornano ai valori predefiniti alla reinstallazione. Su OpenCart 4 vengono rimossi anche il suo evento e la sua azione di avvio (startup action), che lascia passare la notifica e il ritorno del cliente in modalità manutenzione. Se Delete data on uninstall è attivo, vengono rimosse le altre impostazioni del gateway (titolo, descrizione, Receiver ID, chiavi, stato dopo il pagamento, debug log) e il log. Se è disattivo, vengono conservate per una futura reinstallazione. I tentativi di pagamento Khipu vengono sempre conservati, quindi le notifiche tardive relative a ordini pagati in precedenza continuano a essere gestite dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento.

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

Khipu è un marchio di proprietà dei rispettivi titolari. Questa estensione non è affiliata a Khipu né approvata da Khipu.