VibeFox Transbank for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 8.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Valuta del negozio: peso cileno (CLP). Webpay Plus addebita solo pesos interi, quindi imposta Number of decimals su 0 in WooCommerce > Settings > General. Nei negozi con un'altra valuta il metodo di pagamento non viene mostrato.

Account Transbank: per i pagamenti reali ti serve un commercio Webpay Plus standard (acquisizione immediata) con il relativo Commerce Code di produzione e la API Key Secret. Transbank ti fornisce il Commerce Code quando l'affiliazione viene approvata e l'API Key Secret dopo il processo di validazione dell'integrazione (vedi la documentazione per sviluppatori di Transbank). Per i test non servono credenziali. I codici di commercio Webpay Plus Mall, Oneclick e con acquisizione differita non sono supportati.

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 fai clic su Install Now. Puoi anche caricare la cartella wcp_transbank_gateway in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

3. Imposta la valuta del negozio su peso cileno e Number of decimals su 0 in WooCommerce > Settings > General.

4. Apri le impostazioni: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugins.

5. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

6. Attiva Enable / Disable e prova un pagamento con Integration (test) mode attivo, usando le carte di test della documentazione per sviluppatori di Transbank.

7. Per andare in produzione, inserisci il tuo Production Commerce Code e la tua Production API Key Secret, deseleziona Integration (test) mode e salva.

Su Transbank non serve configurare alcun URL di ritorno o webhook. Il plugin invia il proprio URL di ritorno con ogni transazione.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Transbank Webpay Plus. Sopra i campi la pagina ti avvisa quando è selezionata la produzione ma il Production Commerce Code o la API Key manca o non è valida (Webpay viene allora nascosto al checkout), quando la valuta del negozio non è CLP (il metodo di pagamento viene nascosto) e quando i prezzi in CLP hanno decimali (i totali vengono arrotondati a pesos interi). Con la modalità di integrazione attiva, la pagina mostra Integration (test) environment: non viene addebitato denaro reale. Dopo il salvataggio, gli avvisi seguono già le nuove impostazioni. Nell'elenco dei metodi di pagamento, il gateway risulta da configurare quando è selezionata la produzione senza credenziali valide.

Generali

Enable / Disable: Enable Transbank Webpay Plus payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Webpay Plus.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with credit, debit or prepaid card via Webpay.

Ambiente e credenziali

Il testo della sezione rimanda alla documentazione per sviluppatori di Transbank e spiega quando Transbank fornisce le credenziali di produzione.

Integration (test) mode: Use the Transbank integration environment. I pagamenti vanno all'ambiente di integrazione di Transbank con il suo codice di commercio di test pubblico (597055555532), inserito automaticamente. Le credenziali di produzione qui sotto non vengono usate e non viene addebitato denaro reale. Predefinito: attivo. Deselezionala per andare in produzione.

Production Commerce Code: il tuo codice di commercio di produzione (Tbk-Api-Key-Id): 12 cifre, che iniziano con 5970. Se il tuo ne ha 8, inseriscilo così com'è; il plugin aggiunge il prefisso 5970 al salvataggio. Spazi e altri caratteri vengono rimossi. I codici di commercio di test pubblici di Transbank non sono accettati in produzione.

Production API Key Secret: il Tbk-Api-Key-Secret del tuo commercio di produzione. Tienilo riservato. Gli spazi vengono rimossi al salvataggio.

Avanzate

Debug log: Log API requests and returns (errors are always logged). I dettagli vengono scritti in WooCommerce > Status > Logs, origine wcp_transbank_gateway; il campo ha un collegamento view logs. Errori e avvisi vengono registrati anche quando questa opzione è disattivata. Nel log non vengono registrati dati della carta, chiavi API né token completi. Predefinito: disattivato.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (order data is kept). Predefinito: disattivato.

Test e produzione

