VibeFox Khipu for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o versione successiva. Il modulo non si installa su versioni di PHP più vecchie.

Valuta: peso cileno (CLP), peso argentino (ARS) o sol peruviano (PEN). Per i carrelli in altre valute il metodo di pagamento viene nascosto al checkout.

Conto Khipu: ti servono il Receiver ID («Id de cobrador»), la API key e la Secret key del tuo conto di incasso Khipu. Li trovi nel tuo account Khipu, nel profilo commerciante (khipu.com/merchant/profile). Tutti e tre sono obbligatori: senza la Secret key non è possibile confermare alcun pagamento. Nel conto Khipu non c'è nulla da configurare.

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 dominio.

Installazione

1. Nel back office vai su Modules > Module Manager e clicca su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, clicca su Configure, oppure trova VibeFox Khipu Gateway più tardi nell'elenco dei moduli e clicca su Configure.

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco licenza in cima alla pagina Configure e fai clic su Activate (vedi Chiave di licenza).

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

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

All'installazione il modulo crea lo stato dell'ordine Khipu payment on hold. PrestaShop attiva di default il 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 Khipu Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa quando mancano Receiver ID, API key o Secret key (in tal caso Khipu non viene proposto al checkout) e quando la valuta predefinita del negozio non è supportata da Khipu.

Khipu

Enable / Disable: Enable Khipu payments 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: Khipu. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay by bank transfer with Khipu.

Conto Khipu

Copia il Receiver ID, la API key e la Secret key dal tuo conto di incasso Khipu (khipu.com/merchant/profile). Khipu non ha un server sandbox separato e il modulo non ha un interruttore di modalità test. Per fare prove, usa le chiavi di un conto di incasso per sviluppatori («desarrollo»): paga con la banca di prova DemoBank e non viene spostato denaro reale. Passa alle chiavi del tuo conto di incasso di produzione quando vai online.

Receiver ID: il tuo ID di incasso («cobrador») Khipu. I pagamenti di altri conti 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 è possibile confermare alcun pagamento.

Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.

Clear saved secrets: spunta API key o Secret key e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notifiche di pagamento

Notification URL: Khipu conferma i pagamenti chiamando l'URL mostrato qui. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_khipu_gateway/webhook, eventualmente con un codice lingua. L'URL viene inviato automaticamente con ogni pagamento, quindi non c'è nulla da configurare nel tuo conto Khipu, ma l'URL deve essere raggiungibile da internet.

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

Status after payment: lo stato dell'ordine non appena Khipu conferma il pagamento. Lo stato viene impostato subito, con un solo cambio di stato.

Avanzate

Debug log: registra le chiamate API e le notifiche in logs/wc_khp_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche con l'interruttore disattivato. Chiavi e dati del pagatore non vengono mai scritti. Predefinito: disattivato.

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

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

Checkout

