VibeFox Xendit for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

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

Valuta del negozio: IDR, PHP, VND, THB, MYR, USD o SGD. Per le altre valute del carrello il metodo di pagamento non viene mostrato. Quali canali di pagamento e valute sono effettivamente disponibili dipende dal tuo account Xendit.

Account Xendit: ti servono una chiave API segreta con permesso di scrittura per Money-in (fatture) per la modalità test e un'altra per la modalità live, oltre al token di verifica dei webhook di ciascuna modalità (vedi Configurazione). Vengono usate solo le chiavi segrete e i token di verifica. Non serve nessuna chiave pubblica, perché il cliente paga sulla pagina della fattura ospitata da Xendit.

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

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Xendit Payment Gateway nell'elenco dei moduli e fai clic su Configure.

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

4. Incolla le tue chiavi segrete di Xendit, imposta l'URL del webhook nella Dashboard di Xendit e incolla i token di verifica (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Effettua un ordine di prova in modalità test, poi disattiva Test Mode per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine Xendit payment on hold. PrestaShop offre un 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 Xendit Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi un riquadro mostra la modalità attiva: TEST MODE (le fatture vengono create con la chiave segreta di test e non viene addebitato denaro reale) oppure LIVE MODE (le fatture vengono create con la chiave segreta live e i clienti vengono addebitati). Il riquadro avvisa quando la chiave segreta della modalità attiva manca o ha il prefisso sbagliato (in quel caso il metodo di pagamento viene nascosto al checkout), e quando il token di verifica del webhook della modalità attiva è vuoto (le notifiche di Xendit vengono rifiutate, quindi gli ordini vengono creati solo quando il cliente torna nel tuo negozio).

Xendit

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

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

Chiavi API

Crea una chiave API segreta con permesso di scrittura per Money-in (fatture) in Xendit Dashboard > Settings > Developers > API keys, una volta in modalità test e una volta in modalità live. La chiave decide dove viene creata la fattura. Al salvataggio, una chiave che non inizia con il prefisso del suo campo non viene salvata, e la pagina mostra per esempio Test secret key was not saved: it must start with xnd_development_. Le altre impostazioni vengono salvate.

Test Mode: crea le fatture con la chiave segreta di test, quindi non viene addebitato denaro reale. Predefinito: attivato. Disattivalo per accettare pagamenti reali con la chiave segreta live. Finché è attivo, i clienti vedono Test mode: no real money is charged. sotto il metodo di pagamento.

Test Secret Key: la chiave segreta della modalità test di Xendit. Inizia con xnd_development_.

Live Secret Key: la chiave segreta della modalità live di Xendit. Inizia con xnd_production_.

Le chiavi e i token salvati non vengono più mostrati. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi modificarlo.

Webhooks

Il webhook comunica al tuo negozio che una fattura è stata pagata. In Xendit Dashboard > Settings > Developers > Webhooks imposta l'URL mostrato in Webhook URL di questa sezione per Invoices > Invoice paid, in modalità test e in modalità live. Facoltativamente impostalo anche per Invoice expired. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_xendit_payment_gateway/webhook, eventualmente con un codice lingua come /en/. Copialo esattamente come lo mostrano le impostazioni.

Copia poi il Webhook verification token di ciascuna modalità dalla Dashboard di Xendit nel campo corrispondente. Xendit lo invia nell'intestazione x-callback-token. Le notifiche senza il token della modalità in cui è stata creata la fattura vengono rifiutate. Il token dimostra solo che la notifica arriva da Xendit: stato, importo e valuta della fattura vengono sempre riletti dall'API di Xendit con la chiave segreta di quella modalità. Senza il webhook, un ordine viene creato solo quando il cliente torna nel negozio dopo il pagamento.

Test Webhook Verification Token: il token di verifica del webhook della modalità test di Xendit.

Live Webhook Verification Token: il token di verifica del webhook della modalità live di Xendit.

Clear saved secrets: spunta una chiave o un token e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Pagamento

Invoice Description: la descrizione mostrata sulla fattura di Xendit. Puoi usare i segnaposto {order_id}, {order_number} e {site_name}. Poiché l'ordine viene creato dopo il pagamento, {order_id} e {order_number} sono il numero del carrello. L'HTML viene rimosso e il testo viene troncato a 255 caratteri. Predefinito: Order #{order_id}.

Order Status After Payment: lo stato dell'ordine impostato dopo che Xendit conferma il pagamento.

Avanzate

