VibeFox Midtrans for PrestaShop — Guida
Requisiti
PrestaShop: da 8.0 a 9.x.
PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.
Valuta: rupia indonesiana (IDR). Midtrans addebita solo in IDR, quindi il metodo di pagamento viene proposto solo quando la valuta del carrello è IDR. Non c'è conversione di valuta. Aggiungi la valuta IDR in International > Localization se il tuo negozio non l'ha già.
Account Midtrans: ti serve la Server Key da Midtrans Dashboard > Settings > Access Keys, sia nella dashboard sandbox sia in quella 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 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 Midtrans Payment Gateway nell'elenco dei moduli e fai clic su Configure.
3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e fai clic su Activate (vedi Chiave di licenza).
4. Inserisci le Server Key e copia l'URL di notifica del pagamento nella dashboard di Midtrans (vedi Configurazione).
5. Attiva Enable/Disable e fai clic su Save. Prova in Sandbox, poi imposta Environment su Production.
All'installazione il modulo crea due stati dell'ordine: Awaiting Midtrans payment e Midtrans payment on hold. PrestaShop propone un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences. Il modulo deve restare consentito per la valuta IDR.
Configurazione
Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi, la pagina ti avvisa se manca la Server Key dell'ambiente selezionato (in quel caso il metodo di pagamento viene nascosto al checkout) e se la valuta predefinita del negozio non è IDR, e mostra Sandbox mode: payments are simulated, no real money is charged. mentre è selezionato Sandbox.
Midtrans
Enable/Disable: Enable Midtrans payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il titolo del metodo di pagamento mostrato ai clienti al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Midtrans. Obbligatorio.
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. I pagamenti mantengono l'ambiente in cui sono stati effettuati, per rimborsi e notifiche. Predefinito: Sandbox.
Production Server Key: inizia con Mid-server-. Tienila riservata.
Sandbox Server Key: inizia con SB-Mid-server-.
Le chiavi salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarla.
Clear saved keys: spunta una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.
URL di notifica del pagamento
La notifica comunica al tuo negozio che un pagamento è stato effettuato. Il campo Notification URL mostra l'URL da usare. Con URL semplificati ha questo aspetto: https://your-shop/module/wcp_midtrans_payment_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni e 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 riceve una risposta.
Ogni notifica deve contenere una firma valida fatta con una delle tue Server Key, e l'ambiente della chiave deve corrispondere a quello del pagamento. Le notifiche senza firma valida vengono rifiutate. Lo stato viene quindi riletto dalle API di stato di Midtrans. Il modulo gestisce questi stati di transazione Midtrans:
Senza l'URL di notifica, un ordine viene creato solo quando il cliente torna nel negozio dopo aver pagato, e un pagamento differito effettuato più tardi non viene rilevato finché il cliente non torna.
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, a Midtrans viene inviata una riga Rounding adjustment.
Status after payment: lo stato dell'ordine dopo un pagamento confermato.
Payment page expiry (minutes): per quanto tempo il cliente può pagare (pagina Snap, conto virtuale e così via). Lascia vuoto o imposta 0 per il valore predefinito di Midtrans. Un valore che non sia un numero intero di minuti viene rifiutato con un errore al salvataggio.
Order ID prefix: aggiunto al numero inviato a Midtrans, così più negozi possono condividere un account Midtrans. Il numero è l'ID del carrello con un timestamp, ad esempio WC-123-1700000000. 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: scrive le chiamate API e le notifiche in logs/midtrans_p_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. Chiavi e dati dei clienti non vengono mai registrati. Predefinito: disattivato.
Log: mostra la dimensione e le ultime voci del registro. Fai clic su Clear log per svuotarlo.
Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le sue impostazioni e il registro. Gli ordini, i loro riferimenti di pagamento Midtrans e i rimborsi e gli stati dell'ordine del modulo restano sempre, così gli ordini vecchi si possono rimborsare anche dopo una reinstallazione. Predefinito: disattivato.
Checkout
Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Midtrans) e conferma. Il modulo crea una transazione Midtrans Snap per il totale del carrello in rupie intere, con le righe dell'ordine, la spedizione, gli sconti, la confezione regalo, 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. A questo punto non esiste ancora alcun ordine.
Dopo il pagamento il cliente torna nel tuo negozio. Il link di ritorno non segna mai un ordine come pagato: l'ordine viene segnato come pagato solo quando Midtrans lo conferma, con la notifica firmata o con una richiesta alle API di stato di Midtrans quando il cliente torna. L'ordine viene quindi creato e il cliente vede la normale pagina di conferma dell'ordine con il metodo di pagamento usato. Per un pagamento differito 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. Per un ordine chiuso senza pagamento mostra Your Midtrans payment was not completed. Please contact us about this order. Se Midtrans non è raggiungibile quando il cliente torna, una pagina Payment confirmation mostra We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. con un pulsante Check again.
Se il cliente ha lasciato la pagina Snap senza pagare, torna al checkout con il messaggio The Midtrans payment was not completed. You can try again below. Se il pagamento è stato rifiutato o è scaduto, il messaggio è Your Midtrans payment was declined or has expired. Please try again or choose another payment method. Il carrello viene conservato. 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 su Midtrans. Se nel frattempo lo Snap precedente è stato pagato, l'ordine viene creato e non viene avviata alcuna nuova transazione. Se l'ordine esiste già ed è stato chiuso senza pagamento, il messaggio è Your Midtrans payment was declined or has expired. Please place a new order or contact us.
Se Midtrans non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio: Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (ad esempio con una Server Key errata) oppure il motivo indicato da Midtrans. Il motivo tecnico viene scritto nel registro. Un carrello non in IDR mostra Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.
La notifica funziona anche quando il negozio è in modalità manutenzione e non viene bloccata dalla restrizione per paese del tuo negozio.
Il modulo 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 (configura i metodi di pagamento nella dashboard di Midtrans), né abbonamenti. I pagamenti con carta vengono catturati subito, senza autorizzazione e cattura separate.
Ordini e rimborsi
Stati dell'ordine
No order yet: il cliente è stato inviato a Midtrans e non ha pagato, oppure Midtrans non ha ancora confermato il pagamento. Esiste solo il carrello.
Awaiting Midtrans payment: il cliente ha scelto un metodo differito (conto virtuale, punto vendita di prossimità) oppure ha avviato un pagamento con carta non ancora completato. L'ordine diventa pagato quando Midtrans segnala il pagamento.
Payment accepted, Delivered o Midtrans payment on hold: il pagamento è stato confermato. Lo stato segue Status after payment. Il pagamento viene registrato con l'ID transazione Midtrans, e una nota mostra il metodo di pagamento e l'ID ordine Midtrans.
Midtrans payment on hold: viene impostato anche quando un pagamento con carta è in verifica antifrode (challenge, nessun pagamento ancora registrato), quando l'importo o la valuta pagati non corrispondono all'ordine (l'ordine non viene segnato come pagato) o quando arriva un pagamento per un ordine annullato (l'ordine non viene riaperto automaticamente). La nota lo spiega. Controlla l'ordine, poi evadilo oppure rimborsa il pagamento.
Canceled: la transazione non pagata è scaduta o è stata annullata. Quando annulli tu un ordine Midtrans non pagato, la sua transazione Midtrans in sospeso, ad esempio un conto virtuale emesso, viene fatta scadere così non può più essere pagata.
Payment error: il pagamento non è riuscito, oppure un pagamento con carta sottoposto a verifica è stato rifiutato.
Refunded: il pagamento è stato rimborsato integralmente.
Se arriva un secondo pagamento per un ordine già pagato, l'ordine non cambia. Una nota ti chiede di rimborsare il secondo pagamento nella dashboard di Midtrans. Un pagamento per un ordine rimborsato aggiunge solo una nota.
Blocco pagamento Midtrans
La pagina dell'ordine mostra un blocco Midtrans payment con l'ID ordine Midtrans, l'ID transazione (collegato alla transazione nella dashboard Midtrans dell'ambiente del pagamento), il metodo di pagamento, lo stato, l'importo pagato e rimborsato, un badge Sandbox per i pagamenti sandbox, lo storico dei rimborsi e le Midtrans notes dell'ordine.
Rimborsi
Nel blocco Midtrans payment inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Midtrans. Conferma la domanda Refund this amount through Midtrans? This cannot be undone. Sono supportati rimborsi totali e parziali in rupie intere; un importo con decimali viene rifiutato. Ti serve il permesso di modificare gli ordini. Puoi rimborsare fino all'importo effettivamente addebitato da Midtrans, anche se l'ordine è stato modificato in seguito. Il rimborso viene inviato nell'ambiente in cui è stato effettuato il pagamento, quindi deve essere impostata la Server Key di quell'ambiente. Midtrans consente rimborsi via API solo per alcuni metodi di pagamento e stati di transazione (ad esempio pagamenti con carta regolati, GoPay, QRIS o ShopeePay). Se Midtrans non accetta il rimborso, il blocco mostra l'errore e nessun rimborso viene registrato; in tal caso rimborsa dalla dashboard di Midtrans. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili quando Midtrans ha segnalato il pagamento come regolato.
Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Midtrans.
I rimborsi effettuati nella dashboard di Midtrans arrivano tramite la notifica e vengono aggiunti automaticamente allo storico dei rimborsi, con il motivo Refunded in the Midtrans dashboard. Quando lì viene rimborsato l'intero pagamento, l'ordine passa in Refunded.
Chiave di licenza
Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Midtrans Payment Gateway è il primo blocco di Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Poi 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 verificare 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-midtrans 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 cambiare 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 o License expired on seguito da una data. Dopo che l'indirizzo del negozio cambia, o dopo che liberi uno slot di 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: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.
Senza una chiave attiva, Midtrans non viene mostrato ai clienti al checkout. Se comunque viene avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per 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 e i rimborsi funzionano.
Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un 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 a settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.
Risoluzione dei problemi
Midtrans does not appear at checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che l'Environment selezionato abbia la sua Server Key. Verifica che la valuta del carrello sia IDR. In Payment > Preferences verifica che il modulo sia consentito per IDR, per il paese del cliente e per il gruppo del cliente. La pagina delle impostazioni mostra un avviso quando la chiave manca o la valuta del negozio non è IDR.
The payment went through, but no order was created: 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), che sia esattamente l'URL mostrato in Notification URL e che sia raggiungibile: aprilo in un browser, deve comparire una breve spiegazione. Attiva Debug log per vedere le notifiche. L'ordine viene creato anche quando il cliente torna nel negozio dopo aver pagato.
Notification answers Invalid signature: la notifica non è stata firmata con la tua Server Key Sandbox o di Production. Verifica che le chiavi nelle impostazioni appartengano allo stesso account Midtrans della dashboard che invia le notifiche.
Notification answers Server key not configured: nessuna Server Key è impostata. Inseriscila nelle impostazioni; Midtrans ripete la notifica.
Notification answers Order not found — ignored: l'ID ordine Midtrans non è stato emesso da questo negozio, ad esempio da un altro negozio sullo stesso account Midtrans. Assegna a ogni negozio un Order ID prefix diverso.
Notification answers Environment mismatch — ignored: la notifica è stata firmata con la chiave dell'altro ambiente rispetto a quello in cui è stato effettuato il pagamento.
Notification answers Verification failed, please retry: le API di stato di Midtrans non sono raggiungibili. Midtrans ripete la notifica.
Notification answers Busy, please retry: il carrello era in aggiornamento da un'altra richiesta nello stesso momento, oppure l'ordine non è stato possibile crearlo (ad esempio perché il modulo è disattivato). Midtrans ripete la notifica. Controlla il registro per il motivo.
The order is Midtrans payment on hold: leggi le Midtrans notes nel blocco. Il pagamento con carta è in verifica antifrode, l'importo o la valuta pagati non corrispondono all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine.
The customer sees an error when choosing Midtrans: controlla il campo Log nella pagina del modulo; gli errori vengono sempre registrati. Una Server Key errata mostra il messaggio che i pagamenti Midtrans sono temporaneamente non disponibili.
Refund fails: il metodo di pagamento o lo stato della transazione non consente rimborsi via API; rimborsa dalla dashboard di Midtrans, e il rimborso verrà registrato automaticamente sull'ordine. Se il messaggio dice che per l'ambiente in cui l'ordine è stato pagato non è impostata alcuna Server Key, inserisci quella chiave e riprova.
Gli sviluppatori possono modificare i dati inviati a Midtrans con l'hook actionWcpMidtransSnapPayload; l'ID ordine e l'importo non possono essere modificati.
Disinstallazione
Vai su Modules > Module Manager, apri il menu accanto a VibeFox Midtrans 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 registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I riferimenti di pagamento Midtrans e i rimborsi degli ordini, insieme agli stati dell'ordine Awaiting Midtrans payment e Midtrans payment on hold, restano sempre, così gli ordini pagati in precedenza si possono rimborsare dopo una reinstallazione. Gli ordini esistenti mantengono le loro note di pagamento e gli ID transazione.
Midtrans è un marchio del rispettivo titolare. Questo modulo non è affiliato né approvato da Midtrans.