_images/webgriffe-professional-certified.jpg

Modulo di Pagamento MonetaWeb 2.0 per Magento2

Questa è la documentazione del modulo di pagamento MonetaWeb 2.0 per Magento2 che integra la piattaforma con l’omonimo portale di pagamento. Questo modulo permette di effettuare sia pagamenti “standard” con carta di credito, sia pagamenti con il sistema “MyBank”.

Installazione

L’installazione del modulo può essere fatta sia in maniera “guidata” che in maniera “manuale”. Se il modulo è stato acquistato tramite Magento Marketplace, sono disponibili entrambe le procedure di installazione. Invece, se il modulo è stato acquistato tramite Webgriffe® Store è disponibile esclusivamente l’installazione manuale.

Installazione guidata (solo Magento Marketplace)

Se il modulo è stato acquistato sul Marketplace di Magento si hanno a disposizione 2 alternative per l’installazione guidata:

  • Installazione tramite il Component Manager di Magento

    Se non è già stato fatto inserire le proprie credenziali di Magento Markeplace accedendo a System > Web Setup Wizard > System Configuration e seguendo le istruzioni.

    Fatto ciò è possibile accedere al Component Manager in System > Web Setup Wizard > Component Manager, il modulo acquistato dovrebbe comparire nella sezione New Purchases, cliccare quindi su Install per installarlo. Maggiori informazioni sono disponibili alla pagina http://devdocs.magento.com/guides/v2.1/comp-mgr/module-man/compman-main-pg.html.

  • Installazione tramite Composer da linea di comando

    Innanzi tutto assicurarsi di aver aggiunto al proprio composer.json il repository repo.magento.com e di aver configurato le relative chiavi di autenticazione. Maggiori informazioni su come ottenere le chiavi di autenticazione dal Magento Marketplace e su come impostarle in Composer sono disponibili alle pagine http://devdocs.magento.com/guides/v2.0/install-gde/prereq/connect-auth.html e https://getcomposer.org/doc/articles/http-basic-authentication.md.

    Quindi nel file auth.json dovrebbe esserci qualcosa del tipo:

    {
        "http-basic": {
            "repo.magento.com": {
                "username": "<MAGENTO_MARKETPLACE_PUBLIC_KEY>",
                "password": "<MAGENTO_MARKETPLACE_PRIVATE_KEY>"
            }
        }
    }
    

    A questo punto si può lanciare il comando:

    $ composer require webgriffe/module-monetaweb2
    

    In caso di errori del tipo “impossibile trovare webgriffe/module-monetaweb2”, verificare che le informazioni di autenticazione siano corrette, che il file sia nella cartella corretta e che, in generale, venga usato da Composer.

    Infine lancia lo script setup:upgrade di Magento:

    $ php bin/magento setup:upgrade
    

Installazione manuale (Magento Marketplace e Webgriffe Store)

Una volta scaricato il file zip del modulo dal Marketplace di Magento o dal Webgriffe Store, si può procedere con i seguenti step:

  • Creare una cartella artifacts nella cartella radice dell’installazione Magento.

    $ mkdir artifacts
    
  • Impedire l’accesso pubblico a questa cartella attraverso opportuna configurazione del webserver (ad esempio, se è in uso Apache, con un file .htaccess con contenuto Deny from all).

    $ echo "Deny from all" > artifacts/.htaccess
    
  • Copiare il file zip del modulo all’interno della cartella artifacts

  • Aggiungere la cartella artifacts come repository Composer

    $ composer config repo.artifacts "artifact" "artifacts/"
    
  • Aggiungere il modulo alle dipendenze con Composer

    $ composer require webgriffe/module-monetaweb2
    
  • Lanciare lo script setup:upgrade di Magento:

    $ php bin/magento setup:upgrade
    

Configurazione

