VibeFox Midtrans for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 8.0 o successivo, installato e attivo. Senza WooCommerce il plugin non si attiva.
PHP: 8.0 o successivo.
Valuta del negozio: rupia indonesiana (IDR). Per le altre valute il metodo di pagamento viene nascosto al checkout. Non è prevista alcuna conversione di valuta.
Account Midtrans: ti serve la Server Key da Midtrans Dashboard > Settings > Access Keys, nella dashboard sandbox e nella dashboard di produzione. Viene usata solo la Server Key. La Client Key non serve per Snap Redirect. I metodi di pagamento veri e propri (GoPay, QRIS, conti virtuali e altri) si attivano nel tuo account Midtrans.
Chiave di licenza VibeFox: si acquista 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. In alternativa puoi caricare via FTP la cartella wcp_midtrans_payment_gateway in /wp-content/plugins/.
2. Fai clic su Activate.
3. Imposta la valuta del negozio su rupia indonesiana (IDR).
4. Apri le impostazioni: WooCommerce > Settings > Payments > Midtrans > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.
5. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.
6. Inserisci le Server Key e copia l'URL di notifica del pagamento nella dashboard di Midtrans (vedi Configurazione).
7. Attiva Enable/Disable. Esegui le prove in Sandbox, poi passa Environment a Production.
Configurazione
Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Midtrans. Sopra i campi, la pagina ti avvisa quando manca la Server Key dell'ambiente selezionato (in quel caso il metodo di pagamento viene nascosto al checkout) e quando la valuta del negozio non è IDR, e mostra Sandbox mode: payments are simulated, no real money is charged. finché è selezionato Sandbox. Nell'elenco dei metodi di pagamento, Midtrans risulta come da configurare finché non viene inserita una Server Key, e in Sandbox mostra Test mode.
General
Enable/Disable: Enable Midtrans payments attiva o disattiva il metodo di pagamento. Predefinito: off.
Title: il titolo del metodo di pagamento mostrato ai clienti al checkout. Predefinito: Midtrans.
Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. In Sandbox viene aggiunta la riga SANDBOX MODE: no real money is charged.
Credenziali API
Copia la Server Key da Midtrans Dashboard > Settings > Access Keys. La sezione contiene link alla dashboard di produzione e a quella sandbox.
Environment: l'ambiente Midtrans usato dai nuovi pagamenti. Il cambio usa la chiave e l'API dell'ambiente selezionato. Gli ordini mantengono l'ambiente in cui sono stati pagati, per rimborsi e notifiche. Predefinito: Sandbox.
Production Server Key: inizia con Mid-server-. Tienila riservata.
Sandbox Server Key: inizia con SB-Mid-server-.
URL di notifica del pagamento
La notifica comunica al negozio che un pagamento è stato effettuato. La sezione mostra l'URL da usare. Ha questo aspetto: https://your-site/wc-api/midtrans_p_callback/. Incollalo in Midtrans Dashboard > Settings > Payment > Notification URL, nella dashboard sandbox e in quella di produzione che usi. Se apri l'URL in un browser, compare una breve spiegazione, così puoi verificare che sia raggiungibile. Anche il pulsante Test notification URL nella dashboard di Midtrans ottiene una risposta.
Ogni notifica deve contenere una firma valida creata con una delle tue Server Key, e l'ambiente della chiave deve corrispondere a quello dell'ordine. Le notifiche senza firma valida vengono rifiutate. Lo stato viene poi riletto dalle API di stato di Midtrans. Il plugin gestisce questi stati di transazione Midtrans:
Senza l'URL di notifica, un ordine viene confermato solo quando il cliente torna nel negozio dopo aver pagato.
Impostazioni di pagamento
Midtrans addebita solo in IDR e gli importi vengono inviati in rupie intere. Se le righe dell'ordine non corrispondono al totale arrotondato, viene inviata a Midtrans una riga Rounding adjustment.
Status after payment: lo stato dell'ordine dopo un pagamento confermato. Lo stato viene impostato in un solo passaggio, senza doppie email al cliente.
Payment page expiry (minutes): per quanto tempo il cliente può pagare (pagina Snap, conto virtuale ecc.). Lascia vuoto o imposta 0 per il valore predefinito di Midtrans.
Order ID prefix: viene aggiunto al numero d'ordine inviato a Midtrans, così più negozi possono condividere un account Midtrans. Solo lettere, cifre e - _ . ~, fino a 20 caratteri; gli altri caratteri vengono rimossi al salvataggio. Le notifiche di altri negozi vengono ignorate. Predefinito: WC-.
Avanzate
Debug log: Log API calls and notifications scrive in WooCommerce > Status > Logs, origine wcp_midtrans_payment_gateway. Gli errori vengono sempre registrati. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: off.
Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. Predefinito: off.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Midtrans) e inoltra l'ordine. Il plugin crea una transazione Midtrans Snap per il totale dell'ordine in rupie intere, con le righe d'ordine, la spedizione, le tasse e i dati di fatturazione e spedizione del cliente, e invia il cliente alla pagina di pagamento Midtrans. Lì il cliente sceglie uno qualsiasi dei metodi attivi nel tuo account Midtrans.
Dopo il pagamento, il cliente torna alla pagina di conferma dell'ordine del tuo negozio. Il link di ritorno non segna mai un ordine come pagato: il plugin interroga le API di stato di Midtrans e l'ordine viene segnato come pagato solo quando Midtrans lo conferma. Finché il pagamento non è confermato, la pagina mostra We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. La pagina mostra anche il metodo di pagamento utilizzato.
Se il pagamento non è stato completato, il cliente viene inviato alla pagina Pay for order con The Midtrans payment was not completed. You can try again below. Se è stato rifiutato o è scaduto, il messaggio è Your Midtrans payment was declined or has expired. Please try again or choose another payment method. Quando il cliente paga di nuovo, viene riutilizzato uno Snap non utilizzato o in sospeso per lo stesso importo. Se l'importo è cambiato, la transazione in sospeso viene prima fatta scadere presso Midtrans. Se nel frattempo lo Snap precedente è stato pagato, l'ordine viene confermato e non viene creata alcuna nuova transazione.
Se Midtrans non riesce ad avviare il pagamento, il cliente vede Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (per esempio con una Server Key errata) oppure il motivo indicato da Midtrans. Il motivo tecnico viene aggiunto alle note dell'ordine.
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).
Il plugin usa solo Snap Redirect. Non ha finestra pop-up Snap, né modulo carta sul tuo sito, né carte salvate o pagamenti con un clic, né impostazioni di rate o promozioni (i metodi di pagamento si configurano nella dashboard di Midtrans), né WooCommerce Subscriptions. I pagamenti con carta vengono acquisiti immediatamente, senza autorizzazione e cattura separate.
Ordini e rimborsi
Stati dell'ordine
Pending payment: il cliente è stato inviato a Midtrans e non ha ancora scelto un metodo di pagamento.
On hold: il cliente ha scelto un metodo differito e non ha ancora pagato, il pagamento con carta è in verifica antifrode (challenge), oppure l'importo o la valuta pagati non corrispondono all'ordine. In attesa viene impostato anche quando arriva un pagamento per un ordine annullato; l'ordine non viene riaperto automaticamente. La nota dell'ordine lo spiega.
Processing, Completed or On hold after payment: il pagamento è stato confermato. Lo stato segue Status after payment. La nota dell'ordine mostra il metodo di pagamento e gli ID Midtrans. L'ID transazione è l'ID transazione Midtrans e, nella schermata dell'ordine, rimanda alla transazione nella dashboard Midtrans dell'ambiente dell'ordine.
Failed: il pagamento non è riuscito, oppure un pagamento con carta in challenge è stato rifiutato.
Cancelled: la transazione non pagata è scaduta o è stata annullata. Le scorte vengono restituite. Quando annulli in WooCommerce un ordine Midtrans non pagato (o lo fa il timer degli ordini non pagati), la sua transazione Midtrans in sospeso, per esempio un conto virtuale emesso, viene fatta scadere così non può più essere pagata.
Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato di nuovo. Una nota ti chiede di rimborsare il secondo pagamento nella dashboard di Midtrans. Un pagamento per un ordine rimborsato aggiunge solo una nota.
Rimborsi
Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Midtrans (il pulsante mostra il tuo Title). I rimborsi totali e parziali sono supportati in rupie intere; un importo con decimali viene rifiutato. Il rimborso viene inviato nell'ambiente in cui l'ordine è stato pagato, quindi la Server Key di quell'ambiente deve essere impostata. Midtrans consente i rimborsi via API solo per alcuni metodi di pagamento e stati di transazione (per esempio pagamenti con carta regolati, GoPay, QRIS o ShopeePay). Se Midtrans non accetta il rimborso, WooCommerce mostra l'errore e non viene registrato alcun rimborso; in tal caso rimborsa dalla dashboard di Midtrans. Un rimborso riuscito viene aggiunto alle note dell'ordine.
I rimborsi effettuati nella dashboard di Midtrans arrivano con la notifica e vengono registrati automaticamente come rimborsi WooCommerce, con il motivo Refunded in the Midtrans dashboard.
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 > Midtrans. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva e il tuo dominio. Usa Check now per verificare 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 dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Midtrans 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 Plugin e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: 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 verificato di nuovo automaticamente in background.
Risoluzione dei problemi
Midtrans non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la Environment selezionata abbia la sua Server Key. Verifica che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia IDR. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.
Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: la notifica non funziona. Verifica che l'URL di notifica del pagamento sia impostato nella dashboard di Midtrans dell'ambiente che usi (sandbox o produzione) e che sia raggiungibile: aprilo in un browser, compare una breve spiegazione. Attiva il Debug log per vedere le notifiche. L'ordine viene confermato anche quando il cliente torna nel negozio dopo aver pagato.
La notifica risponde Invalid signature: la notifica non è stata firmata con la tua Server Key Sandbox o Production. Verifica che le chiavi nelle impostazioni appartengano allo stesso account Midtrans della dashboard che invia le notifiche.
La notifica risponde Server key not configured: non è impostata nessuna Server Key. Inseriscila nelle impostazioni; Midtrans ripete la notifica.
La notifica risponde Order not found — ignored: l'ID ordine Midtrans non appartiene a un ordine di questo negozio, per esempio proviene da un altro negozio sullo stesso account Midtrans. Assegna a ogni negozio un Order ID prefix diverso.
La notifica risponde Environment mismatch — ignored: la notifica è stata firmata con la chiave di un ambiente diverso da quello in cui l'ordine è stato pagato.
La notifica risponde Verification failed, please retry: non è stato possibile raggiungere le API di stato di Midtrans. Midtrans ripete la notifica.
L'ordine è On hold: leggi la nota dell'ordine. Il cliente non ha completato un pagamento differito, il pagamento con carta è in verifica antifrode, oppure l'importo o la valuta pagati non corrispondono all'ordine.
Il cliente vede un errore quando effettua l'ordine: apri le note dell'ordine oppure attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_midtrans_payment_gateway. Un ordine non in IDR mostra Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.
Il rimborso non riesce: il metodo di pagamento o lo stato della transazione non consente rimborsi via API; rimborsa dalla dashboard di Midtrans, il rimborso verrà registrato automaticamente in WooCommerce. Se il messaggio indica che nessuna Server Key è configurata per l'ambiente in cui l'ordine è stato pagato, inserisci quella chiave e riprova.
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 per il 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 dalla pagina Plugins. La chiave di licenza e lo stato di 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 successiva reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.
Midtrans è un marchio del rispettivo titolare. Questo plugin non è affiliato a Midtrans né approvato da Midtrans.