Debug Log: scrive le richieste API e i webhook in logs/xendit_p_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche quando l'opzione è disattivata. Chiavi API, token e dati dei clienti non vengono registrati. Predefinito: disattivato.

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

Delete Data on Uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo e il log. I dati degli ordini (ID delle fatture degli ordini) e lo stato dell'ordine Xendit payment on hold vengono sempre conservati. Predefinito: disattivato.

Checkout

Il metodo di pagamento viene mostrato quando la valuta del carrello è IDR, PHP, VND, THB, MYR, USD o SGD. Il cliente lo sceglie nella fase di pagamento (per impostazione predefinita Xendit) e conferma. Il modulo crea una fattura Xendit per il totale del carrello nella valuta del carrello e invia il cliente alla pagina della fattura di Xendit. Gli importi in IDR e VND vengono arrotondati a numeri interi, perché Xendit non accetta decimali per queste valute. L'e-mail del cliente viene passata a Xendit. Sulla pagina della fattura il cliente paga con uno dei canali di pagamento attivati nel tuo account Xendit per questa valuta, per esempio un conto virtuale, un portafoglio elettronico, un codice QR, un punto vendita al dettaglio o una carta. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo quando Xendit lo conferma: tramite il webhook, oppure con una richiesta lato server all'API di Xendit quando il cliente torna. Solo allora l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine. Se Xendit non ha ancora confermato il pagamento, compare una pagina Payment confirmation con il messaggio Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. e i pulsanti Check again e Back to checkout. Il webhook crea l'ordine non appena arriva.

