_images/webgriffe-professional-certified.jpg

Modulo di Pagamento Unicredit PagOnline Imprese per Magento2

Questa è la documentazione del modulo di pagamento Unicredit PagOnline Imprese per Magento2 che integra la piattaforma con l’omonimo portale di pagamento. Inoltre, il modulo supporta il pagamento tramite MyBank.

Il modulo mette a disposizione due metodi di pagamento distinti: uno per il pagamento tramite carte di credito e uno specifico per il pagamento tramite MyBank. I due metodi di pagamento vengono configurati e gestiti in modo indipendente l’uno dall’altro. Per i dettagli sulla configurazione dei due metodi di pagamento vedasi capito Configurazione più in basso.

Installazione

La procedura di installazione del modulo varia a seconda che il modulo sia stato acquistato sul Marketplace di Magento o sullo Store di Webgriffe.

Acquisto effettuato su Magento Marketplace

Se il modulo è stato acquistato sul Marketplace di Magento si hanno a disposizione tre alternative:

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

    Una volta scaricato il file zip del modulo dal Marketplace di Magento, si può procedere con la stessa procedura di installazione usata per l’installazione nel caso di un acquisto dallo Store di Webgriffe. Fare riferimento alla sezione corrispondente più avanti in questo documento.

  • 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-unicredit-imprese
    

    In caso di errori del tipo “impossibile trovare webgriffe/module-unicredit-imprese”, 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
    

    Svuota la cache:

    $ php bin/magento cache:clean
    

    E ricompila i dati della dependency injection:

    $ php bin/magento setup:di:compile
    

Acquisto effettuato su Webgriffe Store

Si può procedere all’installazione manuale usando gli artifact di Composer come segue:

  • Nella directory principale dello store creare una cartella chiamata artifacts, se non è già presente;
  • Incollare lo zip del modulo in questa cartella;
  • eseguire il comando:
$ composer config repositories.artifacts artifact artifacts/
  • Installa il modulo usando composer:
$ composer require webgriffe/module-unicredit-imprese
  • Lancia lo script setup:upgrade di Magento:
$ php bin/magento setup:upgrade
  • Svuota la cache:
$ php bin/magento cache:clean
  • Ricompila i dati della dependency injection:
$ php bin/magento setup:di:compile

Configurazione

È possibile configurare il modulo nella seguente pagina dell’admin di Magento2: Stores -> Configuration -> Sales -> Payment Methods. Qui il modulo aggiunge due gruppi di impostazioni:

  • Portale di Pagamento Unicredit PagOnline Imprese, che raggruppa le impostazioni per il pagamento tramite carte di credito
  • Portale di Pagamento Unicredit PagOnline Imprese MyBank, che raggruppa le impostazioni per il pagamento tramite MyBank

