VibeFox MakeCommerce 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.

Accesso a Internet al tuo negozio: MakeCommerce invia le notifiche di pagamento al tuo negozio, quindi il sito deve essere raggiungibile da Internet. Un firewall o l'autenticazione di base possono bloccarle. La modalità manutenzione e la restrizione per paese del negozio non le bloccano.

Account MakeCommerce: ti servono lo Shop ID e la Secret key dal Merchant Portal di MakeCommerce (Settings > API). Gli ambienti di test e di produzione hanno account e chiavi separati. I metodi di pagamento e le valute disponibili sono definiti dal tuo contratto MakeCommerce. Non vengono offerte valute con tre decimali, come KWD o BHD.

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 in seguito VibeFox MakeCommerce Payment nell'elenco dei moduli e fai clic su Configure.

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

4. Inserisci lo Shop ID e la Secret key dell'ambiente di test e, per i pagamenti reali, le chiavi di produzione (vedi Configurazione). Non serve configurare nulla nel Merchant Portal.

5. Attiva Enable/Disable e fai clic su Save. Prova un pagamento con Test mode attivo, poi disattivalo per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine MakeCommerce payment on hold. PrestaShop offre il 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 MakeCommerce Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged. finché la modalità test è attiva. Avvisa quando il metodo è abilitato ma lo Shop ID o la Secret key dell'ambiente corrente sono vuoti, e quando la valuta predefinita del negozio non può essere addebitata da MakeCommerce. In entrambi i casi il metodo viene nascosto nel checkout. Al salvataggio, gli spazi vengono rimossi dalle chiavi.

MakeCommerce

Enable/Disable: Enable MakeCommerce payments attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede nel checkout. È anche il nome del metodo di pagamento memorizzato nell'ordine. Predefinito: Bank link or card (MakeCommerce). Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento nel checkout. Predefinito: Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

Account MakeCommerce

Lo Shop ID e la Secret key si trovano nel Merchant Portal di MakeCommerce, alla voce Settings > API. Il portale di test e quello di produzione hanno account e chiavi separati. La sezione contiene link a entrambi i portali e alla pagina di registrazione di MakeCommerce.

Test mode: usa l'ambiente di test di MakeCommerce (non viene addebitato denaro reale). I nuovi pagamenti vengono creati nell'ambiente selezionato con le sue chiavi. Ogni ordine ricorda l'ambiente in cui è stato pagato: i controlli di stato e i rimborsi vanno sempre lì. Quando è attivo, i clienti vedono TEST MODE — MakeCommerce test environment, no real money is charged. sotto il metodo di pagamento. Predefinito: attivo.

Test Shop ID: lo Shop ID del tuo account di test, nel formato xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Test Secret key: la Secret key del tuo account di test.

Live Shop ID: lo Shop ID del tuo account di produzione.

Live Secret key: la Secret key del tuo account di produzione.

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

Clear saved secret keys: spunta una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notifiche di pagamento

Non serve configurare nulla nel Merchant Portal. Callback URLs mostra, a titolo di riferimento, l'indirizzo per il ritorno o l'annullamento del cliente e l'indirizzo per le notifiche di pagamento. Ogni transazione include i propri URL di ritorno, annullamento e notifica, costruiti a partire da questi indirizzi con il numero del carrello e una chiave aggiunta. MakeCommerce invia un messaggio firmato all'URL di notifica (da server a server) e, tramite il browser del cliente, all'URL di ritorno o annullamento. La firma viene verificata con la Secret key dell'ambiente in cui è stata creata la transazione. I messaggi senza una firma valida vengono rifiutati.

Il modulo gestisce questi stati delle transazioni MakeCommerce:

Il pagamento viene confermato anche quando il cliente torna nel negozio. Se il cliente torna senza un messaggio firmato, il modulo chiede lo stato all'API di MakeCommerce.

Avanzate

