# Gateway Mollie Terminal Il gateway Mollie Terminal consente di accettare pagamenti in presenza sull'hardware [Mollie Terminal](https://www.mollie.com/products/point-of-sale) direttamente da WCPOS. Un pagamento viene avviato da WooCommerce e completato sul terminale, quindi la conferma di Mollie viene registrata nell'ordine. ## Funzionalità[​](#features "Collegamento diretto a Funzionalità") #### Integrazione hardware Invia pagamenti ai terminali Mollie registrati sul tuo account Mollie e accetta pagamenti con carta presente #### Nessun abbinamento manuale I terminali vengono recuperati in tempo reale dal tuo account Mollie: selezionane uno da un menu a discesa, senza dover incollare l'ID del dispositivo #### Completamento affidabile I pagamenti vengono confermati tramite polling di Mollie e il POS reindirizza automaticamente alla ricevuta quando il terminale conferma #### Transazioni sicure Elaborazione conforme a PCI delle transazioni con carta gestita sull'hardware Mollie #### Rimborsi supportati Rimborsi dalla schermata dell'ordine WooCommerce, riconciliati con Mollie per evitare duplicazioni ## Come funziona[​](#how-it-works "Collegamento diretto a Come funziona") Mollie Terminal usa i **pagamenti `pointofsale` lato server** di Mollie. Quando si avvia un pagamento, WooCommerce crea un pagamento Mollie per l'ordine e Mollie lo invia al terminale selezionato. Il cliente paga sul dispositivo e **Mollie è la fonte di verità** per lo stato dei pagamenti e dei rimborsi — i meta locali dell'ordine WooCommerce sono solo una cache. **Come viene confermato un pagamento.** Mentre il pagamento è in corso, il POS interroga Mollie (ogni 2 secondi per impostazione predefinita) e, quando il terminale conferma, reindirizza direttamente alla pagina di ringraziamento. I webhook Mollie vengono utilizzati anche per velocizzare il processo — l'URL del webhook viene impostato automaticamente per ogni pagamento, quindi non c'è **nulla da configurare nel pannello di controllo Mollie**. Il terminale deve essere registrato e attivo nello stesso account Mollie del plugin. ## Configurazione[​](#setup "Collegamento diretto a Configurazione") 1 #### Installa Mollie Terminal per WooCommerce Installalo da `WP Admin > POS > Impostazioni > Estensioni`, oppure scarica l'ultima **risorsa ZIP del plugin** (non il file ZIP del codice sorgente GitHub né il tarball) dalla [pagina delle release di GitHub](https://github.com/wcpos/mollie-terminal-for-woocommerce/releases) e caricalo tramite `Plugin > Aggiungi Nuovo > Carica plugin`. 2 #### Configura le credenziali Mollie 1. Vai in `WP Admin > WooCommerce > Impostazioni > Pagamenti` e apri **Mollie Terminal** 2. Imposta **Modalità** su `Test` per un pagamento simulato tramite terminale di prova oppure su `Live` per un terminale reale 3. Imposta **Origine della chiave API** per riutilizzare la chiave del plugin Mollie ufficiale oppure usare la chiave inserita in questa schermata 4. Se inserisci qui la chiave, incolla la chiave API di test o live corrispondente alla modalità selezionata in **Chiave API Mollie** 5. Salva Eseguire test prima di passare alla modalità live Mollie offre un terminale simulato per i pagamenti di prova `pointofsale`. Usa la modalità `Live` solo quando sei pronto a inviare pagamenti a un terminale fisico o iOS/Android. Consulta [Ambito e limitazioni](#scope-and-limitations) per il flusso di test attuale. Non è necessario un ID profilo I pagamenti `pointofsale` non richiedono un **ID profilo** Mollie e i terminali sono elencati per l'intero account, quindi non è necessario incollare altro. 3 #### Scegli i terminali 1. Seleziona un **Terminale predefinito** dal menu a discesa. L'elenco viene recuperato dall'ambiente Mollie selezionato — i terminali inattivi sono nascosti, perché Mollie non può riattivarli. 2. *(Facoltativo)* Limita i **Terminali abilitati** ai dispositivi effettivamente in uso. Il terminale predefinito salvato rimane disponibile anche se non è selezionato qui; lascia vuota l'impostazione per consentire tutti i terminali attivi. Per dismettere un terminale, modifica o cancella anche **Terminale predefinito**. 3. *(Facoltativo)* Abilita **Blocca selezione terminale** affinché i cassieri non possano cambiare il terminale al momento del pagamento: viene sempre usato il terminale predefinito e questa impostazione viene applicata anche sul server. 4. Salva 4 #### Abilita in WCPOS 1. Vai a `WP Admin > POS > Impostazioni > Pagamento` 2. Trova il gateway **Mollie Terminal** e abilitalo per il POS 3. Salva le impostazioni nota La casella di controllo **Abilita/Disabilita** nella schermata delle impostazioni di WooCommerce controlla solo il checkout del *negozio online*. WCPOS utilizza questo gateway dopo la configurazione, indipendentemente dal fatto che la casella sia selezionata. ## Riferimento impostazioni[​](#settings "Collegamento diretto a Riferimento impostazioni") | Impostazione | Descrizione | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Abilita/Disabilita** | Abilita il gateway per il checkout del negozio online (non richiesto per POS) | | **Titolo** / **Descrizione** | Etichetta e testo mostrati al cliente al momento del checkout | | **Modalità** | `Test` utilizza il terminale di prova simulato di Mollie; `Live` invia i pagamenti a un terminale reale | | **Origine della chiave API** | Utilizza la chiave inserita di seguito oppure riutilizza la chiave di prova/reale corrispondente del plugin ufficiale Mollie Payments for WooCommerce. Se la chiave condivisa non è disponibile, il plugin utilizza la chiave riportata di seguito | | **Chiave API Mollie** | La chiave API di prova o reale per la modalità selezionata. Viene utilizzata quando **Origine della chiave API** è impostata sulla chiave inserita qui e come fallback in caso di chiave condivisa mancante | | **Terminale predefinito** | Il terminale utilizzato per impostazione predefinita al checkout, scelto da un menu a discesa dei terminali attivi nell'ambiente Mollie selezionato | | **Terminali abilitati** | Limita l'elenco al checkout ai terminali selezionati. Vuoto = tutti i terminali attivi. Il terminale predefinito salvato è sempre disponibile; modificare o cancellare anche quello quando si dismette un terminale | | **Blocca la selezione del terminale** | Impone il terminale predefinito al checkout, in modo che i cassieri non possano modificarlo (richiede un terminale predefinito) | | **Registri di debug del checkout** | Mostra gli strumenti **Mostra registri**, **Copia** e **Cancella** nel pannello di pagamento del checkout. Lasciare questa opzione disattivata, a meno che non si raccolgano registri per l'assistenza; l'attività di pagamento viene sempre registrata in `WooCommerce > Status > Log` | L'URL del webhook viene applicato automaticamente a ogni pagamento, quindi non è necessario compilare alcun campo webhook né configurare il pannello di controllo Mollie. ## Utilizzo[​](#usage "Collegamento diretto a Utilizzo") ### Elaborazione dei pagamenti[​](#processing-payments "Collegamento diretto a Elaborazione dei pagamenti") 1. **Aggiungi articoli**: aggiungi prodotti al carrello nel POS 2. **Seleziona gateway**: scegli "Mollie Terminal" come metodo di pagamento 3. **Scegli terminale**: seleziona un terminale dall'elenco a discesa (per impostazione predefinita viene usato quello configurato; nascosto se la selezione del terminale è bloccata) 4. **Avvia pagamento**: fai clic su **Avvia pagamento sul terminale** — Mollie invia il pagamento al dispositivo 5. **Pagamento del cliente**: il cliente avvicina, inserisce o passa la propria carta sul terminale. Lo stato si aggiorna in tempo reale — `Sending to terminal…` → `Waiting for terminal…` 6. **Completamento automatico**: quando il terminale conferma, l'ordine viene contrassegnato come pagato e il POS reindirizza automaticamente alla ricevuta ### Controlli di pagamento[​](#payment-controls "Collegamento diretto a Controlli di pagamento") * **Avvia pagamento sul terminale**: invia una nuova richiesta di pagamento al terminale selezionato * **Annulla pagamento**: annulla un pagamento ancora aperto. Quando il pagamento ha raggiunto il terminale, Mollie segnala che non è più annullabile e il cassiere lo annulla direttamente sul dispositivo ### Gestione ordini[​](#order-management "Collegamento diretto a Gestione ordini") * **Completamento verificato**: ogni webhook, controllo periodico, annullamento e nuovo tentativo recupera lo stato Mollie autorevole prima di modificare un ordine, quindi gli ordini vengono contrassegnati come pagati solo in base a uno stato Mollie confermato * **Monitoraggio pagamenti**: i tentativi di pagamento vengono registrati come cronologia di sola aggiunta nell'ordine * **Generazione delle ricevute**: le ricevute POS standard vengono generate dopo i pagamenti riusciti ## Rimborsi[​](#refunds "Collegamento diretto a Rimborsi") I rimborsi sono supportati. Rimborsare un ordine dalla normale schermata dell'ordine di WooCommerce e il rimborso viene inviato a Mollie. Poiché Mollie è la fonte di riferimento, i tentativi ripetuti di rimborso vengono riconciliati con gli ID e i metadati dei rimborsi di Mollie **prima** di creare un altro rimborso, in modo che un rimborso non venga mai emesso accidentalmente due volte. ## Pulizia dei pagamenti inattivi[​](#stale-payment-cleanup "Collegamento diretto a Pulizia dei pagamenti inattivi") Un pagamento Mollie `pointofsale` può rimanere "aperto" lato Mollie se un checkout viene abbandonato. Il plugin annulla automaticamente questi pagamenti aperti quando: * il polling automatico va in timeout (5 minuti per impostazione predefinita) — l'annullamento viene inviato anziché lasciare il pagamento in sospeso * l'ordine viene completato con un metodo di pagamento **diverso** (ad esempio, il cliente paga invece in contanti), oppure l'ordine viene annullato in WooCommerce * la pagina di checkout viene chiusa durante il pagamento — viene tentato un annullamento mentre la scheda viene chiusa * un controllo WP-Cron viene eseguito ogni 10 minuti e annulla o risolve i pagamenti rimasti aperti oltre la soglia di inattività (10 minuti per impostazione predefinita), anche quando il browser viene chiuso o la connessione di rete si interrompe prima che vengano eseguiti gli altri percorsi di pulizia Se il pagamento ha già raggiunto il terminale, Mollie lo segnala come non annullabile e l'operatore di cassa lo annulla direttamente sul dispositivo — in tal caso queste operazioni di pulizia sono sicure e non hanno effetto. ## Requisiti[​](#requirements "Collegamento diretto a Requisiti") Account Mollie : Account Mollie attivo con una chiave API per la modalità selezionata Hardware compatibile : Un Mollie Terminal attivo per i pagamenti reali; il terminale di prova simulato di Mollie per i test Valuta : EUR — per ora i pagamenti tramite terminale POS sono limitati all'EUR WCPOS : Per il checkout POS è richiesta la versione Pro Connessione stabile : Connessione Internet affidabile per la comunicazione API ## Ambito e limitazioni[​](#scope-and-limitations "Collegamento diretto a Ambito e limitazioni") Modalità di test Mollie supporta i pagamenti di prova `pointofsale` senza un terminale fisico. Abilitare Punto vendita su un profilo Mollie per creare il relativo terminale di prova, quindi impostare questo gateway su `Test`, usare la chiave API di prova corrispondente e selezionare quel terminale. Mollie restituisce un URL `changePaymentState` per scegliere il risultato simulato. Il plugin può creare e interrogare il pagamento di prova, ma il relativo pannello di pagamento non visualizza attualmente quell'URL. Negli strumenti per sviluppatori del browser, individuare la risposta di rete `mtfwc_start_payment` e aprire `_links.changePaymentState.href` per impostare il risultato, quindi lasciare che il POS esegua il polling e lo riconcili. Consultare la [guida di Mollie per i test al punto vendita](https://docs.mollie.com/docs/in-person-payments-testing). Utilizzare la modalità `Live` per un terminale fisico o iOS/Android. Valuta I pagamenti tramite terminale POS sono limitati a **EUR** finché non verrà confermato un supporto più ampio delle valute per Mollie Terminal. ## Risoluzione dei problemi[​](#troubleshooting "Collegamento diretto a Risoluzione dei problemi") ### Problemi comuni[​](#common-issues "Collegamento diretto a Problemi comuni") Nessun terminale viene visualizzato nel menu a discesa * Verificare che **Modalità** e la chiave API effettiva utilizzino lo stesso ambiente Mollie * In modalità di test, abilitare Punto vendita in un profilo Mollie affinché Mollie crei il relativo terminale di test simulato * In modalità Live, verificare che il terminale sia registrato e **attivo** nell'account Mollie; i terminali inattivi sono nascosti perché Mollie non può riattivarli * Assicurarsi che il sito possa raggiungere Mollie: l'elenco viene recuperato in tempo reale tramite l'API Il pagamento non si avvia * Verificare che sia selezionato un terminale (oppure che sia impostato un **Terminale predefinito** quando la selezione è bloccata) * Verificare che il terminale sia acceso, online e attivo sullo stesso account Mollie * Verificare che la valuta dell'ordine sia **EUR** Il terminale ha superato il tempo limite o il pagamento è rimasto aperto * Il plugin tenta di annullare automaticamente i pagamenti aperti allo scadere del timeout (5 minuti per impostazione predefinita) * Se il pagamento ha già raggiunto il terminale e non può essere annullato automaticamente, annullarlo direttamente sul dispositivo * È quindi possibile avviare un nuovo pagamento o accettare il pagamento in un altro modo L'ordine è stato completato sul terminale, ma si aggiorna lentamente * Il POS interroga Mollie ogni 2 secondi e reindirizza quando il pagamento viene confermato; di solito un webhook lo conferma prima * Poiché Mollie è la fonte di riferimento, l'ordine viene riconciliato con lo stato autorevole di Mollie — non viene perso * Verificare la presenza di eventuali messaggi dell'API Mollie in `WooCommerce > Status > Log` ### Ottenere assistenza[​](#getting-help "Collegamento diretto a Ottenere assistenza") Per assistenza tecnica: * Visita il [repository GitHub](https://github.com/wcpos/mollie-terminal-for-woocommerce) per segnalare problemi * Consulta la [guida alla configurazione di Mollie Terminal](https://docs.mollie.com/docs/setting-up-terminal) e l'[API Mollie Create Payment](https://docs.mollie.com/reference/create-payment) per domande relative all'API * Contatta l'assistenza Mollie per problemi relativi all'account e all'hardware ## Schermate[​](#screenshots "Collegamento diretto a Schermate") Le schermate saranno aggiunte in un futuro aggiornamento per mostrare: * La schermata delle impostazioni di Mollie Terminal — chiave API, terminale predefinito e terminali abilitati * Abilitazione del gateway nelle impostazioni di WCPOS * Flusso di elaborazione dei pagamenti nella fase di pagamento del POS