_images/webgriffe-professional-certified.jpg

Modulo di Pagamento Triveneto per Magento2

Questa è la documentazione del modulo di pagamento Triveneto 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-triveneto
    

    In caso di errori del tipo “impossibile trovare webgriffe/module-triveneto”, 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-triveneto
    
  • 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 Triveneto. 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: 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 Triveneto. 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:

    • TranPortalID (test): È l’identificatore dell’esercente di test nei sistemi di Triveneto. Si tratta di un dato fornito da Triveneto al momento dell’attivazione del contratto.
    • Password (test): Una password fornita da Triveneto ed usata per controllare l’autenticità delle transazioni di test.
    • Init URL (test) 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://ipg-test4.constriv.com/IPGWeb/servlet/PaymentInitHTTPServlet

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

    • TranPortalID: È l’identificatore dell’esercente nei sistemi di Triveneto. Si tratta di un dato fornito da Triveneto al momento dell’attivazione del contratto.
    • Password: Una password fornita da Triveneto ed usata per controllare l’autenticità delle transazioni.
    • Init 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://ipg.constriv.com/IPGWeb/servlet/PaymentInitHTTPServlet
  • 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.

  • Azione: Permette di specificare quale azione eseguire quando un cliente effettua un ordine:

    • 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 dal backoffice di Triveneto (attualmente il modulo non implementa la cattura dell’importo quando si paga una fattura in Magento).
    • Autorizzazione e cattura: effettua immediatamente la transazione di pagamento, trasferendo subito i fondi dalla carta di credito del cliente al conto dell’esercente.
  • Chiave segreta: Per garantire una maggiore sicurezza delle transazioni il modulo usa questo dato (generato automaticamente al momento dell’installazione del modulo) per “firmare” i dati che invia a Triveneto e ricontrollare che quello che torna indietro corrisponda a quanto era stato firmato. Normalmente non bisogna mai modificare il contenuto di questo campo. Nel caso si importi un database preso da un’installazione di Magento diversa in cui erano già presenti degli ordini pagati con il modulo Triveneto, allora sarà necessario inserire in questo campo il valore che era stato usato nell’installazione di cui si sta importando il database. In questo modo il modulo potrà verificare correttamente l’esito anche di pagamenti che erano stati iniziati sulla vecchia installazione di Magento.

  • 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 Triveneto è 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 Triveneto è utilizzabile.

  • Ordinamento: permette di impostare un numero di ordinamento che determinerà in quale ordine, nel checkout, il metodo di pagamento Triveneto 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 Triveneto. In questo ambiente tutte le transazioni effettuate sono finte e non c’è alcun trasferimento reale di fondi. Il flusso di pagamento prevede che Triveneto 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 Triveneto (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 triveneto/notify/index

È possibile usare le carte qui di seguito per effettuare le prove necessarie in ambiente di test. Notare che alcune di queste carte danno un esito negativo, che può essere utile per verificare il comportamento del sistema in caso di errore. Le date di scadenza possono essere impostate ad una qualsiasi data di scadenza nel futuro. Anche il codice di verifica ed il nome e cognome del titolare, così come la sua mail possono essere dati qualsiasi:

  • 4539990000000012 -> esito positivo
  • 4539990000000020 -> transazione non approvata
  • 4999000055550000 -> numero di carta non valido

Nell’ambiente di test è possibile selezionare se pagare con cata di credito, con MyBank e con MasterPass. Al momento di scrivere questo manuale, sembra che nell’ambiente di test funzioni solo il pagamento con carta di credito “semplice”. In modalità di produzione, invece, tutte le modalità dovrebbero essere funzionanti.

Utilizzo e gestione dell’esito del pagamento

Quando un cliente completa il checkout di un ordine scegliendo come metodo di pagamento Triveneto, 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 Triveneto 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. Sia in caso di esito positivo che negativo, i dati restituiti da Triveneto vengono inseriti in un commento dell’ordine di Magento, in modo che si possa facilmente verificare la causa di eventuali problemi.

Internazionalizzazione

Il modulo di pagamento Triveneto è 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.