Debug log: registra le chiamate API e le notifiche di pagamento in logs/wc_mkc_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: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo e il registro. Gli ordini e i relativi dati di pagamento MakeCommerce vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Bank link or card (MakeCommerce)) e conferma. Il modulo crea una transazione MakeCommerce per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento di MakeCommerce. Lì il cliente sceglie un link bancario o una carta. L'e-mail e il paese del cliente vengono trasmessi a MakeCommerce, e la pagina si apre nella lingua del negozio quando MakeCommerce la supporta (estone, inglese, lettone, lituano, finlandese, russo, tedesco, polacco), altrimenti in inglese. A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna nel tuo negozio. L'ordine viene contrassegnato come pagato solo dopo che MakeCommerce lo ha confermato: tramite la notifica firmata o il ritorno firmato del cliente, con una verifica della transazione tramite l'API di MakeCommerce. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your MakeCommerce payment has been received. Se l'ordine è stato messo in attesa per una verifica, la pagina mostra Your MakeCommerce payment was received and is being reviewed by the shop.

Se il pagamento è approvato ma non ancora completato, oppure MakeCommerce non è raggiungibile, una pagina Payment confirmation mostra We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. con i pulsanti Check again e Back to checkout. La notifica crea l'ordine non appena il pagamento è completato.

Se il cliente annulla nella pagina di MakeCommerce oppure il pagamento scade o non riesce, il cliente torna al checkout con un messaggio, ad esempio The payment was cancelled. You can try again or choose another payment method., The payment session expired. Please try again. o The payment was not completed. Please try again or choose another payment method. Il carrello viene conservato e il cliente può pagare di nuovo. Ogni tentativo è una nuova transazione MakeCommerce. Un link di pagamento precedente dello stesso carrello funziona ancora, e il carrello non può essere pagato due volte in due ordini.

Se MakeCommerce non riesce ad avviare il pagamento, il cliente resta nel checkout con MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. oppure MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. Il motivo tecnico viene scritto nel registro.

La banca o la carta viene scelta sulla pagina di MakeCommerce, non nel tuo checkout. Il modulo non prevede carte salvate, pagamenti ricorrenti o abbonamenti e non include le spedizioni di MakeCommerce (armadietti per pacchi, etichette).

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a MakeCommerce e non ha ancora pagato, oppure MakeCommerce non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted: il pagamento è stato confermato. Il pagamento viene registrato con l'ID della transazione MakeCommerce, e una nota mostra l'importo, la transazione, l'ambiente e come è stato verificato (API di MakeCommerce o notifica firmata).

MakeCommerce payment on hold: l'importo o la valuta pagati differivano dal carrello (ad esempio, il carrello è stato modificato dopo l'avvio del pagamento), l'importo mancava, la transazione su MakeCommerce non era ancora definitiva sebbene segnalata come completata, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota lo spiega. Se la valuta pagata è quella dell'ordine, nell'ordine viene registrato l'importo effettivamente pagato. Una transazione con una mancata corrispondenza non paga mai l'ordine in seguito; una transazione non ancora definitiva completa l'ordine quando MakeCommerce la segnala come completata. Verifica la transazione nel Merchant Portal, poi evadi l'ordine o rimborsa il pagamento.

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

Se arriva un secondo pagamento per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nel Merchant Portal di MakeCommerce.

Blocco pagamento MakeCommerce

La pagina dell'ordine mostra un blocco MakeCommerce payment con tutte le transazioni MakeCommerce del carrello (data, ID della transazione, un badge Test per i pagamenti di prova, importo, stato e risultato di MakeCommerce), gli importi pagati e rimborsati, lo storico dei rimborsi e le MakeCommerce notes dell'ordine. I pulsanti del blocco richiedono solo il permesso di modificare gli ordini, non l'accesso ai moduli.

Check MakeCommerce payment status: chiede all'API di MakeCommerce lo stato delle transazioni del carrello (le più recenti per prime), lo applica e aggiunge una nota con il risultato. Usalo quando un cliente dice di aver pagato ma l'ordine non è stato completato.

