VibeFox Transbank for PrestaShop — Guida

Requisiti

PrestaShop: dalla 8.0 alla 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Valuta: peso cileno (CLP). Webpay Plus addebita solo pesos interi, quindi imposta la precisione della valuta CLP a 0 in International > Localization > Currencies. Per i carrelli in 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 è approvata e la 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 per Webpay Plus Mall, Oneclick e acquisizione differita non sono supportati.

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 clicca su Upload a module. Scegli il file ZIP del modulo.

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

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

4. Attiva Enable / Disable e clicca su Save. Prova un pagamento con Integration (test) mode attivo, usando le carte di test della documentazione per sviluppatori di Transbank.

5. Per andare in produzione inserisci il Production Commerce Code e la Production API Key Secret, disattiva Integration (test) mode e clicca su Save.

Non serve configurare alcun URL di ritorno o webhook su Transbank. Il modulo invia il proprio URL di ritorno con ogni transazione.

All'installazione il modulo crea lo stato d'ordine Transbank payment on hold. PrestaShop attiva il nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences; la valuta CLP deve restare consentita per il modulo.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Transbank Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando è selezionata la produzione ma il Commerce Code o la API Key di produzione mancano o non sono validi (in tal caso Webpay viene nascosto al checkout), quando la valuta predefinita del negozio non è CLP (il metodo di pagamento viene nascosto per le altre valute) e quando CLP ha decimali (i totali vengono arrotondati ai pesos interi). Finché la modalità di integrazione è attiva, la pagina indica che i pagamenti vanno all'ambiente di integrazione Transbank con il codice di commercio di test pubblico e che non viene addebitato denaro reale.

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus 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: Webpay Plus. Obbligatorio: salvando con un titolo vuoto compare Enter a title for the payment method.

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: i pagamenti vanno all'ambiente di integrazione Transbank con il relativo 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. Disattivalo per andare in produzione. Quando è attivo, i clienti vedono TEST MODE: ambiente di integrazione. Nessun addebito reale. sopra la descrizione del metodo di pagamento.

Production Commerce Code: il tuo codice di commercio di produzione (Tbk-Api-Key-Id): 12 cifre che iniziano con 5970. Se il tuo ha 8 cifre, inseriscilo così com'è; il modulo 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. Tienila segreta. Gli spazi vengono rimossi al salvataggio. Una chiave salvata non viene più mostrata: il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un valore nuovo solo se vuoi cambiarla.

Clear saved API key: spunta Production API Key Secret e clicca su Save per rimuovere la chiave salvata. Un campo vuoto mantiene il valore salvato.

URL di ritorno

Return from Webpay: l'indirizzo a cui Transbank rimanda il cliente, mostrato a titolo di riferimento. Non serve configurare nulla su Transbank: il modulo invia questo URL con ogni transazione. Deve essere raggiungibile dai clienti; la modalità manutenzione non lo blocca.

Avanzate

Debug log: registra le richieste API e i ritorni in logs/wc_tbk_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche con questa opzione disattivata. Non vengono registrati dati della carta, chiavi API o token completi. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del gateway e il log. I dati degli ordini vengono conservati. 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 la modalità in seguito.

Checkout

Al momento del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Webpay Plus, con il logo Webpay) e conferma. Il modulo crea una transazione Transbank per il totale del carrello 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 clicca su Proceed to Webpay. Su Webpay il cliente paga con carta di credito, di debito o prepagata. A questo punto non esiste ancora alcun ordine.

Quando il cliente torna, il modulo 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. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your Webpay payment has been received. Per un ordine in attesa la pagina mostra Your Webpay payment was received and is being reviewed by the shop.

Se la chiamata di conferma non riesce, per esempio per un timeout, il modulo chiede a Transbank lo stato della transazione. Se lo stato resta sconosciuto, non viene creato alcun ordine 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 nello stesso momento un'altra richiesta sta confermando lo stesso carrello, oppure Transbank ha approvato il pagamento ma l'ordine non può ancora essere creato, il cliente vede una pagina Payment confirmation con Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. e un pulsante Check again. L'ordine viene quindi creato dalla risposta salvata, senza una seconda conferma.

Se il cliente annulla su Webpay, oppure il modulo Webpay scade o segnala un errore, non viene addebitato nulla. Il cliente torna al checkout 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 carrello viene conservato e ogni nuovo tentativo è una nuova transazione Webpay.

Se il carrello è cambiato dopo l'avvio del pagamento (per esempio in un'altra scheda, oppure un buono nel carrello non era più valido e PrestaShop lo ha rimosso), la transazione non viene confermata, quindi Transbank non la addebita. Il cliente vede Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. Se il carrello ha già un ordine (pagato con un altro tentativo o un altro metodo di pagamento), anche un ritorno tardivo non viene confermato e 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 quell'ordine non è pagato.

Se Webpay non riesce ad avviare il pagamento, il cliente resta al checkout con 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 ritorno da Webpay funziona mentre il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

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 non viene creato alcun ordine; secondo Transbank, le transazioni non confermate non vengono liquidate. Il modulo non supporta Webpay Plus Mall, carte salvate Oneclick, abbonamenti, acquisizione differita né conversione di valuta.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Webpay e non ha pagato, ha annullato, ha lasciato scadere il modulo, la carta è stata rifiutata o il pagamento non ha ancora potuto essere confermato. Esiste solo il carrello.