La configurazione generale del modulo è possibile da Stores -> Configuration -> Sales -> Payment Methods, nelle sezioni Setefi MonetaWeb 2.0 Payment Gateway (per le configurazioni globali), Portale di pagamento Setefi MonetaWeb 2.0 - Pagamento con Carta di Credito (per le configurazioni specifiche del pagamento con carta di credito) e Portale di pagamento Setefi MonetaWeb 2.0 - Pagamento con MyBank (per le configurazioni specifiche del pagamento con MyBank). Le voci di configurazione (suddivise nelle tre sezioni indicate sopra) sono le seguenti:

  • Abilitato: permette di abilitare o disabilitare il metodo di pagamento. Questa configurazione è specifica per i metodi di pagamento con carta di credito e Mybank, in modo che sia possibile lasciarne abilitato uno solo e disabilitare l’altro se si vuole. Notare però che se un utente inizia un pagamento con Mybank, una volta raggiunta la pagina della banca gli verrà mostrata la possibilità di continuare il pagamento con carta di credito. Questo comportamento può essere verificato usando la modalità di test del modulo ed iniziando un pagamento tramite Mybank, scegliendo poi di concluderlo con carta di credito. Se non si vuole che questo possa succedere, si prega di contattare il supporto tecnico di Setefi.

  • Titolo: permette di specificare il nome del metodo di pagamento che visualizzerà l’utente durante il checkout.

  • Modalità di test: permette di abilitare la modalità di test. Questa modalità è utile per testare il flusso di pagamento prima di metterlo in produzione in quanto il modulo si interfaccerà con l’ambiente di test di MonetaWeb 2.0. In questo ambiente tutte le transazioni effettuate sono finte e non c’è alcun trasferimento reale di fondi. Quando la modalità di test è attiva verranno utilizzati i seguenti parametri:

    • Test Gateway URL URL a cui il modulo invia la richiesta iniziale per avviare la procedura di pagamento quando la modalità di test è attiva. Questo valore dovrebbe essere sempre https://test.monetaonline.it/monetaweb/payment/2/xml
    • Test Terminal ID: È l’identificatore dell’esercente di test nei sistemi di MonetaWeb 2.0. Dovrebbe essere sempre 99999999.
    • Test Terminal Password: Una password usata per controllare l’autenticità delle transazioni di test. Dovrebbe essere sempre 99999999.

    Quando invece la modalità di test non è attiva, il modulo si interfaccerà con l’ambiente di produzione di MonetaWeb 2.0 in cui le transazioni vengono realmente effettuate. In modalità di produzione verranno visualizzate le voci:

    • Gateway URL: URL a cui il modulo invia la richiesta iniziale per avviare la procedura di pagamento quando la modalità di test è disattivata. Questo valore dovrebbe essere sempre https://www.monetaonline.it/monetaweb/payment/2/xml
    • Terminal ID: È l’identificatore dell’esercente nei sistemi di MonetaWeb 2.0. Si tratta di un dato fornito da Setefi al momento dell’attivazione del contratto.
    • Terminal Password: Una password fornita da Setefi ed usata per controllare l’autenticità delle transazioni.
  • Azione di Pagamento: Permette di specificare quale azione eseguire quando un cliente effettua un ordine:

    • Autorizzazione e Cattura: effettua immediatamente la transazione di pagamento, trasferendo subito i fondi dalla carta di credito del cliente al conto dell’esercente.
    • Sola Autorizzazione: si limita ad “autorizzare” il trasferimento dell’importo dell’ordine, senza però effettuare il trasferimento. In pratica i fondi vengono bloccati sulla carta del cliente, ma non trasferiti. Questo trasferimento dovrà essere richiesto manualmente in un secondo tempo o generando una fattura in Magento selezionando l’azione “Capture online” oppure dal backoffice di MonetaWeb 2.0. Il gateway supporta la possibilità di una cattura di un importo inferiore a quello precedentemente autorizzato, ma la cattura non può essere multipla. Quindi se si fanno più fatture per un singolo ordine, solo per la prima sarà possibile catturare l’importo corrispondente.
  • Debug: permette di attivare la modalità di debug che memorizza maggiori informazioni durante il funzionamento del modulo. E’ utile attivare questa modalità in caso di problemi tecnici per capire meglio cosa non sta funzionando.

  • Lingua: permette di scegliere la lingua utilizzata dalle pagine di MonetaWeb 2.0 tra quelle supportate da Monetaweb 2.

  • Valuta: questo campo permette di indicare la valuta in cui effettuare il pagamento. Notare che il modulo non effettua alcuna conversione dell’importo da pagare indicato da Magento, quindi il valore di questo campo di configurazione DEVE essere uguale alla valuta di base impostata in ciascun sito web di Magento.

  • Annullare Ordine se Pagamento Fallisce: permette di annullare l’ordine nel caso in cui il pagamento non vada a buon fine (sia per errori tecnici, sia anche per annullamento volontario da parte dell’utente).

  • Metodo di pagamento disponibile per i pagamenti provenienti da e Metodo di pagamento disponibile per i pagamenti provenienti da queste nazioni: permettono di specificare se il metodo di pagamento MonetaWeb 2.0 è utilizzabile per tutte le nazioni del mondo o solo da nazioni specifiche.

  • Minimo totale d’ordine e Massimo totale d’ordine: permette di specificare quali sono gli importi minimi e massimi dell’ordine per cui il metodo di pagamento MonetaWeb 2.0 è utilizzabile.

  • Ordinamento: permette di impostare un numero di ordinamento che determinerà in quale ordine, nel checkout, il metodo di pagamento MonetaWeb 2.0 verrà visualizzato rispetto agli altri metodi attivi. L’ordine è crescente, quindi i metodi di pagamento con valori più bassi verranno visualizzati più in alto, ed i metodi di pagamento con valori più alti andranno più in basso nell’elenco.

