VibeFox Xendit 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: IDR, PHP, VND, THB, MYR, USD o SGD. Per le altre valute il metodo di pagamento non viene mostrato. Quali canali di pagamento e valute siano effettivamente disponibili dipende dal tuo account Xendit.

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

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_xendit_payment_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Xendit > Manage, oppure fai clic su 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 fai clic su Activate.

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

6. Attiva Enable/Disable. Effettua un ordine di prova in modalità test, poi deseleziona Test Mode per accettare pagamenti reali.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Xendit. Sopra i campi un banner 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 banner avvisa quando manca la chiave segreta della modalità attiva 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 aggiornati solo quando il cliente torna nel tuo negozio). Nell'elenco dei metodi di pagamento, Xendit è segnalato come da configurare finché la modalità attiva non ha una chiave segreta valida.

Generale

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. Predefinito: Xendit.

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 determina 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: Enable test mode crea le fatture con la chiave segreta di test, quindi non viene addebitato denaro reale. Predefinito: attivo. Deselezionala per accettare pagamenti reali con la chiave segreta live.

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

Webhook

Il webhook comunica al tuo negozio che una fattura è stata pagata. In Xendit Dashboard > Settings > Developers > Webhooks imposta l'URL mostrato in questa sezione delle impostazioni per Invoices > Invoice paid, in modalità test e in modalità live. Facoltativamente, impostalo anche per Invoice expired. L'URL ha questa forma: https://your-site/wc-api/xendit_p_callback/. Copialo esattamente come lo mostrano le impostazioni.

Poi copia 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 soltanto 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 webhook, un ordine viene confermato solo quando il cliente torna nel negozio dopo aver pagato.

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.

Pagamento

Invoice Description: la descrizione mostrata sulla fattura Xendit. Puoi usare i segnaposto {order_id}, {order_number} e {site_name}. 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. Lo stato viene impostato subito, in un'unica modifica.

Avanzate

Debug Log: Log API requests and webhooks scrive richieste, webhook e cambi di stato in WooCommerce > Status > Logs, origine wcp_xendit_payment_gateway. Errori e avvisi vengono sempre registrati, anche quando questa opzione è disattivata. Chiavi API, token e dati dei clienti non vengono registrati. Predefinito: disattivato.

Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. Disattivare il plugin non cancella mai nulla. I dati degli ordini (ID delle fatture negli ordini) vengono sempre conservati. Predefinito: disattivato.

Checkout

Il metodo di pagamento viene mostrato quando la valuta del negozio è IDR, PHP, VND, THB, MYR, USD o SGD. Nella pagina Pay for order conta la valuta dell'ordine. Il cliente sceglie il metodo di pagamento (per impostazione predefinita Xendit) e completa l'ordine. Il plugin crea una fattura Xendit per il totale dell'ordine nella valuta dell'ordine e manda il cliente alla pagina della fattura Xendit. Gli importi in IDR e VND vengono arrotondati a numeri interi, perché Xendit non accetta decimali per queste valute. L'indirizzo e-mail di fatturazione del cliente viene passato 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.

Dopo il pagamento il cliente torna alla pagina Ordine ricevuto del 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 arriva su quella pagina. Fino ad allora l'ordine resta In attesa di pagamento.

Se la fattura non va a buon fine o scade, Xendit rimanda il cliente indietro. Un ordine effettuato al checkout viene allora annullato nel modo standard di WooCommerce e la sua fattura scade. Un ordine pagato dalla pagina Pay for order (per esempio un ordine che hai creato per il cliente) torna alla sua pagina di pagamento con il messaggio The Xendit payment was not completed. You can try again or choose another payment method. e resta pagabile.

Un cliente può pagare di nuovo un ordine non pagato. Se il totale dell'ordine, la valuta e la modalità sono invariati e la fattura aperta è ancora valida, il cliente viene mandato alla stessa fattura. Altrimenti la vecchia fattura scade per prima e ne viene creata una nuova, così non ci sono mai due fatture aperte per lo stesso ordine. Se la vecchia fattura era già stata pagata, l'ordine diventa Completato invece di richiedere un nuovo pagamento.

Se Xendit non riesce ad avviare il pagamento, il cliente vede un messaggio breve e può scegliere un altro metodo di pagamento, 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 ordine con totale zero non può essere pagato con Xendit.