Visto che le configurazioni riportate nei due gruppi sono le stesse, qui di seguito riportiamo solo quelle relative al primo gruppo, quelle dell’altro sono analoghe. 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 Unicredit. 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 di Unicredit PagOnline Imprese in modalità di test. A meno di cambiamenti di specifiche da parte del gateway, questo valore dovrebbe essere impostato su https://testeps.netswgroup.it/UNI_CG_SERVICES/services/PaymentInitGatewayPort?wsdl
    • Terminal id dell’esercente (test): è l’identificatore dell’esercente che riceve il pagamento di test. A meno di cambiamenti di specifiche da parte del gateway, questo valore dovrebbe essere impostato su UNI_ECOM per il metodo di pagamento delle carte di credito, mentre dovrebbe essere impostato su UNI_MYBK nel caso di MyBank.
    • Signature key dell’esercente (test) è la chiave segreta usata per formare digitalmente i messaggi scambiati tra Magento ed il gateway, garantendo quindi la sicurezza della comunicazione. A meno di cambiamenti di specifiche da parte del gateway, questo valore dovrebbe essere impostato su UNI_TESTKEY

    Quando invece la modalità di test non è attiva il modulo si interfaccerà con l’ambiente di produzione di Unicredit in cui le transazioni vengono realmente effettuate. La modalità di produzione è utilizzabile solo se si ha un reale contratto con Unicredit e si hanno reali Terminal id esercente e Signature key dell’esercente. In modalità di produzione 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://pagamenti.unicredit.it/UNI_CG_SERVICES/services/PaymentInitGatewayPort?wsdl
    • Terminal id dell’esercente (produzione): è il codice che identifica l’esercente. Si tratta di una valore fornito da Unicredit al momento dell’attivazione del contratto. Fare attenzione ad inserire questo valore esattamente come indicato da Unicredit, rispettando le maiuscole e le minuscole (se presenti) e facendo particolare attenzione a non aggiungere spazi prima o dopo il valore
    • Signature key dell’esercente (produzione): è la chiave segreta usata per firmare digitalmente i messaggi scambiati tra Magento ed il gateway, garantendo quindi la sicurezza della comunicazione. Questo valore è fornito da Unicredit. Fare attenzione ad inserire questo valore esattamente come indicato da Unicredit, rispettando le maiuscole e le minuscole (se presenti) e facendo particolare attenzione a non aggiungere spazi prima o dopo il valore. Questo codice dovrebbe essere simile a questo codice di esempio: 4g4i3d5c0b1d8e3j0j0a4g4i3d5j0j0a. In caso di problemi, se il formato del codice è significativamente diverso da questo esempio (lunghezza molto diversa, presenza di caratteri non alfanumerici ecc.) si prega di contattare Unicredit per avere la conferma della correttezza del codice. Un errore anche di un solo carattere renderà impossibile verificare l’autenticità delle informazioni e quindi impedirà il funzionamento del modulo.
  • Valuta di pagamento: Questa è la valuta in cui verrà convertito l’importo del pagamento e che verrà mostrata al cliente dopo che questo sarà stato rimandato sulla pagina di pagamento di Unicredit. Attualmente sono supportati solo Euro e Dollaro statunitense.

  • Lingua Pagina Pagamento: Questa è la lingua in cui verrà mostrata la pagina di pagamento di Unicredit al cliente. Gli unici valori attualmente supportati da Unicredit sono Italiano ed Inglese

  • Tipo di transazione 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 dal backoffice di Unicredit (attualmente il modulo non implementa la cattura dell’importo quando si paga una fattura in Magento).
  • Giorni di scadenza per i pagamenti in attesa: Qualora il cliente non torni sul sito dell’esercente dopo aver effettuato il pagamento, oppure se non è possibile verificare immediatamente l’esito della transazione, questo campo indica per quanto tempo continuare a riprovare la verifica della transazione. Ad esempio, se un cliente fa un ordine ma i sistemi di Unicredit hanno dei problemi e non riescono a fornire subito la conferma che la transazione è autorizzata, allora il modulo continuerà a richiedere ad Unicredit la conferma di questa transazione una volta ogni ora per il numero di giorni indicato. Se si raggiunge il numero di giorni indicato senza che sia stata ricevuta una risposta (positiva o negativa), allora l’ordine rimarrà fermo in stato “in attesa di pagamento”.

  • Annulla l’ordine se il pagamento fallisce: Se il cliente sceglie di annullare il pagamento cliccando sull’apposito pulsante nella pagina di pagamento, oppure se i sustemi di Unicredit comunicano a Magento che si è verificato un errore di pagamento, allora se questa impostazione è attiva l’ordine verrà annullato. Nelle stesse situazioni, se questa opzione non è attiva allora l’ordine rimarrà nello stato “in attesa di pagamento”. Notare che questa opzione NON HA ALCUN EFFETTO PER I PAGAMENTI ABBANDONATI, cioè quelli in cui il cliente clicca sul pulsante “indietro” del browser oppure chiude la finestra del browser. Gli ordini in queste situazioni rimarranno fermi in stato “in attesa di pagamento”, indipendentemente dal valore dell’opzione “Annulla l’ordine se il pagamento fallisce”. Questo modulo di pagamento non gestisce i pagamenti abbandonati, quindi se serve gestire anche questi ordini (ad esempio annullandoli) sarà necessario usare moduli di terze parti che vadano ad annullare gli ordini rimasti in stato “in attesa di pagamento” per troppo tempo o procedere a fare un’implementazione ad hoc sullo store del cliente per fare la stessa cosa.

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

  • Metodo di pagamento disponibile per i pagamenti provenienti da e Metodo di pagamento disponibile per i pagamenti provenienti da queste nazioni: permette di specificare se il metodo di pagamento Unicredit PagOnline Imprese è 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 Unicredit PagOnline Imprese è utilizzabile.

  • Ordinamento: permette di impostare un numero di ordinamento che determinerà in quale ordine, nel checkout, il metodo di pagamento Unicredit PagOnline Imprese 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 Unicredit. In questo ambiente tutte le transazioni effettuate sono finte e non c’è alcun trasferimento reale di fondi. A differenza di molti altri gateway di pagamento, Unicredit PagOnline Imprese non richiede che si effettuino richieste server to server per poter completare una transazione. Questo permette di testare facilmente il modulo anche su macchine che non sono raggiungibili dall’esterno e che non hanno un indirizzo pubblico.

