_images/webgriffe-professional-certified.jpg

Modulo di Pagamento Key Client/CartaSì per Magento2

Questa è la documentazione del modulo di pagamento QuiPago/Nexi per Magento2 che integra la piattaforma con l’omonimo portale di pagamento.

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-quipago
    

    In caso di errori del tipo “impossibile trovare webgriffe/module-quipago”, 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-quipago
    
  • 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 -> Portale di Pagamento QuiPago. Le voci di configurazione sono le seguenti:

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

  • Abilitato: permette di abilitare o disabilitare il metodo di pagamento.

  • Modalità di Test Abilitata: 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 QuiPago. 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:

    • URL della Pagina di Pagamento (test): è l’URL della pagina di pagamento QuiPago in modalità di test. A meno di cambiamenti di specifiche da parte del gateway questo valore dovrebbe essere impostato su https://int-ecommerce.nexi.it/ecomm/ecomm/DispatcherServlet
    • Alias/Insegna Negozio (test): è il codice identificativo del negozio da usare in modalità di test. Leggi la sezione Modalità di Test qui sotto per maggiori dettagli.
    • Chiave segreta per il calcolo del MAC (test): è la chiave segreta per il calcolo del MAC da utilizzare in ambiente di test. Leggi la sezione Modalità di Test qui sotto per maggiori dettagli.

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

    • URL della Pagina di Pagamento (produzione): è l’URL della pagina del portale di pagamento in ambiente di produzione. A meno di cambiamenti di specifiche, dovrebbe essere impostato su https://ecommerce.nexi.it/ecomm/ecomm/DispatcherServlet
    • Alias/Insegna Negozio (produzione): è il codice identificativo del negozio da usare in modalità di produzione. Questo valore viene comunicato da QuiPago in fase di attivazione del contratto.
    • Chiave segreta per il calcolo del MAC (produzione): è la chiave segreta per il calcolo del MAC da utilizzare in ambiente di produzione. Questo valore viene comunicato da QuiPago in fase di attivazione del contratto.
  • Lingua della Pagina di Pagamento: permette di scegliere in quale lingua deve essere visualizzata la pagina di pagamento in cui l’utente inserisce le informazioni della carta di credito

  • Azione di Pagamento: permette di scegliere se i pagamenti fatti con questo metodo di pagamento devono essere considerati come solo autorizzati o come autorizzati e catturati. Questa opzione dovrebbe essere impostata in accordo con la modalità di contabilizzazione scelta durante l’attivazione del contratto QuiPago.

  • Metodo di cifratura per il calcolo del codice MAC: permette di impostare quale metodo di cifratura utilizzare per il calcolo del codice MAC. Nelle più recenti attivazioni viene sempre utilizzato il metodo SHA1 ma alcuni vecchi contratti necessitano invece del metodo MD5. Se si è in dubbio su quale valore utilizzare fare riferimento al supporto tecnico QuiPago.

  • Annullare Ordine se Pagamento Fallisce: permette di attivare l’annullamento automatico dell’ordine in caso di pagamento fallito.

  • 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.

  • Payment From Applicable Countries e Payment From Specific Countries: permette di specificare se il metodo di pagamento QuiPago è utilizzabile per tutte le nazioni del mondo o solo da nazioni specifiche

  • Minimum Order Total e Maximum Order Total: permette di specificare quali sono i valori minimi e massimi dell’ordine per cui il metodo di pagamento QuiPago è utilizzabile.

  • Sort Order: permette di impostare un numero di ordinamento che determinerà in quale ordine, nel checkout, il metodo di pagamento QuiPago verrà visualizzato rispetto agli altri metodi attivi

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 QuiPago. In questo ambiente tutte le transazioni effettuate sono finte e non c’è alcun trasferimento reale di fondi. Per poter usare questa modalità devi prima registrare un account di test qui https://ecommerce.nexi.it/area-test . Una volta che ti sei loggato ti ritroverai in una pagina che contiene molte informazioni utili:

  • Sotto la sezione Pagamento Semplice trovi i due valori Alias e Chiave per il calcolo mac che devi inserire nei relativi campi di configurazione del modulo su Magento (rispettivamente Alias e Chiave segreta per il calcolo del MAC);
  • In questa stessa sezione (Pagamento Semplice) vengono riportati anche i dati per l’accesso al Back Office, nel quale puoi controllare i vari dati degli ordini e ottenere dei report.
  • Sotto la sezione Carte di Test trovi le carte di test con le quali puoi simulare tutte le tipologie di risultato dei pagamenti.

Utilizzo e gestione dell’esito del pagamento

Quando un cliente completa il checkout di un ordine scegliendo come metodo di pagamento QuiPago, viene redirezionato sulla pagina di pagamento esterna. 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, viene inviato da QuiPago un messaggio server-to-server che comunica l’esito della transazione appena avvenuta. Il modulo di pagamento riceve questa notifica ed effettua, automaticamente, alcune operazioni di gestione del pagamento sull’ordine. Nel caso in cui la transazione non sia stata autorizzata non viene effettuata alcuna operazione e l’ordine rimane in stato Pending Payment. Invece, nel caso in cui la transazione sia andata a buon fine, l’ordine passa automaticamente in stato Processing (o In elaborazione). Sempre in caso di esito positivo, vengono effettuate ulteriori operazioni che variano a seconda dell’Azione di pagamento impostata:

  • Nel caso di Sola Autorizzazione 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.
  • Nel caso di Autorizzazione e Cattura invece, sull’ordine viene creata una Transazione di tipo Cattura e viene generata, automaticamente, la Fattura. In questo modo, per Magento, l’ordine è completamente pagato.

Internazionalizzazione

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

Valute supportate

Il portale QuiPago/Nexi/CartaSì accetta solo importi specificati in Euro. Di conseguenza, il modulo cerca di convertire in Euro l’importo dell’ordine se specificato in una valuta base diversa dall’Euro, utilizzando le tabelle di conversione di Magento (dall’admin si trovano sotto Stores->Currency Rates). Per questo motivo, quando la valuta base è diversa dall’euro, deve essere disponibile un tasso di conversione dalla valuta base all’Euro, altrimenti il modulo restituisce un errore e non permette di effettuare il pagamento dell’ordine. Per maggiori informazioni fare riferimento alla documentazione di Magento2: http://docs.magento.com/m2/ce/user_guide/stores/currency-overview.html