Il metodo di pagamento funziona al checkout classico, nel blocco Checkout e nella pagina Pay for order. In modalità test il blocco Checkout mostra Test mode: no real money is charged. sotto il metodo di pagamento. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il pagamento avviene sempre nella pagina di Xendit. Il plugin non offre rimborsi da WooCommerce, carte salvate, abbonamenti o pagamenti ricorrenti, campi per carta o portafoglio elettronico nel checkout, autorizzazione e cattura separate, sottoaccount xenPlatform, scadenza personalizzata della fattura né commissioni di pagamento.

Ordini

Stati dell'ordine

Pending payment: la fattura è stata creata e il cliente non ha ancora pagato, oppure Xendit non ha ancora confermato il pagamento. La nota dell'ordine mostra l'ID della fattura, l'importo, la valuta e la modalità.

Processing or Completed: il pagamento è stato confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra l'ID della fattura, l'importo pagato, il canale di pagamento e la modalità. L'ID transazione è l'ID della fattura Xendit.

On hold: la fattura pagata non corrispondeva al totale o alla valuta dell'ordine, oppure è stato pagato meno del totale (per esempio l'ordine è stato modificato dopo la creazione della fattura). La nota dell'ordine lo spiega, anche quando l'ordine era già in sospeso. Controlla il pagamento nella Dashboard di Xendit, poi evadi l'ordine o rimborsa il pagamento.

Failed: la fattura attuale è scaduta senza pagamento. Il cliente può pagare di nuovo l'ordine.

Cancelled: il cliente è tornato da una fattura non riuscita o scaduta, oppure l'ordine è stato annullato da te o dal timeout di WooCommerce per gli ordini non pagati. La fattura aperta scade, quindi non può più essere pagata. Se Xendit non accetta questa operazione, una nota ti chiede di far scadere la fattura nella Dashboard di Xendit.

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

Rimborsi

I rimborsi non vengono inviati a Xendit da WooCommerce. Rimborsa il pagamento nella Dashboard di Xendit (la nota dell'ordine e l'ID transazione contengono l'ID della fattura) e registra il rimborso in WooCommerce manualmente.

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 > Xendit. 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 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 il suo slot di 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. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Sulla pagina Plugins e sulle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati.

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

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 giusto (Test Secret Key con xnd_development_ in modalità test, Live Secret Key con xnd_production_ in modalità live) e che la valuta del negozio sia IDR, PHP, VND, THB, MYR, USD o SGD. Il banner delle impostazioni mostra un avviso quando la chiave manca o è sbagliata.

Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: il webhook non funziona. Nella Dashboard di Xendit della modalità che usi (test o live) verifica che l'URL mostrato nelle impostazioni 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 confermato anche quando il cliente torna alla pagina Ordine ricevuto.

Risposta del webhook «Webhook verification token is not configured»: nessuno dei due token di verifica è impostato. Incolla il token nelle impostazioni.

Risposta del webhook «Unauthorized»: il token inviato da Xendit non corrisponde a nessun token nelle impostazioni. Copia di nuovo il token della modalità giusta.

Risposta del webhook «Token does not match the mode of this invoice»: la fattura è stata creata nell'altra modalità. Una notifica di test non conferma mai un ordine live, e viceversa. Imposta il webhook e il token nella modalità in cui è stato pagato l'ordine.

Risposta del webhook «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, che conferma che URL e token funzionano.

Risposta del webhook «Temporary error»: non è stato possibile raggiungere l'API di Xendit per verificare la fattura, manca la chiave segreta della modalità della fattura, oppure l'ordine era in aggiornamento da un'altra richiesta nello stesso momento. Xendit ripete il webhook. Controlla che entrambe le chiavi segrete siano impostate se hai ordini di entrambe le modalità.

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). Attiva Debug Log se serve e controlla WooCommerce > Status > Logs, origine wcp_xendit_payment_gateway. 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 ordine è stata pagata, ma non corrispondeva all'ordine, quindi l'ordine è in sospeso. Controlla il pagamento nella Dashboard di Xendit.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta pagati erano diversi da quelli dell'ordine. Evadi l'ordine o rimborsa il pagamento nella Dashboard di Xendit.

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 fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su 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 noto.

Disinstallazione

Disattivare il plugin conserva tutti i dati. 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, le altre opzioni del plugin, i dati temporanei e i suoi log (file di log, anche quelli ruotati, voci di log nel database e la cartella dei log della versione 1.0) vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le loro note di pagamento, gli ID delle fatture e gli ID delle transazioni.

Xendit è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Xendit.