Se la fattura fallisce o scade, Xendit rimanda il cliente indietro. Il modulo controlla prima la fattura (potrebbe essere stata pagata in un'altra scheda), poi la fa scadere, così non può più essere pagata. Il cliente torna al checkout con il messaggio The Xendit payment was not completed. You can try again or choose another payment method. Il carrello viene conservato.

Un cliente può pagare di nuovo lo stesso carrello. Se il totale del carrello, la valuta e la modalità non sono cambiati e la fattura aperta è ancora valida per almeno altri cinque minuti, il cliente viene inviato alla stessa fattura. Altrimenti la vecchia fattura viene prima fatta scadere e ne viene creata una nuova, così non ci sono mai due fatture aperte per lo stesso carrello. Se la vecchia fattura è già stata pagata, viene creato l'ordine invece di un nuovo pagamento.

Se Xendit non riesce ad avviare il pagamento, il cliente resta al checkout con un messaggio breve, per esempio Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., un messaggio che indica che la valuta non è accettata per il tuo account oppure che il totale dell'ordine è fuori dai limiti di importo di Xendit. Il motivo tecnico viene scritto nel log. Un carrello con totale zero non può essere pagato con Xendit.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non viene bloccato dalla restrizione per paese del tuo negozio.

Il pagamento avviene sempre sulla pagina di Xendit. Il modulo non prevede rimborsi dal back office, carte salvate, abbonamenti o pagamenti ricorrenti, campi per carta o portafoglio elettronico nel checkout, autorizzazione e cattura separate né sottoaccount xenPlatform.

Ordini

Stati dell'ordine

Ancora nessun ordine: il cliente è stato inviato a Xendit e non ha pagato, oppure Xendit non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted or Delivered: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID della fattura Xendit come ID transazione, e una nota mostra l'ID della fattura, l'importo pagato, il canale di pagamento e la modalità.

Xendit payment on hold: la fattura pagata non corrispondeva al totale o alla valuta del carrello, oppure è stato pagato meno del totale (per esempio il carrello è stato modificato dopo la creazione della fattura). La nota lo spiega. Controlla il pagamento nella Dashboard di Xendit, poi evadi l'ordine oppure rimborsa il pagamento. Se in seguito viene pagata un'altra fattura dello stesso carrello con l'importo corretto, il pagamento viene registrato e l'ordine passa allo stato pagato.

Se una fattura viene pagata per un ordine già annullato o rimborsato, lo stato dell'ordine non cambia. Una nota ti chiede di rimborsare il pagamento nella Dashboard di Xendit oppure di ripristinare l'ordine manualmente. Se una seconda fattura viene pagata per un ordine già pagato, l'ordine non cambia e una nota ti chiede di rimborsare il pagamento duplicato nella Dashboard di Xendit.

Blocco Xendit payment

La pagina dell'ordine mostra un blocco Xendit payment con l'ID della fattura, la modalità (con un badge Test mode per i pagamenti di prova), lo stato del pagamento, un elenco di tutte le fatture dell'ordine (data, fattura, ID esterno, importo e importo pagato, stato, canale di pagamento) e le Payment notes dell'ordine.

Rimborsi

I rimborsi non vengono inviati a Xendit dal negozio. Rimborsa il pagamento nella Dashboard di Xendit (cerca l'ID della fattura mostrato nel blocco Xendit payment) e registra il rimborso nell'ordine manualmente. I normali pulsanti di rimborso di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Xendit.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco della licenza License — VibeFox Xendit Payment Gateway è il primo blocco di Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic 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: presta-payment-xendit 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 incluse l'inglese e il 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 un cambio dell'indirizzo del negozio, o dopo aver liberato un posto per il 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 multistore. Rimuovere la chiave dal negozio non libera il posto per il dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Xendit 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 sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a 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 ricontrollato 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 nessun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Xendit non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità attiva abbia una chiave segreta con il prefisso corretto (Test Secret Key con xnd_development_ in modalità test, Live Secret Key con xnd_production_ in modalità live) e che la valuta del carrello sia IDR, PHP, VND, THB, MYR, USD o SGD. La pagina delle impostazioni mostra un avviso quando la chiave manca o è sbagliata. 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 nessun ordine è stato creato: il webhook non funziona. Nella Dashboard di Xendit della modalità che usi (test o live) verifica che l'URL mostrato in Webhook URL sia impostato per Invoice paid e che il token di verifica di quella modalità sia salvato nel campo corrispondente. La Dashboard di Xendit mostra la risposta del tuo negozio per ogni webhook. L'ordine viene creato anche quando il cliente torna nel negozio dopo il pagamento.

Il webhook risponde Webhook verification token is not configured: non è impostato nessun token di verifica. Incolla il token nelle impostazioni.

Il webhook risponde Unauthorized: il token inviato da Xendit non corrisponde a nessun token delle impostazioni. Copia di nuovo il token della modalità giusta.

Il webhook risponde Token does not match the mode of this invoice: la fattura è stata creata nell'altra modalità. Una notifica di test non conferma mai un pagamento reale, e viceversa. Imposta il webhook e il token nella modalità in cui è stato pagato il carrello.

Il webhook risponde Ignored: not an invoice of this store: la fattura non è stata creata da questo negozio, per esempio da un'altra integrazione sullo stesso account Xendit. Anche il pulsante Test della Dashboard di Xendit riceve questa risposta, il che conferma che URL e token funzionano. Ignored: unknown order e Ignored: unknown invoice significano che il carrello o la fattura non sono noti a questo negozio.

Il webhook risponde Temporary error: non è stato possibile raggiungere l'API di Xendit per verificare la fattura, manca la chiave segreta della modalità della fattura, il carrello era in aggiornamento da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Xendit ripete il webhook. Verifica che entrambe le chiavi segrete siano impostate se i pagamenti sono stati avviati in entrambe le modalità, e attiva Debug Log per vedere il motivo.

L'URL del webhook nel browser mostra Method not allowed: è normale. L'URL accetta solo richieste da Xendit.

Una chiave non viene salvata: il valore non inizia con il prefisso del suo campo. Le chiavi di test iniziano con xnd_development_, quelle live con xnd_production_.

Il cliente vede This payment method is temporarily unavailable: Xendit ha rifiutato la richiesta, per esempio perché la chiave segreta è sbagliata o non ha il permesso di scrittura per Money-in (fatture). Controlla il campo Log nella pagina del modulo. Un messaggio sui dati di fatturazione significa che Xendit non ha accettato i dati della richiesta, per esempio l'e-mail.

Il cliente vede A payment for this order was already received by Xendit and is being reviewed: una fattura precedente di questo carrello è stata pagata, ma l'ordine non ha ancora potuto essere confermato. Controlla il pagamento nella Dashboard di Xendit e nel log.

Il cliente vede We could not match this payment to an order: il link di ritorno di Xendit non appartiene a un carrello di questo negozio, oppure non è stato possibile associare nessuna fattura del carrello. Controlla il pagamento nella Dashboard di Xendit e nel log.

Ordine in Xendit payment on hold dopo il pagamento: leggi le note nel blocco Xendit payment. L'importo o la valuta pagati erano diversi dal carrello. Evadi l'ordine oppure rimborsa il pagamento nella Dashboard di Xendit.

Per gli sviluppatori, il modulo mette a disposizione gli hook actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies e actionWcpXenditCurrencyDecimals per modificare la richiesta di fattura, l'elenco delle valute e il numero di decimali per valuta.

Disinstallazione

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

Xendit è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Xendit né approvato da Xendit.