Modalità di Test

La modalità di test è utile per verificare il flusso di pagamento prima di metterlo in produzione, in quanto il modulo si interfaccerà con l’ambiente di test di Setefi. In questo ambiente tutte le transazioni effettuate sono finte e non c’è alcun trasferimento reale di fondi. Il flusso di pagamento prevede che Setefi faccia una chiamata server to server verso il server dell’esercente per comunicare l’esito della transazione. Questo significa che per poter usare il modulo MonetaWeb 2.0 (sia in modalità di test che in modalità di produzione), il server su cui è installato deve poter essere raggiungibile dall’esterno ad una URL pubblica e senza nessun tipo di autenticazione. Come minimo deve essere visibile pubblicamente l’URL monetaweb2/notify/index

È possibile usare le carte qui di seguito per effettuare le prove necessarie in ambiente di test. In ambiente di test qualsiasi altra carta restituirà esito negativo.

Circuito Numero Scadenza CVV Verifica 3D Secure Password 3D Secure
VISA 4471490099993805 01/2022 771 ENROLLED valid
VISA 4349940199996900 01/2022 994 ENROLLED valid
VISA 4163640001916707 01/2019 659 NOT ENROLLED  
VISA 4163640001927142 01/2019 369 NOT ENROLLED  
MASTERCARD 5167950099913810 01/2022 151 ENROLLED valid
MASTERCARD 5398320199997454 01/2020 728 ENROLLED valid
MASTERCARD 5167950099913828 01/2022 921 ENROLLED valid
MASTERCARD 5246949906176152 01/2019 266 NOT ENROLLED  
AMEX 375200000000003 12/2018 5861 NOT SUPPORTED  
DINERS 36961903000009 11/2018 553 NOT SUPPORTED  

Nel caso in cui sia necessario fare delle prove e queste carte non siano più valide per via della loro data di scadenza, si prega di fare riferimento alla documentazione tecnica di MonetaWeb scaricabile dalla sezione “documentazione” del backoffice di MonetaWeb. Nell’appendice A dovrebbe essere presente una tabella con le carte di test aggiornate.