Integration (test) mode decide dove vanno i nuovi pagamenti. Ogni pagamento ricorda il proprio ambiente: la conferma e i rimborsi di un pagamento vanno sempre all'ambiente (integrazione o produzione) e con le credenziali con cui è stato creato, anche se cambi modalità in seguito.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Webpay Plus) e invia l'ordine. In modalità di integrazione il checkout mostra TEST MODE: Integration environment. Nessun addebito reale. Il plugin crea una transazione Transbank per il totale dell'ordine in pesos interi (un totale con decimali viene arrotondato al peso più vicino) e invia il cliente a una breve pagina Redirecting to Webpay. Please wait..., che lo inoltra al modulo Webpay. Senza JavaScript il cliente fa clic su Proceed to Webpay. Su Webpay il cliente paga con carta di credito, di debito o prepagata.

Quando il cliente torna, il plugin conferma (commit) la transazione con Transbank da server a server. L'ordine viene segnato come pagato solo dopo la conferma di Transbank: la risposta deve essere approvata e importo, buy order e sessione devono corrispondere a quanto il negozio ha inviato per questo tentativo. Il cliente vede poi la pagina Ordine ricevuto. Se la chiamata di conferma non riesce, per esempio per un timeout, il plugin chiede a Transbank lo stato della transazione. Se lo stato resta sconosciuto, l'ordine non viene modificato e il cliente vede We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again.

Se il cliente annulla su Webpay, il modulo Webpay scade o segnala un errore, non viene addebitato nulla. L'ordine resta in attesa di pagamento e il cliente torna alla pagina Pay for order con un messaggio, per esempio You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. Una carta rifiutata mostra Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. Il cliente può pagare di nuovo dalla stessa pagina. Ogni nuovo tentativo è una nuova transazione Webpay.

Ogni tentativo Webpay viene confermato al massimo una volta. Ricaricare la pagina di ritorno, usare il pulsante Indietro del browser o un secondo ritorno contemporaneo non confermano mai due volte e non modificano mai l'ordine. Se un ordine non richiede più il pagamento (già pagato con un altro tentativo, annullato o rimborsato), un ritorno tardivo non viene confermato, quindi Transbank non lo addebita. Il cliente vede This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

Se Webpay non può avviare il pagamento, il cliente vede un breve messaggio, per esempio Could not connect to Webpay. Please try again in a moment. oppure Webpay payments are not available at the moment. Please choose another payment method. Il motivo tecnico viene scritto nel log.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Transbank non prevede webhook di pagamento: il risultato viene elaborato quando il cliente torna da Webpay. Se il cliente chiude il browser su Webpay e non torna mai, la transazione non viene confermata e l'ordine resta in sospeso; secondo Transbank, le transazioni non confermate non vengono regolate. Il plugin non supporta Webpay Plus Mall, carte salvate Oneclick, abbonamenti, acquisizione differita né conversione di valuta.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Webpay e non ha ancora pagato, ha annullato, ha lasciato scadere il modulo, oppure il pagamento non ha ancora potuto essere confermato. Una nota registra ogni tentativo chiuso con il suo buy order.

Processing or Completed: Transbank ha approvato il pagamento. Lo stato è impostato da WooCommerce: In lavorazione, oppure Completato per gli ordini con soli prodotti virtuali scaricabili. La nota dell'ordine riporta il codice di autorizzazione, le ultime quattro cifre della carta, il buy order, l'importo, il tipo di pagamento e il numero di rate. L'ID transazione è il token Webpay.

On hold: Transbank ha autorizzato un pagamento che non corrisponde all'ordine (importo, buy order o ID sessione), per esempio perché l'ordine è stato modificato dopo l'avvio del pagamento. La nota elenca le differenze. Controlla il portale Transbank e rimborsa o completa l'ordine.

Failed: il pagamento è stato rifiutato. Non è stato addebitato nulla. La nota mostra il codice e lo stato della risposta.