Payment accepted: Transbank ha approvato il pagamento. Il pagamento viene registrato con il token Webpay come ID transazione, e una nota mostra il codice di autorizzazione, le ultime quattro cifre della carta, il buy order, l'importo, il tipo di pagamento e il numero di rate.

Transbank payment on hold: Transbank ha autorizzato un pagamento che non corrisponde all'ordine (importo, buy order o sessione), oppure un buono nel carrello non era più valido dopo che Transbank aveva approvato il pagamento e PrestaShop lo ha rimosso. Il pagamento viene registrato con l'importo addebitato da Transbank, e la nota elenca le differenze. Controlla il portale Transbank ed evadi l'ordine oppure rimborsa il pagamento.

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

Se Webpay restituisce un pagamento per un carrello che ha già un ordine, il pagamento non viene confermato e una nota su quell'ordine ti chiede di controllare il portale Transbank se il cliente segnala un addebito. Gli ordini esistenti non sono interessati dai tentativi successivi.

Blocco Transbank Webpay Plus

La pagina dell'ordine mostra un blocco Transbank Webpay Plus con il buy order e il relativo ambiente, lo stato del pagamento, il codice di autorizzazione, la carta e il tipo di pagamento con il numero di rate, l'importo addebitato e rimborsato, un badge Integration per i pagamenti di test, lo storico dei rimborsi, i Webpay attempts of the cart e le Transbank notes dell'ordine.

Rimborsi

Nel blocco Transbank Webpay Plus inserisci l'importo in CLP (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Transbank. Conferma la domanda Refund this amount via Transbank? Sono supportati rimborsi totali e parziali in pesos interi. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine Modules. 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 d'ordine con decimali viene arrotondato come l'addebito. I rimborsi arrivano fino all'importo addebitato da Transbank, quindi dopo una discrepanza puoi rimborsare ciò che il cliente ha effettivamente pagato. Il rimborso va nell'ambiente in cui è stato effettuato il pagamento, quindi per un pagamento di produzione devono essere impostate le credenziali di produzione.

Transbank risponde con uno storno (REVERSED) o un annullamento (NULLIFIED). Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con importo, tipo, codice di autorizzazione e saldo rimasto presso Transbank. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. Se Transbank non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Transbank. I rimborsi effettuati nel portale Transbank non vengono importati in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Transbank Gateway è il primo blocco di Modules > Module Manager > VibeFox Transbank Gateway > Configure, sopra le impostazioni. Inserisci 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 di essi si trovano la riga Product: presta-payment-transbank 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 oppure 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, 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. 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. Il front office 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 puoi testarlo al checkout. Un promemoria appare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati quando il cliente torna da Webpay, e i rimborsi dalla pagina dell'ordine funzionano.

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 a settimana. Non serve alcun cron job. Disinstallare o reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Webpay Plus non compare al checkout: controlla che la licenza sia attiva, che Enable / Disable sia attivo, che la valuta del carrello sia CLP e che, con la modalità di integrazione disattivata, 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. In Payment > Preferences controlla che il modulo sia consentito per CLP, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: Transbank non ha webhook, quindi l'ordine viene creato 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 liquidata. Attiva Debug log, controlla il campo Log e verifica la transazione nel portale Transbank.

Il cliente vede We could not confirm your Webpay payment with Transbank: la chiamata di conferma non è riuscita e non è stato possibile verificare lo stato. Non è stato creato alcun ordine e il motivo è nel log. Il cliente può riprovare tra poco. Se il portale Transbank mostra la transazione come autorizzata, contatta il cliente prima che paghi di nuovo.

Il cliente vede Your cart changed after the Webpay payment was started: il totale del carrello era diverso dalla transazione, per esempio per una modifica in un'altra scheda o per un buono scaduto. Non è stato addebitato nulla; il cliente paga il nuovo totale.

Il cliente vede un errore quando sceglie Webpay Plus: attiva Debug log e controlla il campo Log nella pagina del modulo. Webpay payments are not available at the moment di solito indica credenziali di produzione errate. Could not connect to Webpay significa che Transbank non è raggiungibile. Transbank Webpay only supports payments in CLP (Chilean Peso) significa che il carrello è in un'altra valuta.

Totali e rimborsi differiscono di pochi pesos: la valuta CLP ha decimali. Webpay addebita solo pesos interi, quindi i totali vengono arrotondati. Imposta la precisione di CLP a 0 in International > Localization > Currencies.

L'ordine è Transbank payment on hold dopo il pagamento: leggi le note nel blocco Transbank Webpay Plus (vedi Stati dell'ordine), poi evadi l'ordine oppure rimborsa il pagamento.

Il rimborso non riesce 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 non riesce 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 rimborso non riesce con Another request is processing this order: l'ordine era in fase di rimborso o di conferma nello stesso momento. Riprova tra poco.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Transbank 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 successiva reinstallazione. I tentativi Webpay e i rimborsi degli ordini e lo stato d'ordine Transbank payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID delle transazioni.

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