Per testare il pagamento tramite carte di credito è possibile usare le carte qui di seguito ed effettuare tutte le prove necessarie. 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 nome e cognome del titolare possono essere dati qualsiasi:

  • CartaSi 4539990000000038 CVV2: qualsiasi (3 cifre) -> esito positivo
  • Amex 375200000000003 CVV2: qualsiasi (4 cifre) -> esito positivo
  • Visa 4020070300280212 CVV2: 301 -> esito positivo
  • Visa 4172340000123456 CVV2: 784 -> esito negativo
  • Mastercard 5204740000001002 CVV2: 100 -> esito negativo
  • Mastercard 5457210002001040 CVV2: 586 -> esito positivo
  • Maestro 6799990100000000043 CVV2: 004 -> esito positivo

Test di MyBank

Nel momento in cui viene scritta questa documentazione l’ambiente di test di Unicredit per il pagamento tramite MyBank risulta accessibile solo dalla rete interna di Unicredit. Questo significa che con il modulo configurato in modalità di test per Mybank, iniziando un pagamento con Mybank si può arrivare fino alla visualizzazione della pagina che permette di scegliere la banca con cui pagare, ma poi qualsiasi cosa si faccia si riceve un errore. L’unico modo per completare un pagamento di test con Mybank è contattare il supporto tecnico di Unicredit (e-merchant.ucbanca@unicredit.eu) e chiedergli di completare il pagamento per un ordine di test che avete creato. Per poter completare un’ordine di test al supporto tecnico servirà l’URL a cui verrebbe reindirizzato il cliente per effettuare il pagamento; tuttavia la difficoltà è che queste URL sono utilizzabili una volta sola, quindi è indispensabile recuperare tale URL senza prima visualizzarla nel browser. Per fare questo è necessario fare temporaneamente una piccola modifica al codice del modulo: nel file src/Controller/Redirect/Index.php bisogna trovare la riga che inizia con return $this->_redirect( e commentarla (mettere prima del return due forward slash, in modo che la riga diventi //return $this->_redirect(). Quindi ricompilare i dati della dependency injection e svuotare la cache (vedere la sezione sull’installazione del modulo per i comandi per fare questi passaggi). Lo scopo di questa operazione è impedire che il modulo faccia automaticamente redirect alla pagina di pagamento del gateway. Assicurarsi anche di avere la modalità di debug per Mybank attiva e che Mybank sia configurato in modalità di test. A questo punto è possibile procedere ad effettuare un ordine di prova. Procedete normalmente e arrivate a cliccare il pulsante “place order” di Magento. Normalmente a questo punto verreste rimandati sul sito della banca per il pagamento, ma con la modifica fatta prima dovreste avere una pagina bianca di errore. Questo è normale. Quindi bisogna recuperare l’URL del pagamento dai log del modulo: andate nella cartella /var/log nella root di Magento ed aprite il file debug.log. Tra le ultime righe di questo file dovreste trovarne una come questa: [unicreditimpresemybank]: Unicreditimprese - Initialize response has returned redirect url .... L’URL al posto dei tre puntini è quella che vi serve e la potete comunicare all’assistenza tecnica di Unicredit facendo attenzione a non aprirla con un browser. Una volta inviata questa URL potrete ripristinare il file src/Controller/Redirect/Index.php, quindi tornare a ricompilare i dati della dependency injection e a svuotare la cache.

Utilizzo e gestione dell’esito del pagamento

Quando un cliente completa il checkout di un ordine scegliendo come metodo di pagamento Unicredit PagOnline Imprese, 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 cliente viene reindirizzato su una URL gestita dal modulo (unicreditpagonlineimprese/payment/notify, sempre che l’utente non chiuda il browser prima di questo redirect). Quando si arriva su quella pagina, il modulo recupera l’ultimo ordine dalla sessione del cliente e fa una richiesta verso Unicredit per chiedere se il pagamento è già stato completato. Nel caso in cui ci sia un errore, l’utente viene rediretto alla pagina di errore (checkout/onepage/failure), mentre in tutti gli altri casi (incluso quello in cui il pagamento è ancora in corso) l’utente viene rimandato a checkout/onepage/success.

Se non è possibile verificare lo stato di un pagamento nel momento in cui un cliente torna sul sito dell’esercente, il modulo riproverà ogni ora a chiedere ad Unicredit lo stato del pagamento. Questa sequenza di richieste andrà avanti fino a che non si riceve un esito positivo o negativo, oppure finchè non si raggiunge il limite di tempo impostato nella configurazione del modulo. Quando il modulo riesce a determinare l’esito di una transazione, vengono effettuate alcune operazioni. 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’Tipo di transazione di pagamento 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, e viene aggiunto un commento alla lista dei commenti dell’ordine. Questo commento contiene delle informazioni sull’errore che si è verificato.

Internazionalizzazione

Il modulo di pagamento Unicredit PagOnline Imprese è 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 Magento 2. Per maggiori informazioni su questo sistema fare riferimento alla documentazione ufficiale di Magento 2.