VibeFox Khipu for WooCommerce — Guida
Requisiti
WordPress: 6.0 o versione successiva.
WooCommerce: 8.0 o versione successiva, installato e attivo. Senza WooCommerce il plugin rifiuta di attivarsi.
PHP: 8.0 o versione successiva.
Valuta del negozio: peso cileno (CLP), peso argentino (ARS) o sol peruviano (PEN). Il metodo di pagamento è nascosto al checkout quando il negozio, o l'ordine nella pagina Pay for order, usa un'altra valuta.
Account Khipu: ti servono il Receiver ID ("Id de cobrador"), la chiave API e la chiave segreta ("llave") del tuo account di incasso Khipu. Li trovi nel tuo account Khipu, nel profilo esercente (khipu.com/merchant/profile). Tutti e tre sono obbligatori: senza la chiave segreta nessun pagamento può essere confermato.
Sito raggiungibile: Khipu conferma i pagamenti chiamando il tuo negozio, quindi il sito deve essere raggiungibile da internet (niente modalità manutenzione, autenticazione di base o firewall che bloccano Khipu).
Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo dominio.
Installazione
1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca Install Now. Puoi anche caricare via FTP la cartella wcp_khipu_gateway in /wp-content/plugins/.
2. Clicca Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Khipu > Manage, oppure clicca Settings sotto il nome del plugin nella pagina Plugins.
4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca Activate.
5. Inserisci il Receiver ID, la API key e la Secret key del tuo account di incasso Khipu (vedi Configurazione).
6. Attiva Enable / Disable e salva. Per fare prima una prova, usa le chiavi di un account sviluppatore Khipu, poi sostituiscile con le chiavi del tuo account di produzione.
Configurazione
Tutte le impostazioni sono su un'unica pagina: WooCommerce > Settings > Payments > Khipu. Sopra i campi la pagina ti avvisa quando mancano il Receiver ID, la chiave API o la chiave segreta (in quel caso Khipu non viene proposto al checkout) e quando la valuta del negozio non è supportata. Nell'elenco dei metodi di pagamento Khipu è contrassegnato come da configurare finché non sono inserite tutte e tre le chiavi.
Generale
Enable / Disable: Enable Khipu payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Khipu.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay by bank transfer with Khipu.
Account Khipu
Copia Receiver ID, chiave API e chiave segreta dal tuo account di incasso Khipu (khipu.com/merchant/profile). Khipu non ha un server sandbox separato e il plugin non ha un interruttore per la modalità di test. Per provare, usa le chiavi di un account di incasso sviluppatore ("desarrollo"): si paga con la banca di test DemoBank e non viene movimentato denaro reale. Quando vai in produzione, passa alle chiavi del tuo account di incasso di produzione.
Receiver ID: il tuo ID di incasso ("cobrador") Khipu. I pagamenti di altri account Khipu vengono rifiutati.
API key: serve a creare i pagamenti e a verificare ogni pagamento con Khipu.
Secret key: serve a verificare la firma (HMAC-SHA256) delle notifiche di pagamento di Khipu. Senza di essa nessun pagamento può essere confermato.
Notifiche di pagamento
Khipu conferma i pagamenti chiamando l'URL di notifica mostrato in questa sezione delle impostazioni. Ha un aspetto simile a https://your-site/wc-api/webhook_wc_khipu/. 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 realizzata con la tua Secret key. Le notifiche senza una firma valida vengono rifiutate. Poi il plugin chiede a Khipu lo stato del pagamento e agisce in base a ciò che Khipu riporta:
Status after payment: lo stato dell'ordine quando Khipu conferma il pagamento. Lo stato viene impostato subito, con un solo cambio di stato e un solo invio di e-mail.
Avanzate
Debug log: Log API calls and notifications in WooCommerce > Status > Logs, sorgente wcp_khipu_gateway. Gli errori vengono sempre registrati. Le chiavi e i dati del pagatore non vengono mai scritti. Predefinito: disattivato.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. I dati degli ordini (gli ID di pagamento Khipu negli ordini) vengono sempre conservati. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Khipu) ed effettua l'ordine. Il plugin crea un pagamento Khipu per il totale dell'ordine nella valuta dell'ordine, con il numero d'ordine, il nome del negozio e gli articoli ordinati, e porta il cliente alla pagina di pagamento Khipu. L'e-mail di fatturazione viene trasmessa a Khipu quando è valida. Nella pagina Khipu il cliente paga con bonifico dalla propria banca e sceglie lì tra i tipi di bonifico offerti da Khipu.
Dopo aver pagato, il cliente torna alla pagina di conferma dell'ordine del tuo negozio. L'ordine viene segnato come pagato solo dopo che Khipu conferma il bonifico: tramite la notifica firmata, oppure tramite una richiesta di stato a Khipu quando il cliente apre la pagina di conferma dell'ordine. Il ritorno alla pagina non segna mai un ordine come pagato. Finché il bonifico non è confermato, la pagina mostra Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.
Se il cliente lascia la pagina Khipu senza pagare, arriva sulla pagina Pay for order con The Khipu payment was not completed. You can try again or choose another payment method. Un nuovo tentativo elimina il precedente pagamento Khipu non pagato, quindi il vecchio link non può più essere pagato. Se Khipu ha già ricevuto il pagamento precedente, l'ordine viene completato e non viene creato un 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.
Con la gestione delle scorte attiva, il pagamento Khipu scade insieme al tempo Hold stock (minutes) di WooCommerce, così il cliente non può pagare un ordine che è già stato annullato.
Se Khipu non riesce a creare il pagamento, il cliente vede 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.
Il metodo di pagamento funziona sul checkout classico, sul blocco Checkout e sulla pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).
Il plugin gestisce solo pagamenti una tantum tramite bonifico. I rimborsi da WooCommerce non sono supportati e non ci sono abbonamenti, metodi di pagamento salvati o preautorizzazioni.
Ordini
Stati dell'ordine
Pending payment: il cliente è stato inviato a Khipu e non ha ancora pagato, oppure Khipu non ha ancora confermato il bonifico. La nota dell'ordine mostra l'ID di pagamento Khipu.
Processing or Completed: Khipu ha confermato il pagamento. Lo stato segue Status after payment. La nota dell'ordine mostra l'ID di pagamento Khipu e l'ID transazione è l'ID di pagamento Khipu.
On hold: Khipu ha segnalato un pagamento il cui importo o la cui valuta non corrispondono all'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato (per esempio dopo il tempo di blocco delle scorte). La nota dell'ordine lo spiega. Controlla il pagamento nel tuo account Khipu e completa l'ordine o rimborsa il cliente.
Se arriva un pagamento per un ordine già pagato o chiuso dopo il pagamento, l'ordine non viene modificato. Una nota ti chiede di rimborsarlo al cliente se si tratta di un secondo pagamento.
Rimborsi
I rimborsi non vengono inviati a Khipu da WooCommerce. Rimborsa il cliente dal tuo account Khipu o tramite bonifico, poi registra il rimborso in WooCommerce manualmente.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Khipu. Incolla la chiave in License key e clicca 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 vibefox.net.
Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera lo slot del suo 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 comunque avviato, 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 con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati.
Quando una licenza scade, il plugin continua a funzionare, ma gli aggiornamenti e l'assistenza richiedono un rinnovo. Lo stato viene controllato di nuovo automaticamente in background.
Risoluzione dei problemi
Khipu non compare al checkout: controlla che la licenza sia attiva, che Enable / Disable sia attivo e che Receiver ID, API key e Secret key siano tutte inserite. La valuta del negozio deve essere CLP, ARS o PEN. La pagina delle impostazioni mostra un avviso quando manca qualcosa.
Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: Khipu conferma un bonifico dopo che la banca lo ha verificato. L'ordine viene aggiornato quando arriva la notifica di Khipu o quando il cliente apre la pagina di conferma dell'ordine. Controlla che il tuo sito sia raggiungibile da internet all'URL di notifica mostrato nelle impostazioni (niente modalità manutenzione, autenticazione di base o firewall che bloccano Khipu) e guarda in WooCommerce > Status > Logs, sorgente wcp_khipu_gateway.
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 è arrivata da Khipu.
La notifica risponde Payment does not belong to this order: il pagamento è stato fatto a un altro Receiver ID o per un altro ordine. Controlla il Receiver ID.
La notifica risponde Payment not final yet o Verification unavailable: il bonifico è ancora in verifica, oppure Khipu non è raggiungibile. Khipu invia di nuovo la notifica.
L'ordine è In sospeso: leggi la nota dell'ordine. L'importo o la valuta non corrispondevano all'ordine, oppure il pagamento è arrivato dopo che l'ordine era stato annullato.
Il cliente vede "Khipu payments are not available right now": la chiave API manca o è errata. Controlla le chiavi nel tuo account Khipu.
Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca Check now. Se l'indirizzo del sito è cambiato, clicca Check now per attivare la chiave sul nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato conosciuto.
Se il tuo account Khipu accetta un'altra valuta, per esempio EUR per Khipu Spagna, gli sviluppatori possono aggiungerla con il filtro wc_khp_supported_currencies.
Disinstallazione
Disattivando il plugin, tutti i dati vengono conservati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una eventuale nuova installazione. Gli ordini esistenti mantengono le loro note di pagamento e i loro ID transazione.
Khipu è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Khipu né approvato da Khipu.