Al checkout il cliente sceglie il metodo di pagamento (di default Khipu) con la sua descrizione e conferma l'ordine. Il modulo crea un pagamento Khipu per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento Khipu. Su Khipu il pagamento compare come Order # con il numero del carrello e il nome del negozio, insieme all'elenco dei prodotti. L'e-mail del cliente viene passata a Khipu quando è valida. Sulla pagina Khipu il cliente paga tramite bonifico bancario dalla propria banca. A questo punto l'ordine non esiste ancora.

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Khipu: tramite la notifica firmata, oppure tramite una richiesta di stato a Khipu quando il cliente torna. Il ritorno in sé non segna mai nulla come pagato. Una volta creato l'ordine, il cliente vede la pagina standard di conferma dell'ordine. Se la banca sta ancora verificando il bonifico o Khipu non è raggiungibile, compare una pagina Payment confirmation con il testo Khipu is confirming your bank transfer. Your order will be created 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 del carrello non può essere abbinato ad esso (per esempio, 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 lascia la pagina Khipu senza pagare, o il pagamento non è stato completato, 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. Un nuovo tentativo elimina il precedente pagamento Khipu non pagato, così il vecchio link non può più essere pagato. Se Khipu ha già ricevuto il pagamento precedente, l'ordine viene creato e non viene effettuato alcun nuovo pagamento. Se il bonifico precedente è ancora in verifica, 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 Khipu non riesce a creare il pagamento, il cliente resta al checkout con un breve messaggio, 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 modalità manutenzione e non viene bloccata dalla restrizione per paese del tuo negozio.

Il modulo gestisce solo pagamenti singoli tramite bonifico bancario. I rimborsi non vengono inviati a Khipu da PrestaShop, e il modulo non gestisce abbonamenti, metodi di pagamento salvati o preautorizzazioni. I pagamenti non completati non sono collegati a una prenotazione di magazzino.

Ordini

Stati dell'ordine

No order yet: il cliente è stato inviato a Khipu e non ha pagato, oppure Khipu non ha ancora confermato il bonifico. Esiste solo il carrello.

Payment accepted or Delivered: Khipu ha confermato il pagamento. Lo stato segue Status after payment. Il pagamento viene registrato con l'ID del pagamento Khipu come ID transazione, e una nota mostra Khipu payment verified. Payment ID: con l'ID del pagamento e l'importo.

Khipu payment on hold: Khipu ha confermato un pagamento il cui importo o la cui valuta non corrisponde all'ordine (per esempio, il carrello è stato modificato dopo l'avvio del pagamento), oppure il pagamento è arrivato dopo l'annullamento dell'ordine. L'importo effettivamente ricevuto viene registrato sull'ordine (non quando la valuta è diversa), e una nota lo spiega. Controlla il pagamento nel tuo conto Khipu, poi completa l'ordine o rimborsa il cliente. Se per lo stesso carrello arriva in seguito un pagamento dell'importo giusto, l'ordine passa allo stato pagato.

Se arriva un pagamento per un ordine già pagato o chiuso dopo il pagamento, l'ordine non viene modificato. Una nota ti chiede di rimborsare il 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.

Blocco pagamento Khipu

La pagina dell'ordine mostra un blocco Khipu payment con i tentativi di pagamento Khipu del carrello dell'ordine (data, importo, ID del pagamento Khipu, stato e risultato Khipu), un avviso Manual review finché l'ordine è in Khipu payment on hold, e le Khipu notes dell'ordine. Il blocco è di sola lettura.

Rimborsi

I rimborsi non vengono inviati a Khipu da PrestaShop, perché Khipu non offre rimborsi tramite la sua API. Rimborsa il cliente dal tuo conto Khipu o tramite bonifico bancario, poi registra manualmente il rimborso in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Khipu Gateway è il primo blocco di Modules > Module Manager > VibeFox Khipu Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopo, 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. Più in basso ci sono la riga Product: presta-payment-khipu e il link 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 modificare 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 indica 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 uno slot di 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 multinegozio. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot 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. Lo storefront di PrestaShop non sa che hai effettuato l'accesso 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.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo 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

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

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 al conto di incasso di cui usi le chiavi, oppure la richiesta non proviene da Khipu.

La notifica risponde Order not found o Payment does not belong to this order: il pagamento è stato effettuato verso un altro Receiver ID o per un altro carrello. Controlla il Receiver ID.

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 created, retry later: l'ordine veniva confermato in quel momento da un'altra richiesta, oppure l'ordine non è stato creato (per esempio, il modulo è disattivato). Khipu invia di nuovo la notifica. Il motivo è nel log.

L'ordine è in Khipu payment on hold: leggi le note nel blocco Khipu payment. 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 conto Khipu.

Se il tuo conto Khipu accetta un'altra valuta, per esempio EUR per Khipu Spagna, gli sviluppatori possono aggiungerla con l'hook actionWcpKhipuSupportedCurrencies.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Khipu Gateway 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 e il log. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I tentativi di pagamento Khipu e lo stato dell'ordine Khipu payment on hold vengono sempre conservati. Gli ordini esistenti mantengono le note di pagamento e gli ID delle transazioni.

Khipu è un marchio registrato del rispettivo titolare. Questo modulo non è affiliato né approvato da Khipu.