Rimborsi

Nel blocco MakeCommerce payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via MakeCommerce. Conferma la domanda Refund this amount via MakeCommerce? Sono supportati rimborsi totali e parziali. I rimborsi sono limitati all'importo e alla valuta della transazione MakeCommerce, quindi dopo una mancata corrispondenza dell'importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato all'ambiente in cui il pagamento è stato effettuato (test o produzione), quindi le chiavi di quell'ambiente devono essere impostate. Il motivo viene inviato a MakeCommerce come commento del rimborso; senza motivo il commento è Refund for order seguito dal riferimento dell'ordine. Se MakeCommerce non accetta il rimborso, il blocco mostra l'errore, viene aggiunta una nota e nessun rimborso viene registrato. Se MakeCommerce sta ancora elaborando il pagamento, il messaggio è MakeCommerce is still processing this payment — try the refund again later. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con l'ID del rimborso MakeCommerce. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili una volta che MakeCommerce ha confermato il pagamento.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite MakeCommerce.

I rimborsi effettuati nel Merchant Portal arrivano con lo stato della transazione e vengono aggiunti alle note. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox MakeCommerce Payment è il primo blocco di Modules > Module Manager > VibeFox MakeCommerce Payment > Configure, sopra le impostazioni. Incolla la chiave in License key e clicca su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino a cui 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 ci sono la riga Product: presta-payment-makecommerce 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, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure 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, 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 slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, MakeCommerce non viene mostrato ai clienti nel checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. La vetrina di PrestaShop non sa che sei connesso 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 nel 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 reimpostare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

MakeCommerce non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che l'ambiente corrente abbia le sue chiavi: Test Shop ID e Test Secret key in modalità test, Live Shop ID e Live Secret key in modalità produzione. Verifica che la valuta del carrello abbia al massimo due decimali. 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 non è stato creato alcun ordine: le notifiche non sono riuscite a raggiungere il negozio, ad esempio a causa di un firewall o dell'autenticazione di base. L'ordine viene creato anche quando il cliente torna nel negozio o fa clic su Check again. Verifica che siano impostate le chiavi dell'ambiente in cui il pagamento è stato effettuato: la notifica viene verificata con la Secret key di quell'ambiente e, senza di essa, MakeCommerce riceve un errore e riprova. Attiva Debug log per vedere le notifiche.

L'ordine è in MakeCommerce payment on hold: leggi le MakeCommerce notes nel blocco nella pagina dell'ordine (vedi Stati dell'ordine), verifica la transazione nel Merchant Portal, poi evadi l'ordine o rimborsa il pagamento.

Le notifiche vengono rifiutate: un messaggio con firma errata, per un altro carrello, un altro negozio o una transazione non creata per il carrello viene rifiutato e non cambia nulla. Verifica che lo Shop ID e la Secret key appartengano allo stesso account e allo stesso ambiente di MakeCommerce.

Il cliente vede un errore quando sceglie MakeCommerce: attiva Debug log e controlla il campo Log nella pagina del modulo. Una valuta che MakeCommerce non può addebitare produce MakeCommerce cannot process payments in seguito dal codice della valuta.

Il rimborso non riesce con un messaggio sull'ambiente: l'ordine è stato pagato nell'ambiente di test o di produzione, e le chiavi di quell'ambiente non sono configurate. Inseriscile e riprova.

Il rimborso non riesce con No MakeCommerce transaction ID found for this order: l'ordine non ha un pagamento MakeCommerce confermato. Rimborsalo nel Merchant Portal.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox MakeCommerce Payment e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data è attivo, vengono rimosse le impostazioni del modulo e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. Le transazioni e i rimborsi MakeCommerce e lo stato dell'ordine MakeCommerce payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID delle transazioni.

MakeCommerce è un marchio del rispettivo titolare. Questo modulo non è affiliato a MakeCommerce né approvato da MakeCommerce.