È anche possibile testare il pagamento tramite Mybank usando la modalità di test. Per fare questo selezionare il metodo di pagamento appropriato nel checkout di Magento per iniziare un pagamento con Mybank e quindi, una volta arrivati alla pagina di pagamento della banca, si prega di scegliere una banca tra quelle indicate qui di seguito:

  • Fakebank_AUTHORISED Simula una transazione correttamente autorizzata
  • Fakebank_ERROR: Simula un errore
  • Fakebank_AUTHORISINGPARTYABORTED Simula un pagamento annullato dal pagatore
  • Fakebank_PENDING Simula una transazione ancora in corso
  • Fakebank_TIMEOUT Simula una transazione che non è stata completata prima che scadesse il tempo concesso all’utente per completare il pagamento (normalmente 15 minuti)

Usare qualsiasi altra banca dalla lista fornita mentre si è in modalità di test non funzionerà. Dopo aver selezionato una delle banche indicate qui sopra, si prega di seguire le istruzioni su schermo ed infine si verrà rimandati al sito Magento da cui si era partiti.

Utilizzo e gestione dell’esito del pagamento

Quando un cliente completa il checkout di un ordine scegliendo come metodo di pagamento MonetaWeb 2.0, viene redirezionato sulla pagina di pagamento del gateway. In questo momento Magento imposta lo stato dell’ordine in Pending Payment (o Attesa Pagamento). Dopo che il cliente completa il pagamento inserendo i dati della carta di credito, il server di Setefi contatta l’URL di notifica fornita dal modulo per comunicare l’esito della transazione. Se il pagamento va a buon fine, allora l’ordine viene marcato come pagato, passando in stato Processing (o In elaborazione) e il cliente viene ridirezionato alla pagina checkout/onepage/success. In caso di errore, invece, l’ordine rimane nello stato in cui già si trovava ed il cliente viene rimandato a checkout/onepage/failure.

In caso di esito positivo, vengono effettuate ulteriori operazioni che variano a seconda dell’Azione impostata:

  • Nel caso di Autorizzazione e Cattura sull’ordine viene creata una Transazione di tipo Cattura e viene generata, automaticamente, la Fattura. In questo modo, per Magento, l’ordine è completamente pagato.
  • Nel caso di Sola Autorizzazione invece, sull’ordine viene creato una Transazione di tipo Autorizzazione che indica a Magento che l’importo di pagamento è stato autorizzato. Per Magento però l’ordine non è ancora pagato e infatti non esiste alcuna Fattura legata all’ordine.

Se invece l’esito del pagamento indica un errore, allora l’ordine rimane nello stato in cui si trovava, a meno che l’opzione Annullare Ordine se Pagamento Fallisce (vedi sezione Configurazione) non sia stata abilitata, in questo caso l’ordine finirebbe nello stato Cancellato. Sia in caso di esito positivo che negativo, i dati restituiti da Setefi vengono inseriti in un commento dell’ordine di Magento, in modo che si possa facilmente verificare la causa di eventuali problemi.

Come detto in precedenza, se un utente inizia un pagamento con Mybank, ha la possibilità di cambiare idea e completare il pagamento con carta di credito. Quando questo accade, il modulo inizialmente usa per l’ordine il metodo di pagamento tramite Mybank. Quando si riceve la richiesta server-to-server (inviata da Setefi verso il sito Magento), se la notifica indica che il metodo di pagamento è cambiato, allora il modulo va ad aggiornare l’ordine con il nuovo metodo di pagamento aggiunge un commento speciale all’ordine per spiegare cosa è successo.

Internazionalizzazione

Il modulo di pagamento MonetaWeb 2.0 è sviluppato con una interfaccia utente nativa in lingua inglese (en_US). Nel modulo però è anche compresa la traduzione in lingua italiana (it_IT). È possibile tradurre l’interfaccia in altre lingua utilizzando il sistema di traduzione nativo di Magento 2. Per maggiori informazioni su questo sistema fare riferimento alla documentazione ufficiale di Magento 2.