Se Webpay restituisce un pagamento per un ordine già pagato, annullato o rimborsato, il pagamento non viene confermato e una nota ti chiede di controllare il portale Transbank se il cliente segnala un addebito. Gli ordini esistenti non sono influenzati dai tentativi successivi.

Rimborsi

Il pulsante di rimborso viene offerto solo per gli ordini pagati tramite Webpay. Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Webpay Plus (il pulsante usa il titolo del metodo di pagamento). Sono supportati rimborsi totali e parziali in pesos interi. Un importo parziale con decimali viene rifiutato con Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. L'ultimo residuo di un totale dell'ordine con decimali viene arrotondato come l'addebito. Il rimborso va all'ambiente in cui è stato effettuato il pagamento, quindi in produzione devono essere impostate le credenziali di produzione.

Transbank risponde con uno storno (REVERSED) o un annullamento (NULLIFIED). Un rimborso riuscito viene aggiunto alle note dell'ordine con importo, tipo, codice di autorizzazione e saldo residuo presso Transbank. Se Transbank non accetta il rimborso, WooCommerce mostra l'errore e nessun rimborso viene registrato. I rimborsi effettuati nel portale Transbank non vengono importati in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Transbank Webpay Plus. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino a cui 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 collegamento 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 il suo posto di dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Webpay Plus 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. I gestori del negozio con accesso vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono influenzati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Webpay Plus non compare al checkout: controlla che la licenza sia attiva, che Enable / Disable sia attivo, che la valuta del negozio sia CLP (nella pagina Pay for order, la valuta dell'ordine) e, con la modalità di integrazione disattiva, che siano salvati un Production Commerce Code valido (12 cifre, che iniziano con 5970) e una Production API Key Secret. La pagina delle impostazioni mostra un avviso per ogni condizione mancante.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: Transbank non ha webhook, quindi l'ordine viene confermato solo quando il cliente torna da Webpay. Se il cliente ha chiuso il browser su Webpay, la transazione non è stata confermata e, secondo Transbank, non viene regolata. Controlla le note dell'ordine, il log e la transazione nel portale Transbank.

Il cliente vede We could not confirm your Webpay payment with Transbank: la chiamata di conferma non è riuscita e lo stato non ha potuto essere verificato. L'ordine non è stato modificato ed è stata aggiunta una nota. Il cliente può riprovare tra poco. Se il portale Transbank mostra la transazione come autorizzata, confermala lì prima della spedizione.

Il cliente vede un errore durante l'invio dell'ordine: attiva Debug log e controlla WooCommerce > Status > Logs, origine wcp_transbank_gateway. Il messaggio Webpay payments are not available at the moment indica di solito credenziali di produzione errate. Could not connect to Webpay significa che Transbank non è raggiungibile. Un ordine in una valuta diversa da CLP non può essere pagato con Webpay.

Totali e rimborsi differiscono di qualche peso: i prezzi in CLP hanno decimali. Webpay addebita pesos interi, quindi i totali vengono arrotondati. Imposta Number of decimals su 0.

Il rimborso fallisce con The production Commerce Code / API Key are missing: il pagamento è stato effettuato in produzione e le credenziali di produzione non sono salvate. Inseriscile e riprova.

Il rimborso fallisce con Transbank refused the refund oppure Transbank did not approve the refund: Transbank non lo ha accettato; il messaggio mostra il motivo oppure il tipo e il codice di risposta restituiti. Non è stato rimborsato nulla. Controlla la transazione nel portale Transbank.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

La disattivazione del plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway, le altre opzioni e i dati temporanei del plugin e i suoi log (file di log, compresi quelli ruotati, e voci di log nel database) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. I dati Transbank memorizzati sugli ordini vengono sempre conservati, perché servono per la contabilità e i rimborsi. Gli ordini esistenti conservano le proprie note di pagamento e gli ID delle transazioni.

Transbank e Webpay sono marchi dei rispettivi titolari. Questo plugin non è affiliato a Transbank né approvato da Transbank.