# Introduzione
Il modulo BNL Advanced 2.0 diventa Axepta ed offre agli esercenti del gruppo bancario la possibilità di interfacciare il proprio negozio Magento con uno dei più interessanti sistemi di POS Virtuali una volta chiamato e-Positivity.
{% hint style="info" %}
Tutti i riferimenti al vecchio sistema di connesisone BNL devono essere letti per le nuove versioni del modulo: Axepta.
{% endhint %}
## Cosa è e-Positivity
Una soluzione progettata per un servizio completo e sicuro di pagamenti via web alle aziende che, disponendo di una vetrina su Internet, siano interessate al sistema di validazione dei pagamenti elettronici. E-POSitivity è’ una piattaforma operativa che permette di elaborare transazioni via internet in maniera flessibile e in tutta sicurezza. Con tre diverse soluzioni, Connect, Virtual Terminal e API, e–POSitivity permette agli esercenti di gestire le transazioni e consente ai titolari delle carte di credito/clienti di acquistare direttamente e autonomamente tramite il sito Web dell’esercente
# Cosa è un POS?
Un POS virtuale è un’applicazione informatica che permette ai merchant di accettare pagamenti online tramite carta di credito. Quando entri in un negozio fisico spesso hai la possibilità di pagare con carta di credito o di debito usando un’apposita macchinetta, detta Point Of Sale (punto di vendita) o POS. Il POS virtuale funziona in modo simile, ma per i negozi online.
## POS virtuale: processo di pagamento
Quando un cliente effettua un ordine nel tuo negozio online, compila i campi richiesti e alla fine sceglie il metodo di pagamento. A questo punte viene reindirizzato alla pagina di un POS virtuale, dove inserisce i dati di pagamento.
Grazie al POS virtuale, tu merchant non hai accesso ai dati di pagamento dei tuoi clienti, perciò non devi preoccuparti di gestirli e di conformarti alle regole PCI DSS (Payment Card Industry Data Security Standard). Inoltre, i clienti potranno pagare con il loro metodo preferito nel tuo negozio online e tu potrai guadagnare la loro fiducia.
## Come fa il POS Virtuale ad inviare il denaro nel mio conto corrente?
Come precedentemente descritto, il POS virtuale non è altro che un software che ha dei parametri di configurazione da impostare nel suo pannello di controllo. Ogni POS Virtuale ha delle credenziali di accesso ai servizi POS rilasciati dalla propria banca. Tali credenziali sono registrate negli archivi della banca e vengono controllate ad ogni transazione eseguita con il POS virtuale.
Tali credenziali sono collegate ad un profilo POS il quale è connesso al vostro conto corrente bancario. Quindi al click sulla conferma d'ordine, il POS virtuale domanderà l'accesso al sistema sicuro della banca, inviando le credenziali precedentemente inserite e permetterà al cliente di visualizzare la pagina di pagamento sicura.
Il cliente inserirà i dati della propria carta di credito e l'istituto di credito (VISA, Mastercard, ecc...) invierà alla banca collegata al profilo POS virutale l'ammontare accreditato dal cliente.
## Perché usare un POS virtuale?
* I tuoi clienti possono pagare nel tuo negozio online con carta di credito
* Non devi essere PCI compliant
* Non devi gestire, salvare e conservare i dati di pagamento dei tuoi clienti
## POS virtuale: quali metodi di pagamento sono disponibili?
Un POS virtuale offre solo pagamenti online con le carte di credito e di debito, ma non con altri metodi. Normalmente sono accettati tutti i principali circuiti internazionali, come Visa, Mastercard, American Express e Maestro.
# IGFS
L'Internet Gateway Financial Systems o più semplicemente IGFS è la soluzione modulare realizzata per supportare le aziende e le istituzioni finanziarie che offre il sistema di Token e prevenzioni alle frodi per le transazioni generate via eCommerce, consentendo ai commercianti di accettare crediti/debiti internazionali per mezzo di eWallet (portafogli digitali) ed conti correnti bancari. L'architettura modulare consente l'integrazione semplice e sicura per tutti i tipi di carte di credito.
Il modulo di pagamento per Magento BNL utilizza la metodologia IGFS per stabilire le comunicazioni con i server della banca.
## Compatibilità
Il modulo è compatibile con le nuove classi IGFS 2.3.x rilasciate all'inizio del 2017.
# 3D Secure
Il 3D Secure è il sistema di protezione antifrode Verified by Visa e Mastercard® SecureCode™ che garantisce una tutela per gli acquisti online. Ad ogni acquisto si riceve un SMS contenente un codice di sicurezza unico da inserire al momento del pagamento per confermare il tuo acquisto.
L’iscrizione a Verified By Visa e 3D Secure Code è a carico di BNL POSitivity
# Transazioni con carta di credito
## Come funzionano le transazioni con carta di credito?
Conoscere il funzionamento del flusso del processo della transazione di pagamento della carta di credito aiuta a comprendere anche l'iter utilizzato da Magento e dai moduli di pagamento. Le azioni di base del ciclo di vita delle transazioni sono:
* Autorizzazione (Authorization)
* Addebito (Capture)
* Storno (Refund)
* Annullamento (Void)
Queste azioni di flusso sono suddivise in operazioni più specifiche che possono essere chiamate in modo differente in base al gateway di pagamento. Di seguito sono riportati alcuni elementi di base rilevanti:
### **Autorizzazione**
E’ un blocco temporaneo di un importo specifico su una carta di credito. Questa operazione non genera nessun tipo di movimento bancario sul conto corrente del cliente perchè non viene contabilizzato, quindi, **non è un addebbito**. L’autorizzazione viene rilasciata dalla banca di riferimento, oppure dal gestore del circuito di carte di credito. L'autorizzazione permette quindi di “prenotare” un importo prima che l’operazione venga effettivamente effettuata. In questo modo è garantita in ogni caso la disponibilità dell’importo al momento della prenotazione definitiva. L'operazione di autorizzazione ha una validità di 30gg.
### Addebito
La cattura di un importo può avvenire direttamente oppure dopo l'autorizzazione. In questo caso la banca o l'istituto di credito sbloccherà la "prenotazione" qualora vi fosse stata una precedente autorizzazione e addebiterà al cliente l'importo richiesto. Tale operazione genera un vero e proprio movimento del denaro dall'istituto di credito verso la banca dell'esercente che ha richiesto il pagamento di un bene o servizio.
### Storno
L'operazione di storno può essere effettuata solamente dopo una cattura e mai dopo l'autorizzazione. In questo caso la banca o l'istituto di credito movimenterà il denaro dal conto dell'esercente al conto del cliente.
### Annullamento
L'annullamento della transazione avviene solamente se vi è un'autorizzazione attiva non addebitata. In questo caso l'autorizzazione precedentemente richiesta verrà annullata senza generare alcun movimento del denaro.
## Magento States & Status
Magento gestisce gli status degli ordini attraverso due parametri fondamentali :
* **States**
* **Nuovo**: L'ordine è nuovo, non processato e non preso in carico da un gateway di pagamento o altro.
* **In attesa del pagamento**: Il pagamento è in corso attraverso il gateway selezionato dal cliente. Gli elementi presenti nell'ordine sono stati già eliminati dall'inventario di Magento.
* **In Elaborazione**: La fattura è stata creata, l'ordine è pronto per essere processato.
* **Completo**: La spedizione è completata.
* **Chiuso**: L'ordine è chiuso prima che la fattura sia stata creata. Gli elementi ritornano in stock.
* **Cancellato**: Una nota di credit è stata effettuata
* **In Attesa**: State manuale per mantenere in sospeso un ordine.
* **Revisione Pagamento**: In attesa di un'integarzione di informazioni da parte del payment gateway: Utilizzato spesso dal modulo di Paypal.
Ogni States di Magento può essere mappato in più Status. Gli Status possono essere impostati manualmente dal proprietario del negozio Magento. I gateway di pagamento di solito hanno la capacità di impostare lo status diverso dal parametro predefinito dall'utente. I gateway di pagamento introducono talvolta nuovi status e non utilizzano quelli di default.
# Gestione degli Ordini
La gestione degli ordini in Magento è molto sofisticata e vi sono moltissime soluzioni che potrebbero essere adottate ma la domanda che ci si pone sempre è: **Generare l'ordine prima del pagamento ?** oppure **attendere il pagamento prima di creare un ordine?** Prima di tutto bisogna considerare cosa è un ordine dal punto di vista commerciale.
## Gli Ordini
La definizione della parola **Ordine in ambito commerciale è la richiesta di una merce o di un servizio**. Quindi un ordine commerciale è la richiesta di determinato prodotto nel negozio magento da parte di un "potenziale cliente". Consideriamo il richiedente un "**potenziale**" cliente **poichè non lo è ancora, visto il mancato pagamento della merce o del servizio**. Quindi un ordine potrebbe esistere ma non aver alcun valore finchè il "potenziale cliente" o il "richiedente" non effettua il pagamento.
Al momento della conferma dell'ordine in Magento, il richiedente esprime la sua volontà nell'interesse di un determinato servizio o merce e Magento può "riservare o mantenere la disponibilità" di tale prodotto per un determinato periodo e/o dopo un'azione personalizzata da parte del gateway di pagamento.
Magento ha diverse funzionalità legate alla gestione degli ordini e noi **ci focalizzeremo sulla gestione dello status prima e dopo il pagamento dell'ordine**.
Abbiamo detto che il richiedente ha espresso il proprio interesse nell'acquisto di un determinato prodotto o servizio al click di conferma d'ordine che può reindirizzare il richiedente al gateway sicuro della banca.
Vi sono moltissimi modi di effettuare un pagamento, ma noi ci soffermeremo sui **pagamenti con redirect** chiamati **Hosted** (pagamenti ospitati nel server della banca).
Durante il redirect verso il server sicuro della banca, **Magento DEVE creare un ordine per mantenere "la richiesta" che il cliente ha generato durante l'uso del carrello in archivio**, poichè il reindirizzamento verso un sito differente **cancella i dati temporanei del carrello** perdendo definitivamente le informazioni. In questo determinato istante l'ordine viene creato e registrato in archivio con un codice ordine univoco e con uno status della transazione in "Pending Review" o "Pagamento in revisione" **inviando una notifica al cliente relativa all'ordine generato**. **La notifica non alcun valore fino al ricevimento del documento commerciale più importante: la Fattura.**
Ecco i casi più frequenti riscontrati:
1. il cliente effettua il pagamento e ritorna sul sito internet dell'esercente
* un messaggio lo avviserà dell'avvenuto pagamento. Magento imposterà un nuovo status "In Elaborazione" (Processing)
2. il cliente non effettua il pagamento e ritorna sul sito internet dell'esercente
* un messaggio lo avviserà sull'errore generato. Magento creerà un nuovo carrello con i vecchi prodotti scelti dal cliente e cancellerà il vecchio ordine mantenendo traccia della transazione annullata da parte del cliente.
3. il cliente effettua il pagamento e chiude il browser
* il server della banca contatterà il negozio Magento inviando una notifica sull'esito del pagamento (solo in live mode). Magento imposterà un nuovo status "In Elaborazione" (Processing)
4. il cliente non effettua il pagamento e chiude il browser
* il server della banca contatterà il negozio Magento inviando una notifica sull'esito del pagamento (solo in live mode). Magento imposterà un nuovo status "Cancellato" (Canceled)
Seguendo quanto detto in precedenza, in tutti i casi su riportati Magento mantiene traccia di ciò che il cliente ha ordinato e sarà possibile conoscere ciò che è successo durante la fase di acquisto attraverso i log del modulo di pagamento (vedi[ Logging, Debug](/logging-debug-ed-errori-comuni)).
L'invio dell'email di notifica d'ordine al cliente disposto da Magento, è necessario a seguito della conferma dell'ordine da parte del cliente. Qualora non venisse corrisposto un pagamento per tale ordine il cliente e l'esercente potrebbero risalire alla richiesta. Ad ogni modo il cliente può controllare lo status dell'ordine direttamente dal suo pannello di controllo Magento in cui sarà ben evidente il mancato pagamento dell'ordine sottoscritto.
# Servizi Offerti
BNL offre a tutti i commercianti una soluzione di pagamento completa in ogni suo dettaglio. Si rivolge a tutti i tipi di commercianti, dai semplici e piccoli negozi delle PMI italiane alle grandi multinazionali offrendo una soluzione di pagamento all'avanguardia che spazia dalla semplice Hosted 3D Secure alla versione più completa MO.TO nella quale non viene richiesta l’autenticazione 3DSecure del titolare. che consente la richiesta diretta di addebito. Una soluzione su misura per ogni esercente.
## Circuiti Abilitati
e-POSitivity consente di accettare una vasta gamma di circuiti eseguendo una sola integrazione:
* VISA
* VISA Electron
* MASTERCARD
* MAESTRO
* DINERS CLUB
* JCB
* AURA
* NOVA
* AMERICAN EXPRESS
### OPZIONI
* ALIAS / TOKEN / WALLET
## Procedure di sicurezza supportate
* Verify By VISA
* Mastercard SecureCode
## Bonifici Online
* MyBank
## Portafogli Digitali (Digital Wallet)
* Paypal
* Findomestic
* Masterpass
# Pagamenti Supportati
Questa estensione supporta i seguenti metodi di pagamento attraverso la piattaforma messa a disposizione dalla BNL.
* VISA
* MASTERCARD
* VISA ELECTRON
* JBC
* Aura
* Nova
* Paypal
* Masterpass
* American Express
* Diners Club
* Maestro
L’accettazione delle carte Visa, Visa Electron, MasterCard e Maestro è compresa nel contratto di convenzionamento stipulato con BNL POSitivity. Per i circuiti American Express, Diners e JCB è necessario sottoscrivere gli appositi moduli di convenzione con i rispettivi circuiti; la modulistica è disponibile contattando la propria Agenzia BNL, il proprio Agente BNL POSitivity o il Servizio Esercenti. BNL POSitivity provvederà ad inoltrare il contratto e ad attivare il circuito automaticamente al momento della ricezione del codice di convenzione assegnato. Per l'attivazione di Masterpass rivolgersi alla rete di vendita di BNL POSitivity o al servizio di assistenza e-commerce. Per l'attivazione di MyBank rivolgersi alla rete di vendita di BNL POSitivity o al servizio di assistenza e-commerce.
Vi sono due tipologie di pagamenti adottati da BNL:
1. Pagamenti on line
2. Pagamenti diretti
Il modulo per Magento BNL Advanced copre ambedue le metodologie offrendo un pieno supporto al sistema di interconnessione con la BNL.
BNL supporta molti tipi di pagamenti in una sola piattaforma. Tali servizi, per poter essere attivati necessitano delle credenziali rilasciate dalla BNL. Qui di seguito verranno mostrati i servizi per i quali si richiede un'autenticazione:
* Hosted 3D Secure
* MyBank
* Masterpass Wallet
* Paypal
* Findomestic
* Server to Server 3D Secure
* Mo.To (Mail Order / Telephone Order)
# Pagamenti On Line
Questa è l’ opzione più semplice e sicura, consiste nell’utilizzo di una pagina di pagamento fornita da BNL POSitivity e residente sui nostri server. In questo caso, il titolare di carta verrà indirizzato sulle pagine di BNL POSitivity al momento del pagamento e potrà inserire i dati della carta di credito direttamente sul sito di BNL POSitivity, protetto con certificato SSL. Successivamente, il cliente titolare di carta verrà reindirizzato nuovamente al vostro sito Web, a cui trasmetteremo i dettagli relativi all’esito del pagamento.
Il modulo si occuperà di recuperare tutti i dati necessari dall'ordine creato in Magento per richiedere alla BNL l'autenticazione e la richiesta d'uso del servizio di pagamento.
Il cliente seguirà questo percorso:
Negozio **>** Carrello **>** Conferma Ordine **>** Reindirizzamento al sito sicuro della banca **>** Raccolta dei dati (carta di credito) **>** Controlla l'iscrizione al servizio 3D Secure e richiede l'eventuale password **>** Esito della transazione **>** Reindirizzamento sulla pagina di conferma dell'esercente.
La pagina della BNL è personalizzabile ma bisogna far richiesta alla banca per la modifica.
# Pagamenti Diretti
In questa modalità, **la pagina di pagamento risiede sul server dell’esercente**, quindi, dopo che il titolare di carta (cliente) ha concluso gli acquisti, cliccando su “paga” dal carrello verrà indirizzato in una pagina (modulo), dove inserirà i dati necessari per effettuare una transazione (PAN, data scadenza, CCV2).
Il modulo di pagamento include un sistema integrato compatibile con la maggior parte delle estensioni più conosciute di checkout in commercio.
## Integrazione con il checkout (Interfacce)
L'estensione di pagamento si adatta al sistema integrato del carrello del negozio Magento. La comunicazione fra il server dell'esercente e la banca avvengono attraverso il sistema API della BNL. Il cliente non noterà tale processo.
Per i pagamenti con carta di credito, i dati sono trasferiti via API fornite da BNL attraverso tutta la fase di checkout dell'ordine per controllare e salvare le informazioni sensibili nei server della BNL con connessione sicura. Lo stato delle transazioni vengono inviate dalla BNL in un secondo momento, aggiornando lo status corrente dell'ordine mantenendo una sincronia fra i due sistemi (banca/magento).
# Caratteristiche
La modalità server to server consente di avere un modulo di inserimento della carta di credito direttamente nella pagina di checkout di Magento e permettere ai clienti di inserire i propri dati sensibili durante la fase di checkout. **Il proprietario del negozio Magento dovrà fornire alla propria banca dietro richiesta da parte della BNL un documento che attesti il rispetto delle regole indicate nel prospetto di sicurezza delle transazioni on line PCI DSS**. La banca può in qualsiasi momento interrompere il servizio di POS Virtuale ritenendo responsabile di qualsiasi danno alla banca stessa nonchè alla clientela il proprietario del negozio.
Durante la fase di checkout il negozio Magento dovrà offrire garanzie ai visitatori attraverso una politica di sicurezza di alto livello, offrendo una connessione sicura SSL ed un supporto tecnico ai visitatori/acquirenti.
## Payment Card Industry Data Security Standard (PCI DSS)
Quando viene utilizzata l'estensione di pagamento BNL per Magento, non è necessario fornire la certificazione PCI DSS. Le informazioni che vengono trasmesse con tecnologia AJAX, utilizzata dal client API della BNL assicura che il negozio Magento non sia a diretto contatto con i dati relativi alla carta di credito, perchè il cliente trasferirà i dati relativi alla carta di credito direttamente dal suo client a BNL. Le varie integrazioni offerte da BNL consentono un pieno controllo della sicurezza delegando proprio a quest'ultima la responsabilità della raccolta delle informazioni sensibili (Hosted Solution 3DSecure). Durante tale procedura, al cliente cliente verrà richiesta l'immissione del numero di carta di credito nel sito protetto della banca.
**Cos’è lo standard PCI-DSS?**
Lo standard PCI-DSS (Payment Card Industry Data Security Standard) è stato elaborato con lo scopo di uniformare le modalità di gestione della sicurezza dei dati delle carte di credito da parte del consorzio PCI creato da American Express, Discover Financial Services, JCB, MasterCard Worldwide e Visa International.
**Chi si deve adeguare?**
Lo standard deve essere rispettato da tutte le entità (esercenti, service provider, banche) coinvolte in una transazione mediante carta di credito che comporti la trasmissione, l’utilizzo o la memorizzazione del Primary Account Number (PAN) della carta. Tutti i settori commerciali ne sono interessati.
## Logging & Debug
Qualsiasi comunicazione con BNL viene registrata in un file di log e può essere utilizzato per il supporto, il test e operazioni di debug dai tecnici del negozio Magento. Le richieste di status delle transazioni di pagamento inviate via API a BNL ed i dati dei processi di pagamento integrati in cui viene richiesta la carta di credito sono esclusi da questo log.
## Configurazione e gestione delle opzioni dell'estensione
L'estensione offre un nuovo menù BNL nell'are amministrativa di Magento. Questo contiene l'accesso a tutte le configurazioni ed opzioni del modulo, così come l'impostazione degli account di accesso, dei file di log ed altre informazioni.
# Requisiti Minimi
Negozio **Magento**:
* Versione: Community dalla release 1.9.3.x
* Versione: Community dalla release 2.x
**Estensioni richieste nel server:**
* simplexml
* mcrypt
* hash
* GD
* DOM
* iconv
* curl
* SOAP (per Webservices API)
# Installazione
# Magento 1.x
Prima di ogni installazione e modifica strutturale di Magento, **è caldamente consigliato effettuare un backup dei dati e dei files** ed accertarsi di aver effettuato un backup corretto. Solo dopo tale operazione potrete effettuare l'**installazione prima nel vostro ambiente di sviluppo** e successivamente nel vostro ambiente di produzione.
Dopo aver acquistato il modulo di pagamento riceverete il file compresso che contiene il modulo via email. Decomprimete il file ricevuto nel vostro computer ed inviate il contenuto della cartella scompattata, all'infuori del file di pdf, nella cartella di **root del vostro sito internet** via [FTP](https://it.wikipedia.org/wiki/File_Transfer_Protocol). Entrate nell'area amministrativa di Magento (se eravate già dentro l'area amministrativa scollegatevi e ricollegatevi).
* Svuotare la **Cache di Magento**
* Accedete a: **Sistema > Configurazione** > **Metodi di Pagamento** , troverete il nuovo modulo installato oppure a **Vendite** > **Metodi di Pagamento** > **BNL > Configurazione**
* Se si era già connessi nell'area amministrativa di magento disconnettersi e rieffettuare il login.
## Aggiornamento del modulo
Il nuovo modulo ufficiale della BNL richiede un'attenta pulizia del sistema dal vecchio modulo presente nel vostro negozio Magento. Per disinstallare il modulo bisogna prima di tutto preparare una **copia di backup** del sito internet (**files/database**) e successivamente cancellare le seguenti [cartelle e files](https://gist.githubusercontent.com/shinesoftware/daedf66f417bd08a43c3da3e3e5735f0/raw/76af75ae6c327b869987f8222f25f8048c2c495d/consorzio-triveneto-3.8.txt) e cancellare all'interno della tabella core\_config\_data i records legati al modulo. Bisogna fare attenzione al prefisso delle cartelle di Magento usato in fase di installazione del software e modificare la query proposta di seguito con il proprio prefisso.
Ecco la query per comodità:
> DELETE from core\_config\_data where path like '%epositivity\_cc%';
Se non si aggiornano anche i records collegati al metodo di pagamento si rischia un errore nella griglia ordini. Per far conoscere a Magento che il modulo è stato modificato eseguire la seguente query:
> UPDATE sales\_flat\_order\_payment set method = 'epositivity\_hosted' WHERE method = 'epositivity\_cc';
La Shine Software **offre un servizio dedicato all'aggiornamento dei dati e dei moduli Magento a pagamento**. Se qualcosa non dovesse andare per il verso giusto, ripristinate il database ed i file all'ultimo backup e chiedete la nostra assistenza.
La richiesta di assistenza tecnica per qualsiasi errore riscontrato durante la fase di installazione, configurazione, uso del modulo avrà un **costo di un'ora di** [**Assistenza Tecnica Magento**](http://www.shinesoftware.com/programmatore-magento.html) per il controllo, la correzione e la riconfigurazione del modulo. Per qualsiasi richiesta di assistenza usare il gestore delle segnalazioni.
## Permessi di Files e Cartelle
I permessi dei files e delle cartelle del modulo di pagamento devono seguire lo standard richiesto da Magento. L'utente proprietario dei files e delle cartelle deve essere lo stesso utente usato dal webserver (Apache / nGinx). Quindi, tranne nel caso in cui si effettua l'upload usando delle credenziali differenti da un utente riconosciuto dal sistema come proprietario del progetto del vostro negozio, non si dovranno impostare dei permessi specifici dopo il caricamento del modulo via FTP. Ad ogni modo i permessi da adottare per un progetto Magento sono ampiamente discussi nel sito internet della [Magento](http://devdocs.magento.com/guides/m1x/install/installer-privileges_after.html).
## Reset Configurazione
Per effettuare un reset della configurazione del modulo basta eseguire una query nel database oppure semplicemente far click sulla funzione Reset presente nel pannello di controllo del modulo:\
## Menu
Il menù amministrativo Magento permette una scorciatoia diretta alla configurazione del modulo. Vedi foto.
## Compilazione
Se il negozio magento ha la funzionalità di compilazione attivata, bisognerà ricompilare il codice e fare attenzione durante la compilazione affinchè tutti i file richiesti dal modulo siano stati correttamente spostati nella cartella /includes
## Configurazione & Cache
Durante la fase di configurazione, **Magento potrebbe ripresentare i vecchi dati di configurazione**. Bisogna fare molta attenzione alla Cache di Magento che mantiene tutti i dati di configurazione. Anche se il sistema presenta la gestione Cache disabilitata è consigliato un aggiornamento.
# Magento 2.x
{% hint style="info" %}
Prima di ogni installazione e modifica strutturale di Magento, **è caldamente consigliato effettuare un backup dei dati e dei files** ed accertarsi di aver effettuato un backup corretto. Solo dopo tale operazione potrete effettuare l'**installazione prima nel vostro ambiente di sviluppo** e successivamente nel vostro ambiente di produzione.
{% endhint %}
### Installazione via Shell
Se si desidera installare il modulo via shell bisogna eseguire il seguente comando dalla root di Magento.
```
composer config repositories.core vcs git@bitbucket.org:shinesoftware/core.git
composer config repositories.bnl vcs git@bitbucket.org:shinesoftware/bnl.git
composer require shinesoftware/core:dev-master
composer require shinesoftware/bnl:dev-master
```
All'esecuzione del comando il software *composer* avvierà la procedura di recupero del *repository* presso bitbucket.org.
{% hint style="info" %}
Bisogna fare attenzione all'ultimo comando che determina la versione da scaricare. Verrà sempre installata l'ultima versione del modulo ma nello stesso tempo bisogna fare attenzione alle dipendenze da installare. Vedi capitolo [dipendenze](/installazione/magento-2/dipendenze).
{% endhint %}
**Per poter connettere il vostro composer al repository ufficiale serve una chiave SSH valida che permetterà al sistema Bitbucket.org di inviarvi il pacchetto.**
{% hint style="info" %}
Per poter recuperare la chiave pubblica in un server unix-like dovrete eseguire il seguente comando nel terminale linux:
cat \~/.ssh/id\_rsa.pub
{% endhint %}
> Dopo aver copiato la chiave pubblica dovrete aprire una segnalazione su e richiederne la registrazione per il dominio indicato in fase di acquisto.
{% hint style="info" %}
Molte volte le chiavi pubbliche di un server vengono registrate in bitBucket e non possono essere utilizzate anche per il suddetto uso.
{% endhint %}
In questi casi bisogna creare una nuova chiave ed utilizzarla all'aggiornamento del modulo attivandola con i seguenti comandi:
```
ssh-keygen << creare una chiave con il nome id_shinesoftware
cat ~/.ssh/id_shinesoftware.pub << chiave da inviare alla shinesoftware
eval $(ssh-agent) << attivazione dell'agente ssh
ssh-add ~/.ssh/id_shinesoftware << attivazione della nuova chiave nel vostro server
```
# Dipendenze
Installazione e recupero delle dipendenze PagOnline
## Installare le dipendenze
Per generare le richieste alla banca il modulo si avvale della dipendenza PagOnline. Per installare la giusta dipendenza bisogna prima di tutto conoscere il proprio ambiente di produzione ed in particolare la versione del PHP.
Per installare la versione della dipendenza che utilizza un PHP <= 7.1 bisogna eseguire il seguente comando:
```
composer require mattiabasone/PagOnline:v1.0.1
```
Qualora la versione sia superiore alla PHP 7.1 bisogna eseguire il seguente comando:
```
composer require mattiabasone/pagonline:v2.1.0
```
Senza tale dipendenza il modulo BNL non riuscirebbe a generare le richieste alla banca generando un blocco di Magento.
# Disinstallazione
La disinstallazione di un modulo dentro Magento 2.x è molto semplice: basta cancellare i le righe che sono state inserite dentro il file composer.json oppure eseguire i seguenti comandi:
```
composer remove shinesoftware/bnl
composer config --unset repositories.bnl
```
Bisogna anche pulire il proprio database e per poterlo fare eseguite quanto riportato qua in basso.
{% hint style="info" %}
Aprire il proprio database collegato a Magento e cancellare le occorrenze legate alla configurazione del modulo dentro la cartella **core\_config\_data** per rendere il proprio archivio pulito.
{% endhint %}
# Template Personalizzato
I file di stile ed i file di layout standard del modulo sono posizionati nella cartella
* /app/design/frontend/base
* /app/design/adminhtml/default
Qualora il template installato nel negozio non rispetti la gerarchia del Core di Magento il modulo potrebbe non mostrare le interfacce grafiche non generando un errore visibile. Controllare i file system.log ed exception.log per comprendere dove il vostro template si aspetta di trovare i files.
Il modulo ha in sè alcune porzioni di template presenti dentro la cartella /app/design/frontend/**base** come indicato sopra. La path base indica che se Magento non dovesse trovare i file dentro al template personalizzato risalirebbe al "**template base**" nel quale vi sono tutti i files di template del core di Magento compresi anche i files del modulo.
*I file template di successo e di fallimento vengono sovrascritti. Qualora vi fossero delle funzionalità integrate direttamente nei file di template delle suddette pagine, bisogna controllare se il metodo di "innesto" del codice personalizzato rispetti il sistema di layout di Magento. Se, ad esempio, un codice javascript **è stato "incollato" all'interno del template** della pagina di successo e/o fallimento del proprio tema/template, bisogna correggerne il metodo di inserimento via blocchi creando un'apposita estensione, così come indicato dalle linee guida di innesto dei blocchi statici di Magento.*
In questi casi basterebbe un controllo approfondito del template Magento accertandosi della correttezza delle path usate nel caricamento del layout.
## Personalizzazione del Redirect
E' possibile conoscere tutti i blocchi generati dal modulo dal file di layout che si trova in */app/design/frontend/base/default/layout/nomemodulo.xml*
Le pagine di redirect sono definite sotto l'elemento: "**\[nomemodulo]\_\[metododipagamento]\_redirect**". E' possibile creare un blocco statico ed aggiungerlo usando un innesto del blocco nel file xml.
Quindi ricapitolando:
1. Creare il blocco statico in Magento
2. Modificare il file di layout precedentemente creato inserendo il blocco statico con il comando indicato di seguito
3. Aggiornare la cache di Magento
> \\
> \\page/1column.phtml\\\
> **\**\
> **\**\
> **\your\_block\_id\_1\**\
> **\**\
> **\**\
> \
In questo modo durante la creazione della pagina di redirect magento intercetterà che bisognerà includere il nuovo blocco statico.
## Cache System
Prima di ogni operazione sui files di template di Magento bisogna accertarsi che nel negozio non sia attiva alcun tipo di cache. Quindi disabilitare tutte le cache attive come ad esempio:
* Cache interna di Magento
* Cache APC o Varnish, xCache, ecc...
* Compilazione del codice sorgente di Magento
E' possibile richiedere assistenza all'installazione del modulo ai tecnici della Shine Software scegliendo il servizio Installazione e Configurazione Moduli Magento presente nel sito internet [www.shinesoftware.it](https://www.gitbook.com/book/shinesoftware/consorzio-triveneto/edit#).
# Lingue & Traduzioni
per modificare la lingua in un negozio multiview dovreste impostare le varie view alle lingue presenti in Magento.
Ad esempio:
* Store A
* Italiano (View)
* Locale Italiano (Italia)
* Inglese (View)
* Locale English (United States)
In questo modo quando gli utenti selezioneranno la versione italiana o inglese il modulo riconoscerà la lingua assegnata alla view.
Ecco un esempio relativo all'impostazione della lingua inglese per la view dedicata alla versione inglese del negozio.
## Come tradurre il testo contenuto dentro il modulo?
Il modulo offre una traduzione in Italiano ed in Inglese utilizzando un file csv contenuto dentro la cartella app/locale/it\_IT/Shinesoftware\_NomeModulo.csv (magento 1.9.x) e app/code/Shinesoftware/NOME-MODULO/i18n/en\_US.csv (versione inglese per Magento 2.x).
Per aggiungere una lingua e/o aggiungere delle traduzioni basta creare/modificare i seguenti files:
* app/code/Shinesoftware/NOME-MODULO/i18n/**it\_IT**.csv (magento 2.x)
* app/locale/**it\_IT**/Shinesoftware\_NomeModulo.csv (Magento 1.9.x)
Per creare il file serve un semplice editor di testo come il blocco note di Windows o TextWrangler per Mac. Il file deve essere caricato sul server nella posizione su indicata. Il testo da tradurre deve essere così composto:
> "This text must be translated", "Questo testo deve essere tradotto"
Bisogna fare attenzione alle virgolette ed alla virgola separatrice. Ogni frase deve essere racchiusa fra le virgolette e separata con la virgola. Ogni frase deve essere su inserita in una linea differente.
Al termine dell'operazione bisogna aggiornare la cache di Magento.
Il testo da tradurre si trova sempre dentro i files .phtml a vostra disposizione dentro le seguenti percorsi:
* app/code/Shinesoftware/NOMEMODULO/view/frontend/templates/...
* app/design/frontend/base/default/template/NOMEMODULO/...
Aprire i file con un editor di testo e recuperare il testo da tradurre copiandolo nel file csv che avete precedentemente creato. Ad esempio, in un file \*.phtml di un modulo per Magento 1.9.x potreste trovare:
> \\_\_("If you are the store owner check the log files in your Magento store and contact the bank helpdesk") ?>
e nella versione Magento 2.x potreste trovare:
> \\_\_("If you are the store owner check the log files in your Magento store and contact the bank helpdesk.") ?>
Per tradurre le suddette frasi bisogna recuperare solamente ciò che appare fra le virgolette:
* If you are the store owner check the log files in your Magento store and contact the bank helpdesk
e riportare la frase nel file csv precedentemente creato:
> "If you are the store owner check the log files in your Magento store and contact the bank helpdesk.", "Se sei il proprietario del negozio controlla i file di log nel tuo negozio Magento e contatta il supporto della banca"
Come detto in precedenza, dopo aver caricato il file nella stessa posizione sul server, bisogna aggiornare la cache di magento e la traduzione apparirà.
Qualora non doveste riuscire a tradurre qualcosa, potete richiedere il servizio [Programmatore Magento](https://shinesoftware.it/programmatore-magento.html), ed un nostro tecnico creerà l'integrazione per voi.
# Configurazione Generale
Dopo aver installato il modulo, vedi sezione installazione, l'esercente deve configurare il proprio negozio Magento con le credenziali di test offerte dalla banca.
Si consiglia di effettuare diversi test di acquisto prima di passare in produzione per controllare se le varie fasi di autorizzazione, cattura, e storno funzionano correttamente nel proprio negozio.
Al termine di una transazione di pagamento per un dato ordine, il modulo di pagamento prevede un continuo scambio di informazioni via API fra il negozio Magento e BNL che determinano lo status del pagamento. La banca contatterà il server del cliente, che deve essere accessibile da remoto senza alcuna password, per ricevere le modifiche dello status degli ordini eseguiti.
## Pannello di Configurazione Soluzioni BNL
Il pannello di configurazione delle soluzioni di pagamento della BNL si mostra molto complesso a prima vista poiché le soluzioni di pagamento offerte sono moltissime. Il software Magento integra perfettamente tali soluzioni offrendo un metodo di visualizzazione delle configurazioni diviso in pannelli annidati.
# Soluzioni di Pagamento
Per semplificare le attività di realizzazione dell’interfaccia al “**Payment Gateway**”, BNL ha studiato degli specifici plug-in che vengono forniti al Merchant e che consentono una rapida integrazione delle funzioni di pagamento all’interno del proprio sistema.Sfruttando il modulo di pagamento della Shine Software l'esercente potrà integrare velocemente il metodo di pagamento in pochi minuti e disporre di un POS Virtuale.
# MO.TO (Mail Order / Telephone Order)
## MO.TO. (Mail Order/Telephone Order)
Con la parola MO.TO. (Mail Order/Telephone Order) indichiamo i pagamenti effettuati in modalità Server to Server, nei quali **non viene richiesta l’autenticazione 3DSecure** del titolare. La modalità **server to server** utilizzata dalla gestione MO.TO prevede l’autorizzazione on line della richiesta di pagamento, con invio da parte dell’azienda venditrice dei dati relativi alla carta di credito. Questa modalità è utilizzata anche per la richiesta dei pagamenti relativi ad ordini ricevuti tramite gli altri canali di vendita (ad esempio corrispondenza, telefono, m-commerce, etc.).
In questi casi, la fase di pagamento si esaurisce con l’invio verso BNL di una richiesta di pagamento contenente tutti i dati necessari per effettuare il pagamento e la ricezione di una risposta in modalità sincrona contenente l’esito del pagamento stesso. Nei casi in cui è previsto che il titolare sottoponga i dati relativi alla propria carta di credito direttamente al sistema del Commerciante, **lo stesso è soggetto alle normative PCI-DSS**; BNL si riserva la possibilità di richiedere un documento che ne attesti la certificazione.
### Creazione Ordine Amministrazione MO.TO
Nell'area amministrativa degli ordini di Magento è possibile realizzare un ordine usando in combinazione al metodo MO.TO al fine di effettuare un pagamento diretto sfruttando la tecnologia Magento ed il POS Virtuale della BNL. Tale funzionalità è prevista solamente per contratti in cui l'esercente potrà effettuare Autorizzazioni dirette senza il sistema 3D Secure. Contattare la propria banca per ulteriori dettagli.
### Configurazione Server to Server & MO.TO
Dopo aver avuto accesso nel pannello di controllo amministrativo di Magento bisogna far click nella voce di menu BNL > Configuration > BNL Payment Solutions > MO.TO (Mail Order / Telephone Order). Il pannello di controllo del metodo si presenterà come da foto.\
### Required Settings
Le impostazioni richieste minime si trovano in questo pannello. Configurando questo pannello, il modulo sarà funzionante sia nell'area amministrativa di Magento che nell'area pubblica. Di seguito una foto della sezione.\
## 3D Secure Server to Server (Frontend)
La soluzione **server to server** sfruttata dal modulo Magento permette al cliente di effettuare il pagamento immediato inserendo i dati della propria carta di credito direttamente nella pagina protetta del negozio Magento.
Ecco un esempio di visualizzazione della sezione del metodo di pagamento direttamente all'interno di uno dei moduli Magento più famosi: "One Step Checkout".\
### Integrazione
Il metodo di pagamento si integra in Magento sfruttando tutte le funzionalità del CORE del software eCommerce al fine di eseguire i pagamenti onsite.
# Hosted 3DSecure
La soluzione Hosted 3D Secure offre agli esercenti **un modo semplice, veloce e sicuro per ricevere i pagamenti con carta di credito, e digital wallet**, dai loro clienti utilizzando un redirect durante la fase di pagamento al sito sicuro della banca.
Tale soluzione **non richiede alcuna certificazione di sicurezza PCI-DSS** poichè la sicurezza della transazione di pagamento viene delegata all'istituto BNL. Il cliente si troverà in **un sito internet protetto e sicuro** in cui potrà indicare le informazioni sensibili quali carta di credito e/o password ai servizi Digital Wallet.
La pagina visualizzata dal cliente viene chiamata "**Hosted Payment Page**" e viene selezionata in base alla richiesta effettuata dal modulo di pagamento. Le soluzioni offerte della BNL sono disponibili alla pagina "[Pagamenti Supportati](/pagamenti-supportati)".
## Magento Checkout
Durante la fase di checkout del carrello in Magento, ed in particolare durante la selezione del metodo di pagamento attivo nel negozio, il cliente visualizzerà il nome del metodo di pagamento, una descrizione scelta dall'esercente ed un avviso di reindirizzamento alla conferma dell'ordine.
# MyBank (SEPA Credit Transfer)
MyBank è una soluzione di autorizzazione elettronica che consente ai consumatori di **effettuare in modo sicuro pagamenti online e autenticazioni dell’identità digitale usando il servizio di online banking delle propria banca**.
**MyBank crea un collegamento diretto online tra il conto corrente bancario del cliente e la banca dell’esercente**, evitando di richiedere e memorizzare dati personali. **L’identità digitale del cliente e i suoi dati sensibili sono sempre protetti.** L’autorizzazione immediata dei pagamenti riduce il rischio di frodi e ri-addebiti. Grazie a MyBank le transazioni online avvengono con più fiducia e serenità.
MyBank e-payment consente di ottenere, **in tempo reale**, **un’autorizzazione per il trasferimento di fondi dal conto bancario del cliente a quello dell’esercente online**, utilizzando un bonifico SEPA.
## Configurazione
Dopo aver avuto accesso nel pannello di controllo amministrativo di Magento bisogna far click nella voce di menu BNL > Configuration > BNL Payment Solutions > MyBank (SEPA Credit Transfer). Il pannello di controllo del metodo si presenterà come da foto.
## Required Settings
Le impostazioni richieste minime si trovano in questo pannello. Configurando questo pannello, il modulo sarà funzionante sia nell'area amministrativa di Magento che nell'area pubblica. Di seguito una foto della sezione.
## Controllo delle Transazioni (cronjob)
I bonifici bancari ormai sono diventati molto veloci. Un tempo bisognava attendere giorni, adesso sono molto veloci e non serve più attendere molti giorni prima di chiedere alla banca se il proprio denaro è stato contabilizzato. Il modulo permette di richiedere dei bonifici veloci grazie all'accordo con MyBank a tutti i potenziali clienti. Gli ordini pagati con MyBank seguono un percorso un pò diverso dal pagamento Hosted con carte di credito e bisogna fare attenzione ad alcune particolarità durante la configurazione del modulo.
Dopo l'avvenuto pagamento con MyBank, l'ordine generato risulterà in attesa finchè il cronjob non chiederà alla banca lo status della transazione. Per impostare la frequenza di richiesta di aggiornamento dell'ordine bisogna impostare il campo Payment Cron Inquiry presente nel pannello di configurazione del modulo nella sezione dedicata alle impostazioni di sistema del metodo MyBank.
Se nessun valore viene impostato nel suddetto parametro, Magento controllerà tutti gli ordini generati con "bnl mybank" e con status "pending payment" la cui data di creazione rientra in massimo di 15 minuti. Il metodo fornito dalla banca è "verify" che permette di conoscere lo status della transazione in modo asincrono. Se la transazione è stata autorizzata, l'ordine passerà nello status "processing" o "in elaborazione". In caso contrario l'ordine verrà cancellato.
E' possibile richiedere se la transazione è andata a buon fine anche utilizzando l'apposito bottone presente nel pannello degli ordini. Il bottone apparirà in alto, vicino agli altri bottoni solamente nel caso in cui lo status dell'ordine non è impostato come completato. L'operazione richiederà qualche secondo ed il risultato verrà mostrato in un messaggio. Ulteriori informazioni sono sempre presenti nel [file di log](/logging-debug-ed-errori-comuni).
## Testing
Per effettuare un test utilizzando il sistema MyBank bisogna prima di tutto inserire un prodotto a carrello e procedere verso il chekout di Magento. Selezionare il metodo di pagamento BNL MyBank.
**Attenzione**: *L'ambiente di test della BNL non risulta fruibile. Per effettuare un test dovreste passare in produzione e simulare un vera e propria transazione.*
# Findomestic
Qualora il cliente desiderasse l’attivazione del circuito Findomestic al fine di accettare transazioni con carte Aura e Nova, sarà necessario che sottoscriva il contratto; il modulo potrà essere richiesto direttamente a Findomestic o mediante la rete di vendita di BNL POSitivity.Configurazione
Dopo aver avuto accesso nel pannello di controllo amministrativo di Magento bisogna far click nella voce di menu BNL > Configuration > BNL Payment Solutions > Findomestic. Il pannello di controllo del metodo si presenterà come da foto.
## Required Settings
Le impostazioni richieste minime si trovano in questo pannello. Configurando questo pannello, il modulo sarà funzionante sia nell'area amministrativa di Magento che nell'area pubblica.
## Magento Checkout
Durante la fase di checkout del carrello in Magento, ed in particolare durante la selezione del metodo di pagamento attivo nel negozio, il cliente visualizzerà il nome del metodo di pagamento, una descrizione scelta dall'esercente ed un avviso di reindirizzamento alla conferma dell'ordine. Il cliente verrà indirizzato sulla pagina di pagamento di BNLPOSitivity come nel caso del pagamento "Hosted 3DSecure".
# Paypal
L’esercente che vuole attivare PayPal sul POS virtuale ePOSitivity deve:
* attivare un conto PayPal Business dal sito dal sito [www.paypal.it](http://www.paypal.it) e, in caso di necessità di assistenza, chiedere ad un operatore di PayPal chiamando il numero verde 800 976 359 del Gruppo Attivazione Commercianti;
* richiedere le abilitazioni necessarie alle API PayPal per consentire l’esecuzione di transazioni da e–POSitivity;
* l'esercente, ricevuta l’abilitazione da PayPal, segnala a l'esito fornendo:
* API Username
* API Password
* Signature
* BNL POSitivity provvede ad abilitare PayPal sul POS virtuale e-POSitivity.
Dopo aver avuto accesso nel pannello di controllo amministrativo di Magento bisogna far click nella voce di menu BNL > Configuration > BNL Payment Solutions > Paypal. Il pannello di controllo del metodo si presenterà come da foto.
## Required Settings
Le impostazioni richieste minime si trovano in questo pannello. Configurando questo pannello, il modulo sarà funzionante sia nell'area amministrativa di Magento che nell'area pubblica.
## Magento Checkout
Durante la fase di checkout del carrello in Magento, ed in particolare durante la selezione del metodo di pagamento attivo nel negozio, il cliente visualizzerà il nome del metodo di pagamento, una descrizione scelta dall'esercente ed un avviso di reindirizzamento alla conferma dell'ordine. Il cliente verrà indirizzato sulla pagina di pagamento di BNLPOSitivity come nel caso del pagamento "Hosted 3DSecure".
# MasterPass
**MasterPass** by MasterCard di MasterCard è un servizio di wallet elettronico che rende lo shopping online sicuro, semplice e conveniente. **MasterPass** by MasterCard memorizza tutte le informazioni di pagamento e spedizione in un luogo centralizzato e protetto.
Dopo aver inserito gli articoli nel carrello online e una volta pronto a eseguire il checkout, fai clic o tocca il pulsante per il checkout; **Buy With MasterPass** (Acquista con MasterPass) e seleziona il tuo wallet collegato a MasterPass by MasterCard. Potrai fare clic su: **Sign in** (Accedi) dalla pagina di checkout o dopo essere stato reindirizzato a MasterCard. Dopo l’accesso, potrai scegliere la carta e l’indirizzo di spedizione da utilizzare tra quelli memorizzati. Se desideri usare una carta o un indirizzo di spedizione che non hai ancora aggiunto a MasterPass by MasterCard, fai clic o tocca l’opzione **Add** (Aggiungi).Dopo la scelta della carta e dell’indirizzo di spedizione, potrai rivedere il tuo ordine prima di procedere al checkout.
## Configurazione
Dopo aver avuto accesso nel pannello di controllo amministrativo di Magento bisogna far click nella voce di menu BNL > Configuration > BNL Payment Solutions > Masterpass. Il pannello di controllo del metodo si presenterà come da foto.
## Required Settings
Le impostazioni richieste minime si trovano in questo pannello. Configurando questo pannello, il modulo sarà funzionante sia nell'area amministrativa di Magento che nell'area pubblica.
## Magento Checkout
Durante la fase di checkout del carrello in Magento, ed in particolare durante la selezione del metodo di pagamento attivo nel negozio, il cliente visualizzerà il nome del metodo di pagamento, una descrizione scelta dall'esercente ed un avviso di reindirizzamento alla conferma dell'ordine. Il cliente verrà indirizzato sulla pagina di pagamento di BNLPOSitivity come nel caso del pagamento "Hosted 3DSecure".
# Digital Wallet
**Il Digital Wallet** è un portafoglio virtuale che consente agli utenti di effettuare pagamenti – online o all’interno di negozi fisici – mediante dispositivi elettronici. In altre parole è uno strumento sicuro in grado di memorizzare numeri di carte di credito, debito, prepagate o di conti bancari per effettuare pagamenti in modo rapido e semplice.
Il portafoglio virtuale è la soluzione più sicura per i pagamenti digitali: consente di effettuare pagamenti semplicemente creando un account gratuito e inserendo il proprio indirizzo email. In seguito alla creazione dell’account, l’utente potrà abilitare pagamenti senza condividere i propri dati personali.
Tutte le informazioni personali dell’utente vengono conservate all’interno di appositi ambienti protetti esterni alle pagine online, rendendo il pagamento particolarmente sicuro.
## Configurazione
Dopo aver avuto accesso nel pannello di controllo amministrativo di Magento bisogna far click nella voce di menu BNL > Configuration > BNL Payment Solutions > Digital Wallet. Il pannello di controllo del metodo si presenterà come da foto.
## Required Settings
Le impostazioni richieste minime si trovano in questo pannello. Configurando questo pannello, il modulo sarà funzionante sia nell'area amministrativa di Magento che nell'area pubblica.
## Magento Checkout
Al primo acquisto il cliente inserirà i dati della carta di credito nel sito sicuro della banca e completerà il suo ordine. Se l'ordine verrà completato con successo, e l'opzione su indicata risulta essere attiva, i dettagli della carta di credito verranno salvati dentro i server della banca.
Quindi al secondo acquisto e durante la fase di checkout del carrello in Magento, il cliente visualizzerà il nome del metodo di pagamento, una descrizione scelta dall'esercente ed un avviso di reindirizzamento alla conferma dell'ordine dove troverà i suoi dati carta precedentemente inseriti.
# Fatturazione Automatica
Alcuni esercenti necessitano l'opzione della fatturazione automatica e la "cattura" dell'importo presente in fattura. La cattura (vedi contabilizzazione dei metodi di pagamento) permette di richiedere contestualmente il denaro indicato durante la fase di autorizzazione del pagamento. Tale opzione permetterà all'esercente di far generare in automatico la fattura a Magento e la conseguente "cattura online" dell'importo presente nell'ordine.
Per attivare tale opzione è possibile accedendo nella sezione Store > Configuration > Sales > Payment Method > BNL > Common Options > Auto Invoice: Yes
Abilitando tale opzione il software Magento comunicherà al modulo di pagamento di effettuare una richiesta di movimentazione contestualmente alla generazione della fattura.
Attenzione! Tale opzione è disponibile solamente nella versione del modulo di pagamento BNL ePOSitivity per Magento 2.
# Status Ordini
In fase di inizializzazione della transazione il server della banca invia una comunicazione sull'esito al modulo Magento.
Il processo di notifica può avvenire esclusivamente attraverso le porte 80 e 443.
I tentativi di comunicazione seguono le seguenti regole:
1. Al termine del pagamento il sistema della banca esegue una richiesta a Magento.
2. Il primo tentativo è fatto al termine della transazione dell'utente.
3. Se il primo tentativo di notifica non va a buon fine, i contatti verso il server dell'esercente verranno tentati ogni ora fino ad una corretta risposta. Verranno selezionate le transazioni eseguite e non notificatedelle ultime 24 ore e fino ad un‘ora prima dell'esecuzione dell'autorizzazione.
# Test & Live Mode
## Test & Live Mode
La BNL mette a disposizione degli esercenti un accesso diretto ai metodi di pagamento offerti usando delle credenziali di test che permettono di controllare il corretto funzionamento delle varie soluzioni. E' possibile inoltre simulare le transazioni di pagamento in un ambiente protetto ed identico all'ambiente di produzione usando alcune carte di credito di test. Vi sono degli accorgimenti da adottare durante le fasi di test:
* non si può testare il modulo se la banca non riesce a connettersi al dominio in cui è installato il modulo. Il dominio deve essere accessibile pubblicamente.
* il negozio Magento deve essere accessibile (frontend) senza password (vedi htpasswd).
Alla sottoscrizione dei servizi POS Virtuali, la banca rilascerà le credenziali di test per effettuare alcuni test direttamente nel vostro negozio usando il modulo della Shine Software.
## Configurazione per la modalità di TEST
Per impostare il negozio Magento in modalità di test bisogna impostare i seguenti parametri necessari per la connessione corretta al server di test:
1. Tranportal ID (vedi tabella di seguito)
2. Password
3. **Debug: YES**
## Configurazione per la modalità LIVE
Per impostare il negozio Magento in modalità di LIVE bisogna impostare i seguenti parametri necessari per la connessione corretta al server LIVE:
1. Tranportal ID (Ufficiale)
2. Password (Ufficiale)
3. **Debug: NO**
Attenzione! Se la password risulta scaduta, l'accesso al servizio POS verrà inibito generando un errore di **Invalid Tranportal ID** vedi capitolo: [Logging, Debug, Errori Comuni](/logging-debug-ed-errori-comuni)
## Credenziali & Carte di Credito di Test
La BNL mette a disposizione degli esercenti un accesso diretto ai metodi di pagamento offerti usando delle credenziali di test che permettono di controllare il corretto funzionamento delle varie soluzioni. E' possibile inoltre simulare le transazioni di pagamento in un ambiente protetto ed identico all'ambiente di produzione usando alcune carte di credito di test. Vi sono degli accorgimenti da adottare durante le fasi di test:
* non si può testare il modulo se la banca non riesce a connettersi al dominio in cui è installato il modulo.
* Il dominio e di conseguenza il negozio Magento devono essere accessibili pubblicamente.
Impostazioni del modulo nella sezione amministrativa:
Per poter configurare un accesso diretto per effettuare i test utilizzare le seguenti credenziali:
| | Terminal ID | kSIG (Password) | Credenziali TEST |
| ---------- | ----------- | ---------------------------- | ---------------------------------------------------------- |
| Hosted | 08000001 | xHosiSb08fs8BQmt9Yhq3Ub99E8= | - |
| MyBank | 08000001M | xHosiSb08fs8BQmt9Yhq3Ub99E8= | Banca da selezionare: NEXI - user: bayer - pass: ntt0wned! |
| Masterpass | 08000001P | xHosiSb08fs8BQmt9Yhq3Ub99E8= | registrarsi |
**Attenzione:** Tali credenziali nel tempo potrebbero essere modificate dalla banca. Per richiedere delle proprie credenziali di test contattare la vostra banca.
Per le prove è possibile utilizzare una carta di credito fra quelle presenti nella documentazione tecnica fornita dalla banca oppure le seguenti presenti in questo manuale.
| **TIPO** | **CARTA DI CREDITO** | **SCADENZA** | **CVV** | ESITO AUTH |
| -------- | -------------------- | ------------ | --------- | ---------- |
| VISA | 4557773333333335 | data futura | tre cifre | OK |
| VISA | 4557772222222229 | data futura | tre cifre | OK |
| VISA | 4111111111111111 | 10/2023 | tre cifre | KO |
**Attenzione:** Le carte di credito qui presenti possono non essere idonee per effettuare i test poichè continuamente aggiornate dalla banca. Contattare il supporto bancario per richiedere le carte di credito di test.
# Sicurezza & PCI DSS
## Payment Card Industry Data Security Standard (PCI DSS)
La sicurezza è uno degli elementi fondamentali per le vendite a distanza e, in particolare, su Internet, considerata la criticità dei dati trattati.BNL ha da sempre posto una particolare attenzione alla sicurezza nell’erogazione dei propri servizi, come attestato dalle importanti certificazioni ottenute (**PCI-DSS e ISO27001**), e dalla costante attenzione alle normative di sicurezza proposte dai circuiti di pagamento.
Quando viene utilizzata l'estensione di pagamento BNL per Magento (**pagamenti diretti**), potrebbe essere necessario fornire la certificazione PCI DSS. Le informazioni che vengono trasmesse con tecnologia AJAX, utilizzata dal client API della BNL assicura che il negozio Magento non sia a diretto contatto con i dati relativi alla carta di credito, perchè il cliente trasferirà i dati relativi alla carta di credito direttamente dal suo client a BNL.
## Sicurezza
La piattaforma “Payment Gateway” rende disponibili alle Aziende operanti in Internet, i più aggiornati protocolli di autenticazione proposti dai circuiti internazionali: **Verified by VISA** e **MasterCard SecureCode**, uniti alla verifica del codice di controllo presente sulla carta. L’utilizzo di questi protocolli tutela l’Azienda venditrice dal disconoscimento delle transazioni da parte del titolare della carta di credito o prepagata, garantendo, nella maggior parte dei casi, il buon esito del pagamento.
# Transazioni Magento
Il modulo di pagamento per Magento offre un completo supporto alle transazioni di pagamento connesse al sistema della BNL.
L'amministratore del negozio Magento potrà, attraverso il pannello di controllo ordini, gestire tutte le transazioni di pagamento come:
* Autorizzazione
* Cattura
* Storno (anche parziale di una fattura)
* Annullamento dell'Autorizzazione
E' possibile conoscere l'esito dell'operazione immediatamente dopo l'esecuzione stessa. L'amministratore non dovrà accedere al pannello di backoffice della BNL per conoscere gli esiti, ma far click semplicemente nella singola transazione e visualizzare la risposta della richiesta "Server to Server".\
# Logging, Debug ed Errori Comuni
## Logging, Debug ed Errori Comuni
Qualsiasi comunicazione con la BNL viene registrata in un file di log e può essere utilizzato per il supporto, il test e operazioni di debug dai tecnici del negozio Magento. Le richieste di status delle transazioni di pagamento inviate via API a BNL ed i dati dei processi di pagamento integrati in cui viene richiesta la carta di credito sono esclusi da questo log.
### Magento Log
Per attivare il sistema di registrazione log di Magento bisogna accedere alla sezione amministrativa di Magento e dal menù:
Sistema > Configurazione > Avanzate > Sviluppatore > Impostazioni Log > Abilitato > Si\
Dopo aver attivato il sistema di log e salvato la configurazione, il software magento creerà uno o più file di testo con estensione .log all'interno della cartella del progetto /var/log. La cartella /var/log deve avere i permessi di scrittura per poter creare i file. Per ulteriori informazioni contattare il servizio assistenza del piano hosting.
### Payment Log
Per scaricare il file di Log, crearne una copia di backup basta effettuare un semplice click sul bottone creato appositamente nel pannello di controllo del modulo: **Download Log file**.
Per generare un file di log pulito e con una sola transazione basta eseguire queste operazioni:
1. Fare click su Clear Log file
2. Eseguire un test di acquisto su Magento
3. Fare click su Download Log file
In questo modo il file precedentemente creato verrà conservato in una copia di backup dentro la cartella dei log di Magento e verrà creato un file pulito. Questa operazione è possibile usarla quando si desidera inviare un file di log alla banca per un supporto tecnico (vedi capitolo [Helpdesk Support](/helpdesk-support)).
## Errori Comuni
Durante la connessione ai servizi potrebbe capitare di visualizzare i seguenti codici di errore. I codici di errore sono inviati dal server della BNL al vostro negozio e non provengono dal modulo. Il modulo li interpreta, li trascrive nel file di log ed attraverso il file di log i tecnici della BNL potranno il motivo dell'errore. Prima di contattare i tecnici della BNL con l'opzione "[Helpdesk Support](/helpdesk-support)", di seguito descritto, è bene effettuare un controllo semplice utilizzando le informazioni riportate di seguito.
1. **IGFS\_20022 Campo Signature Non Valido**
1. Questo errore racchiude molte casistiche ma principalmente si riferisce ad una chiamata errata o parametri errati inviati al server della banca, il quale non riconoscendo la richiesta risponde con un errore IGFS\_20022. In questi casi bisogna scaricare il file di log e creare una segnalazione richiedendo un supporto tecnico alla Shine Software.
2. **MISSING refTranID**
1. Il problema riguarda il metodo di transazione impostato in archivio relativo al gateway payment selezionato nel pannello di configurazione. Il software tenta di **effettuare una cattura** di una transazione **senza** avviare **un'autorizzazione**. Un'autorizzazione bancaria genera un codice di riferimento chiamato refTranID ma se tale autorizzazione non viene effettuata, il modulo non può procedere con la cattura. Controllare la tabella core\_*config\_\_data ed in particolare il percorso payment/bnl\_METHODO/payment\_action deve essere impostato su authorize e non su authorize\_capture.*
3. **EMAIL DI CONFERMA PRIMA DEL PAGAMENTO**
1. Sfortunatamente, Magento non fornisce la funzionalità di invio di e-mail dopo aver ricevuto il pagamento con successo da gateway di terze parti e, per impostare un comportamento differente, abbiamo creato una personalizzazione per inviare e-mail manualmente utilizzando un observer. Per utilizzare questa estensione, è necessario disabilitare l'email dell'ordine predefinita dal back-end del negozio Magento 2 per usufruire della funzionalità dell'estensione. Semplicemente, vai su Negozio -> Configurazione -> Vendite -> Email di vendita -> Ordine -> e imposta l'opzione Abilitata predefinita su "No".
4. **IGFS\_20026 SHOP ID DUPLICATO**
1. Il codice dell'ordine è duplicato. Questo significa che state tentando di effettuare una transazione usando un codice d'ordine già presente negli archivi della BNL. Con molta probabilità si sta utilizzando l'ambiente di test in cui molti utenti utilizzano codici d'ordine identici.
# Helpdesk Support
Il modulo di pagamento BNL registra all'interno di un file di log tutte le informazioni necessarie per effettuare una transazione di pagamento utilizzando i server della BNL. Oltre alle richieste di inizializzazione delle richieste vengono registrate anche tutti i parametri di risposta del server, consentendo di effettuare un controllo approfondito del funzionamento del modulo di pagamento.
Al fine di velocizzare qualsiasi operazione di supporto tecnico, nell'area amministrativa del modulo Sistema > BNL > Configurazione > General Options > Helpdesk è possibile inviare una richiesta completa agli operatori della BNL via email automaticamente con un semplice click sul bottone **Request Helpdesk Support**.
## Email di Supporto Tecnico
Per poter usare la funzione di Helpdesk bisogna creare un template personalizzato partendo dal nostro template di base seguendo i seguenti passi:
1. Accedere su Sistema > Email Transazionali
2. Fare click su Aggiungi Nuovo Template
3. Caricare il template realizzato "BNL - Helpdesk Email Template"
4. Impostare un nome al proprio template ad esempio: "BNL Helpdesk Request"
5. Assegnare il nuovo template nella sezione General Options > BNL Helpdesk > Template
6. Salvare la configurazione
Tale opzione permette di inviare un'email contenente tutte le informazioni necessarie per un "debug" veloce da parte dello staff tecnico della BNL.\
Il file di log inviato all'helpdesk si trova nella cartella di Magento /var/log/shinesoftware\_bnl.log
Di seguito un estratto del file di log:
### Cosa fare se si riscontra un problema?
Prima di inviare alla BNL una richiesta di assistenza si consiglia di svuotare il file di log attraverso la funzione "Clear Logs" presente nel pannello di controllo del modulo nella sezione "Payment module options". Il file originale verrà duplicato come file di backup ed il file originale verrà svuotato.
\
Dopo aver pulito il file di log, eseguite l'operazione di acquisto di un prodotto fino a riprodurre il problema riscontrato durante il pagamento. A questo punto, il file di log ha registrato le operazioni eseguite ed è pronto per essere inviato all'helpdesk della BNL. vedi capitolo [Logging, Debug ed Errori Comuni.](https://github.com/shinesoftware/bnl-advanced-2-0/tree/b9fd9a41fa39441150bbfd82cfcf16aa86581521/logging-and-debug.md)
### Assistenza Tecnica
Il modulo ha superato centinaia di controlli ed è installato in moltissimi negozi Magento sparsi nel territorio nazionale. Viene aggiornato costantemente per mantenere uno standard alto di qualità del servizio offerto dalla Shine Software. La richiesta di assistenza tecnica per qualsiasi errore riscontrato durante la fase di installazione, configurazione, uso del modulo avrà un **costo di un'ora di** [**Assistenza Tecnica Magento**](http://www.shinesoftware.com/programmatore-magento.html) per il controllo, la correzione e la riconfigurazione del modulo. Per qualsiasi richiesta di assistenza usare il gestore delle segnalazioni allegando il file di log generato dal modulo.
# Versioni & Changelog
In questa pagina racchiudiamo tutte le modifiche effettuate al modulo e dei suoi sottomoduli ed i loro rilasci. La versione del proprio modulo nella versione di Magento 1.9.x è visibile nella sezione in alto del pannello di configurazione dei metodi di pagamento:
> Are you ready to use the BNL payment **v.2.0.0.0** method? Click here to learn more.
La versione del sotto-modulo si trova al fianco del nome.
Per la versione di Magento 2.x basta leggere il file module.xml presente nella cartella "etc" del modulo.
**Attenzione**: Il modulo è in continua evoluzione e per questo motivo vi invitiamo a seguirci su Twitter ed a pubblicare una recensione al primo utilizzo per ricevere oltretutto uno sconto alla scadenza dell'assistenza tecnica direttamente al link: .
## Versioni
Magento è in continua evoluzione così come le estensioni realizzate dalla Shine Software. Le funzionalità vengono analizzate, programmate, sviluppate e testate. Di seguito le funzionalità esposte dal metodo di pagamento ed integrate nelle versioni di Magento.
| Funzionalità | Magento 1.9.3.x | Magento > 2.x |
| ---------------- | --------------- | ------------- |
| Hosted 3D Secure | Incluso | Incluso |
| MyBank | Incluso | Incluso |
| Masterpass | Incluso | Incluso |
| Alipay | Incluso | |
| Findomestic | Incluso | Incluso |
| Paypal | Incluso | |
| Wallet | Incluso | |
| Mo.To | Incluso | |
### Magento 1.9.3.x
```
* b938c52 - (HEAD -> master, origin/master, origin/HEAD) Save the comment after the callback by the bank servers
* f30e24e - Fixed amount bug
* 514c3cc - Module rule has been fixed Check transaction has been improved
* 303ab0e - Translation for store views of the common title and description fields Fixed minor bugs
* e713b21 - Check and fix of the amount in the hosted and mybank gateway
* 902b44b - BNL Verify Transaction button has been added in the order page Cron has been improved
* b037144 - MyBank Inquiry has been improved Hosted controller has been fixed Payment description error has been fixed
* 99e3864 - fixed minor bugs in the Utils class
* 800370f - MyBank issues fixed!
* 3073ca3 - MyBank issues fixed!
* 24389e9 - Template files have been updated
* 2b3ca9a - New fixes and improvements in all the gateways fixed minor bugs
* ac25f56 - Common currency codes have been integrated in the code (compilation issue) Clear log & Reset tool has been improved MoTo terminal id has been fixed System configuration panel has been updated Log management has been improved minor bug fixes
* bd46eca - Debug option has been improved in the hosted method
* f5daed6 - Findomestic, Moto, Wallet, MyBank, Paypal, Masterpass have been added
* 598e78b - (tag: 2.0.0.0) Initial commit
```
### Magento 2.x
```
2fb4894 - (HEAD -> master, origin/master, origin/HEAD) [fix] - Send Order Confirmation Email After Successful Payment
3a28065 - [fix] - Constructor has been improved
3ff1eca - [fix] - Constructor parameters have been updated
45481ab - [wip] - Igfs Class is now a dependency mattiabasone/pagonline
4ac06e6 - [fix] - composer.json has been updated
1b0b7ba - [fix] - License module has been improved
de09d91 - [fix] - Useless module has been removed
c78244b - [fix] - request template has been fixed temporary
7c07531 - [fix] - Temporary fix for the PSR-4 need to improve the package
c77896f - [fix] - composer.json has been updated
a55cddd - [fix] - Module Version has been updated
e78906e - license core path has been fixed
b1463cb - Composer path has been fixed
7bc5e30 - Magento 2.3.0: Implement below code to skip the CSRF check on your custom route called outside Magento environment. This implementation does not break core frontend/adminhtml routes, Magento 2.3/2.2/2.1 web stores.
8bee3fe - Cron feature has been added. This feature check if there are orfan orders set as payment review. Findomestic module has been added for the first beta Logo feature has been fixed. Now when the payment title is empty a logo appears
700aaf5 - Cron Payment Check has been created Cron Payment Check has been created
2738733 - Cron Payment Check has been created
c7854aa - module version has been updated
350df63 - Merge branch 'master' of https://bitbucket.org/shinesoftware/bnl-advanced-m2
1e74d3e - module version has been updated
905771e - module version has been updated Verify the order and the action cancel the order if the transaction is not confirmed from the bank server
3c119c0 - AUTH method is the default method. If the user need to capture automatically the credit he/she must enable the Auto Invoice feauture. Autoinvoice feature has been added! Logging messages have been added.
8acda28 - Refactoring for new PADL system
93e01eb - Refactoring for new PADL system
a430c4e - Checkout Agreement acceptance has been fix Minor Bug has been fixed
67a08bc - Call back has been upgraded in the hosted solution Request of the additional information has been updated for Magento 2.2
ed31d36 - Call back has been upgraded in the hosted solution Request of the additional information has been updated for Magento 2.2
9d5ac57 - (tag: 2.1.7) Clean up old code
0c79f3b - readme file updated
2fb4894 - (HEAD -> master, origin/master, origin/HEAD) [fix] - Send Order Confirmation Email After Successful Payment
3a28065 - [fix] - Constructor has been improved
3ff1eca - [fix] - Constructor parameters have been updated
45481ab - [wip] - Igfs Class is now a dependency mattiabasone/pagonline
4ac06e6 - [fix] - composer.json has been updated
1b0b7ba - [fix] - License module has been improved
de09d91 - [fix] - Useless module has been removed
c78244b - [fix] - request template has been fixed temporary
7c07531 - [fix] - Temporary fix for the PSR-4 need to improve the package
c77896f - [fix] - composer.json has been updated
a55cddd - [fix] - Module Version has been updated
e78906e - license core path has been fixed
b1463cb - Composer path has been fixed
7bc5e30 - Magento 2.3.0: Implement below code to skip the CSRF check on your custom route called outside Magento environment. This implementation does not break core frontend/adminhtml routes, Magento 2.3/2.2/2.1 web stores.
8bee3fe - Cron feature has been added. This feature check if there are orfan orders set as payment review. Findomestic module has been added for the first beta Logo feature has been fixed. Now when the payment title is empty a logo appears
700aaf5 - Cron Payment Check has been created Cron Payment Check has been created
2738733 - Cron Payment Check has been created
c7854aa - module version has been updated
350df63 - Merge branch 'master' of https://bitbucket.org/shinesoftware/bnl-advanced-m2
1e74d3e - module version has been updated
905771e - module version has been updated Verify the order and the action cancel the order if the transaction is not confirmed from the bank server
3c119c0 - AUTH method is the default method. If the user need to capture automatically the credit he/she must enable the Auto Invoice feauture. Autoinvoice feature has been added! Logging messages have been added.
8acda28 - Refactoring for new PADL system
93e01eb - Refactoring for new PADL system
a430c4e - Checkout Agreement acceptance has been fix Minor Bug has been fixed
67a08bc - Call back has been upgraded in the hosted solution Request of the additional information has been updated for Magento 2.2
ed31d36 - Call back has been upgraded in the hosted solution Request of the additional information has been updated for Magento 2.2
9d5ac57 - (tag: 2.1.7) Clean up old code
0c79f3b - readme file updated
547979d - first commit (hosted, mybank, masterpass)
```
# Lingue & Traduzioni