BNL e POSitivity. Connect. Guida per l integrazione

Transcript

1 BNL e POSitivity Connect Guida per l integrazione 1

2 BNL e POSitivity Connect Guida per l integrazione Versione 2.6 Introduzione 4 1 Opzioni disponibili Pagina di pagamento e POSitivity o modulo personalizzato? Modalità PayOnly Modalità PayPlus Modalità FullPay Circuiti di pagamento supportati 5 2 Iniziare l integrazione Dati necessari Pagina di esempio in ASP Pagina di esempio in PHP Pagina di esempio in ASP.NET (VB) Pagina di esempio in ColdFusion Transazioni ed esiti in ambiente di test Notifica delle transazioni via Campi obbligatori e opzionali Campi obbligatori Campi opzionali 12 4 Invio di informazioni opzionali Informazioni per la fatturazione Informazioni per la spedizione Campi personalizzati 14 5 Personalizzazione dell aspetto di Connect D Secure Gestione di transazioni 3D Secure per clienti API 16 7 Gestione della risposta 16 8 File necessari da includere Versione ASP Versione PHP Versione Java 20 2

3 Informazioni sull assistenza Insieme ai vostri dati d accesso per l ambiente di test, il Servizio Esercenti BNL POSitivity vi ha fornito anche altri manuali, in base alla soluzione da voi scelta. La guida per l integrazione di e POSitivity Connect che state leggendo, si rivelerà essere il riferimento per i problemi relativi all integrazione del vostro sito Web con e POSitivity. Per informazioni relative alla configurazione del comportamento del POS virtuale, per capire come processare pagamenti manuali e altre transazioni (ad esempio chiusure di autorizzazioni, storni ) e per visualizzare i report vi invitiamo a fare riferimento al manuale di Virtual Terminal contenuto nell in cui avete trovato i dati per effettuare l integrazione nell ambiente di test. Se dopo aver letto la documentazione non avete trovato una risposta alle vostre domande, contattate il Servizio Esercenti BNL POSitivity scrivendo all indirizzo ecommercesupport@bnlpositivity.it oppure chiamando il numero verde Informazioni per i clienti con integrazione Connect 1.x già attiva Nel caso in cui rientriate tra i clienti BNL POSitivity che hanno effettuato l integrazione della versione precedente di e POSitivity Connect, proposta fino ad aprile 2009, vi elenchiamo di seguito le principali modifiche apportate alla nuova release: le pagine di pagamento per la raccolta dei dati (PayOnly, PayPlus e FullPay) mostrano ora il logo BNL POSitivity; sulle stesse è inoltre possibile personalizzare il logo, i fonts e i colori; i parametri per la creazione dell hash sono stati modificati; ne consegue che i file ipg-util.asp e ipg-util.php sono stati modificati; il nome del parametro trxccy è stato modificato in currency; i valori del campo mode devono ora essere sempre inviati minuscoli; il campo authenticatetransaction è stato eliminato; la pagina Metodi di pagamento mancanti è stata eliminata: il campo paymentmethod indica ora il circuito della carta di credito e il valore creditcard non è più un valore valido; il suffisso dell URL a cui inviare i dati del modulo è stato modificato da /emea/connectsh a connect/gateway/processing; i clienti vengono ora reindirizzati agli indirizzi responsesuccessurl e responsefailurl in base all esito del pagamento, anziché essere indirizzati sempre all indirizzo responseurl indipendentemente dal risultato della transazione; il campo mode deve contenere valori con caratteri esclusivamente minuscoli (payonly, anziché PayOnly, payplus anziché PayPlus, fullpay anziché FullPay). Se non avete ancora effettuato il passaggio alla nuova versione, vi invitiamo ad avvertire preventivamente il Servizio Esercenti BNL POSitivity all indirizzo ecommercesupport@bnlpositivity.it in modo da procedere alle abilitazioni necessarie e alla riattivazione del vostro ambiente di test. 3

4 Introduzione e POSitivity Connect è la soluzione di pagamento più semplice che BNL POSitivity offre per collegare il vostro negozio online alla piattaforma per pagamenti via Internet di e POSitivity. BNL POSitivity, una volta ricevuti i dati tramite Connect, si preoccuperà di gestire tutte le interazioni necessarie con i circuiti di credito per elaborare la transazione in modo corretto. Questo documento descrive le modalità di integrazione del vostro sito con e POSitivity e fornisce le istruzioni per iniziare ad accettare rapidamente i pagamenti dal vostro sito Web. 1 Opzioni disponibili 1.1 Pagina di pagamento e POSitivity o modulo personalizzato? e POSitivity Connect fornisce due possibilità diverse di integrazione con il vostro sito Web. L opzione più semplice prevede l utilizzo di una pagina di pagamento fornita da BNL POSitivity e residente sui nostri server. In questo caso, il vostro cliente verrà indirizzato sulle nostre pagine al momento del pagamento e potrà inserire i dati della carta di credito direttamente sul nostro sito protetto con certificato SSL. Successivamente, il vostro cliente verrà reindirizzato nuovamente al vostro sito Web, a cui trasmetteremo i dettagli relativi all esito del pagamento. Le tre modalità che proponiamo per la raccolta dei dati sono PayOnly, PayPlus e FullPay. Se preferite invece che il cliente non lasci il vostro sito Web, potete creare un vostro modulo di pagamento personalizzato utilizzando il layout che preferite. Anche se il modulo risiede sui vostri server, i dati della carta di credito verranno inviati direttamente al nostro gateway. Per mostrare un sito Web sicuro (simbolo del lucchetto nel browser) durante la raccolta dei dati della carta, il vostro sito deve fornire una connessione SSL tramite un server HTTPS. Questa soluzione necessita di alcune certificazioni richieste dai circuiti internazionali. Nel caso vogliate adottarla vi invitiamo a contattare BNL POSitivity. Nel caso in cui decidiate di delegare a e POSitivity la raccolta dei dati (soluzione più semplice), avete a disposizione tre differenti metodi per scegliere quali tipi di dati devono essere richiesti dal sistema. In base alle vostre necessità, potete scegliere di raccogliere esclusivamente i dati necessari per il pagamento (carta di credito) oppure richiedere anche i dati per la fatturazione e la spedizione. 1.2 Modalità PayOnly Nella modalità PayOnly, e POSitivity Connect raccoglie esclusivamente le informazioni minime necessarie per effettuare la transazione. Quando il cliente viene indirizzato alla pagina di BNL POSitivity, viene 4

5 visualizzato un modulo per l inserimento del numero di carta di credito, la data di scadenza e il codice di sicurezza CVC riportato sul retro della carta utilizzata. Se si utilizza questa modalità consigliamo di inviare al gateway anche alcuni campi opzionali (almeno il nome) in modo da poter identificare il vostro cliente sui nostri sistemi. 1.3 Modalità PayPlus Nella modalità PayPlus, in aggiunta ai dati della carta di credito richiesti nella modalità PayOnly, il sistema richiede anche tutte le informazioni relative alla fatturazione (ad esempio: nome, indirizzo ). Quando il cliente viene indirizzato al gateway di BNL POSitivity, vengono visualizzate in sequenza due pagine: la prima per raccogliere i dati di fatturazione, la seconda per i dati della carta di credito. 1.4 Modalità FullPay Se desiderate che BNL POSitivity raccolga per voi tutte le informazioni possibili (dati di fatturazione, spedizione e di pagamento) potete utilizzare Connect in modalità FullPay. In questa modalità, dopo aver trasmesso l importo dell ordine, e POSitivity richiederà al vostro cliente anche tutte le altre informazioni richieste, guidandolo su tre pagine. Consigliamo l utilizzo di FullPay esclusivamente nel caso in cui non abbiate un sistema per la gestione degli ordini e decidiate di utilizzare esclusivamente e POSitivity Virtual Terminal per recuperare le informazioni del vostro cliente per l invio della merce in seguito al pagamento. 1.5 Circuiti di pagamento supportati e POSitivity consente di accettare una vasta gamma di circuiti eseguendo una sola integrazione: L accettazione delle carte Visa, Visa Electron, MasterCard e Maestro è compresa nel contratto di convenzionamento stipulato con BNL POSitivity. Per alcune categorie merceologiche è possibile che vi siano delle restrizioni nell accettazione delle carte MasterCard e Maestro: in tali casi BNL POSitivity fornisce un avviso preventivo in fase di definizione del contratto. Le carte Maestro sono accettate esclusivamente in modalità Connect e solo se sulla carta è attivo il servizio di sicurezza 3D Secure SecureCode. Per informazioni visitare: 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. BNL POSitivity provvederà ad inoltrare il contratto e ad attivare il circuito automaticamente al momento della ricezione del codice di convenzione assegnato. Per accettare pagamenti tramite PayPal (esclusivamente transazioni di tipo Sale tramite Connect) è necessario contattare PayPal al numero verde Per informazioni visitare: 5

6 2 Iniziare l integrazione Questa sezione propone un semplice esempio per integrare il vostro sito Web con e POSitivity in modalità PayPlus, delegando quindi a BNL POSitivity la raccolta dei dati di fatturazione. Le pagine di esempio sono proposte utilizzando ASP, PHP, ASP.NET (VBScript) e ColdFusion. In questa sezione si presuppone che lo sviluppatore abbia una conoscenza di base del linguaggio di scripting scelto. 2.1 Dati necessari Per effettuare l integrazione con il gateway, assicuratevi che il Servizio Esercenti vi abbia fornito insieme a questo manuale i seguenti parametri per integrarvi all ambiente di test. Store Name (codice esercente) Il codice esercente che identifica il vostro negozio sui sistemi di BNL POSitivity. Ad esempio : Shared Secret Il codice segreto generato in modo casuale che viene utilizzato ad ogni transazione per costruire il valore di hash così da garantire l identità del vostro sito Web. 2.2 Pagina di esempio in ASP Il codice riportato costruisce una semplice pagina che comunica con e POSitivity in modalità PayPlus. Nel momento in cui un vostro cliente preme il pulsante Acquista, viene indirizzato sulle pagine sicure di BNL POSitivity, dove potrà inserire le sue informazioni di fatturazione e i dati della sua carta di credito per effettuare il pagamento di EUR. A pagamento completato, il cliente verrà riportato su una pagina di conferma presente sul vostro sito Web; in questo esempio l URL per le transazioni approvate è indicato con <!-- #include file="ipg-util.asp"--> <html> <head><title>pagina di esempio di e POSitivity</title></head> <body> <p><h2>prima transazione con e POSitivity</h2></p> <form method="post" action=" <input type="hidden" name="txntype" value="sale"> <input type="hidden" name="timezone" value="cet"/> <input type="hidden" name="txndatetime" value="<% getdatetime() %>"> <input type="hidden" name="hash" value="<% call createhash("10.00","978") %>"> <input type="hidden" name="storename" value="1003xxxxxxx"> <input type="hidden" name="mode" value="payplus"> <input type="hidden" name="currency" value="978"> <input type="hidden" name="language" value="it_it"> <input type="hidden" name="responsesuccessurl" value=" <input type="hidden" name="responsefailurl" value=" <input type="text" name="chargetotal" value="10.00"> <input type="submit" value="acquista"> </form> </body> </html> 6

7 Il codice illustrato nel capitolo 8 File necessari da includere rappresenta il file incluso ipg-util.asp. Questo file contiene il codice necessario per la generazione del valore hash SHA1. Nel file ipg-util.asp è necessario specificare il vostro Store Name e il vostro Shared Secret. 2.3 Pagina di esempio in PHP Riportiamo di seguito una pagina PHP con le stesse caratteristiche della pagina ASP illustrata sopra. <? include("ipg-util.php");?> <html> <head><title>pagina di esempio di e POSitivity</head> <body> <p><h2>prima transazione con e POSitivity</h2></p> <form method="post" action=" <input type="hidden" name="txntype" value="sale"> <input type="hidden" name="timezone" value="cet"> <input type="hidden" name="txndatetime" value="<?php echo getdatetime()?>"> <input type="hidden" name="hash" value="<?php echo createhash("10.00","978")?>"> <input type="hidden" name="storename" value="1003xxxxxxx"> <input type="hidden" name="mode" value="payplus"> <input type="hidden" name="currency" value="978"> <input type="hidden" name="language" value="it_it"> <input type="hidden" name="responsesuccessurl" value=" <input type="hidden" name="responsefailurl" value=" <input type="text" name="chargetotal" value="10.00"> <input type="submit" value="acquista"> </form> </body> </html> Anche in questo modulo di esempio, è necessario includere il file aggiuntivo ipg-util.php, all interno del quale dovrete specificare il vostro Store Name e il vostro Shared Secret. Per motivi di sicurezza vi consigliamo di non inserire il vostro codice Shared Secret direttamente nel codice sorgente del file ipg-util, ma di recuperarlo ad esempio da un database. In entrambi gli esempi illustrati l indirizzo POST URL specificato è valido esclusivamente per inviare transazioni all ambiente di test. Al termine dei test, vi forniremo l indirizzo e i dati definitivi per inviare le transazioni in produzione. 2.4 Pagina di esempio in ASP.NET (VBScript) Riportiamo di seguito una pagina.aspx che consente l inserimento dell importo da addebitare tramite una casella di testo e chiede conferma prima di procedere. <%@ Page Language="VBScript" ValidateRequest="False" %> <script runat="server"> Private Sub Page_Load() conferma_importo.visible = False send.visible = False End Sub 7

8 Private Sub Invia(sender As Object, e As EventArgs) Dim adesso As DateTime = DateTime.Now Dim adesso_stringa As String Dim store_id As String Dim importo_hash As String Dim shared_secret As String Dim hash_hex As String Dim hash_sha1 As String adesso_stringa = adesso.tostring("yyyy:mm:dd-hh:mm:ss") adesso_stringa = adesso_stringa.replace(".",":") txndatetime.value = adesso_stringa importo.text = importo.text.replace(".",",") chargetotal.value = importo.text store_id = "1003xxxxxxx" shared_secret = "sharedsecret" importo_hash = importo.text hash_hex = strtohex(string.concat(store_id, adesso_stringa, importo_hash, "978", shared_secret)) hash_sha1 = FormsAuthentication.HashPasswordForStoringInConfigFile(hash_hex, "sha1").tolower() hash.value = hash_sha1 importo.visible = False conferma_importo.text = conferma_importo.text & importo.text & ".<br><br>vuoi proseguire? " conferma_importo.visible = True check.visible = False send.visible = True End Sub Private Function strtohex(mystr As String) As String Dim hexstr As String Dim hextmp As String Dim i% For i = 1 To Len(myStr) hextmp = Hex(Asc(Mid(myStr, i, 1))) hexstr = hexstr & hextmp Next strtohex = hexstr.tolower() End Function </script> <html> <head><title>bnl e-positivity</title></head> <body> <form id="positivity" runat="server"> <p><b>transazione su BNL e-positivity</b></p> <p>inserire l'importo e premere 'Acquista'; confermare premendo su 'Continua'.</p> <asp:hiddenfield id="txntype" Value="sale" runat="server"/> <asp:hiddenfield id="timezone" Value="CET" runat="server"/> <asp:hiddenfield id="txndatetime" Value="" runat="server"/> <asp:hiddenfield id="hash" Value="" runat="server"/> <asp:hiddenfield id="storename" Value="1003xxxxxxx" runat="server"/> <asp:hiddenfield id="mode" Value="payplus" runat="server"/> <asp:hiddenfield id="currency" Value="978" runat="server"/> <asp:hiddenfield id="language" Value="it_IT" runat="server"/> <asp:hiddenfield id="chargetotal" Value="" runat="server"/> <asp:hiddenfield id="responsesuccessurl" Value=" runat="server"/> <asp:hiddenfield id="responsefailurl" Value=" runat="server"/> <asp:textbox id="importo" Text="10.00" runat="server"/> <asp:label id="conferma_importo" Text="Procedi con il pagamento di EUR " runat="server"/> <asp:button id="check" runat="server" Text="Acquista" OnClick="Invia"/> 8

9 <asp:button id="send" runat="server" Text="Continua" PostBackUrl=" </form> </body> </html> 2.5 Pagina di esempio in ColdFusion Riportiamo di seguito una pagina ColdFusion con le caratteristiche della pagina ASP illustrata sopra. <cfset DataTransazione = DateFormat(Now(),'yyyy:mm:dd') & "-" & TimeFormat(Now(),'HH:mm:ss')> <cfset Importo = "10.00"> <cfset StoreNumber = "1003xxxxxxx "> <cfset SharedSecret = "sharedsecret"> <cfset Stringa = StoreNumber & DataTransazione & Importo & 978 & SharedSecret> <cfset StringaAscii = ""> <cfloop from="1" to="#len(stringa)#" index="idxcarattere"> <cfset StringaAscii = StringaAscii & FormatBaseN(Asc(Mid(Stringa, idxcarattere, 1)), 16)> </cfloop> <cfset Codice = LCase(Hash(StringaAscii,"SHA"))> <cfoutput> <form method="post" action=" <input type="hidden" name="txntype" value="sale"> <input type="hidden" name="timezone" value="cet"> <input type="hidden" name="txndatetime" value="#datatransazione#"> <input type="hidden" name="hash" value="#codice#"> <input type="hidden" name="storename" value="#storenumber#"> <input type="hidden" name="mode" value="payplus"> <input type="hidden" name="currency" value="978"> <input type="hidden" name="language" value="it_it"> <input type="hidden" name="chargetotal" value="#importo#"> <input type="hidden" name="responsesuccessurl" <input type="hidden" name="responsefailurl" value=" <input type="submit" value="acquista"> </form> </cfoutput> 2.6 Transazioni ed esiti in ambiente di test Nell ambiente di test è possibile effettuare delle transazioni utilizzando queste carte di credito: Circuito Numero Scadenza CVC Password 3D Secure Visa / o altro valore (servizio non attivo) MasterCard / o altro valore secret3 Durante l utilizzo del sistema di test in fase di integrazione, noterete che l autorizzativo in questa fase approva esclusivamente le transazioni con importi senza centesimi <= EUR ad esempio 10,00 EUR. Le transazioni inviate con importi non interi ad esempio 10,01 EUR o 13,99 EUR o uguali/superiori a EUR verranno negate, in modo da consentire di simulare dei casi di autorizzazioni negate. In questo modo sarà possibile controllare l esito della transazione e testare il comportamento della pagina di conferma e dell intero sistema (soprattutto dal vostro lato) sia in caso di transazioni andate a buon fine, sia in caso di transazioni negate. 9

10 É importante evidenziare che in questa fase di integrazione il sistema non effettua alcuna verifica sull effettiva validità o esistenza della carta utilizzata per il pagamento; è sufficiente inserire dei dati formalmente validi per proseguire senza problemi; ad esempio è possibile inserire come scadenza delle carte sopra riportate 12/2015 senza ottenere errori. Una transazione in test quindi non può essere condotta verso un esito negativo inserendo una scadenza diversa, ma utilizzando importi con centesimi, come descritto poco sopra. 2.7 Notifica delle transazioni via BNL e POSitivity è in grado di inviare una conferma tramite posta elettronica per ciascun pagamento effettuato. Queste notifiche possono essere inviate sia a voi che ai vostri clienti. Se la funzionalità è abilitata, la conferma via al vostro cliente verrà inviata esclusivamente se: in modalità PayPlus e FullPay il cliente inserisce il proprio indirizzo ; in modalità PayOnly, il form che effettua l invio delle variabili al gateway trasmette anche il parametro opzionale contenente l indirizzo del cliente. Per informazioni sull attivazione e sulla personalizzazione di questa funzionalità, vi invitiamo a fare riferimento al capitolo 5 Notifica delle transazioni via del manuale di Virtual Terminal. 3 Campi obbligatori e opzionali e POSitivity consente l invio al gateway di diverse tipologie di transazioni, alcune delle quali sono valide esclusivamente se applicate a transazioni effettuate in precedenza. Il tipo di transazione viene comunicato tramite il campo txntype. sale Vendita: l addebito sulla carta di credito avviene immediatamente. preauth Solo autorizzazione: l importo sulla carta di credito viene solo prenotato senza procedere all addebito fino a che non viene inviata una chiusura. postauth Incasso di un importo pre-autorizzato: effettuabile esclusivamente in seguito ad un autorizzazione preauth, per la quale postauth ne richiede la contabilizzazione. void Annullamento: annulla un ordine già contabilizzato (chiuso), a patto che la transazione da annullare sia stata effettuata nella stessa giornata. A differenza di un normale storno, void non lascia traccia né dell acquisto, né dell annullamento sull estratto conto della carta. Per motivi di sicurezza la funzione di annullamento è soggetta ad abilitazione specifica: in caso si debba utilizzare la funzione void tramite Connect, contattare il Servizio Esercenti. Il rimborso di una transazione processata in una giornata precedente non può essere effettuato tramite Connect. Per effettuare questo tipo di operazione, è necessario accedere a Virtual Terminal e fare riferimento al paragrafo Rimborsare un ordine del manuale di Virtual Terminal. 10

11 Per maggiori informazioni su come effettuare un rimborso e sulle ulteriori operazioni effettuabili nelle modalità e POSitivity Virtual Terminal e API (se richiesto), consultare i relativi manuali. 3.1 Campi obbligatori Sulla base della tipologia di transazione inviata, alcuni campi diventano o meno obbligatori. I campi che possono essere richiesti in base alla transazione sono i seguenti. timezone Fuso orario della transazione; quello italiano è CET. txndatetime Data e ora della transazione. hash storename mode Valore hash SHA1 calcolato sulla base dei seguenti campi: storename + txndatetime + chargetotal + currency + sharedsecret. É importante che l hash sia generato passando alla funzione i campi in questo esatto ordine (vedere il file ipg-util per maggiori dettagli). Codice esercente fornito dal Servizio Esercenti. Specifica la modalità di raccolta dei dati (set di informazioni) del cliente e determina la visualizzazioni di 1, 2 o 3 pagine del sistema per la richiesta dei dati di fatturazione, spedizione e pagamento. chargetotal Importo della transazione; utilizzare sempre il punto come separatore decimale, ad esempio per un importo di 12 Euro e 34 centesimi. I separatori delle migliaia (1, o 1.000,01) non sono consentiti. currency oid tdate Valuta della transazione. Obbligatorio esclusivamente per transazioni PostAuth e Void identifica l ordine a cui fa riferimento la transazione. Identificazione esatta della transazione; questo parametro viene restituito al momento dell esecuzione della transazione originaria. I parametri seguenti diventano obbligatori esclusivamente se nella sezione Personalizzazione Impostazioni di Connect in Virtual Terminal non sono stati definiti gli indirizzi (URL) a cui trasferire l utente in caso di pagamento andato a buon fine o in caso di fallimento della transazione: responsesuccessurl L indirizzo URL assoluto al quale i vostri clienti verranno reindirizzati in caso di transazione approvata (messaggio di conferma). responsefailurl L indirizzo URL assoluto al quale i vostri clienti verranno reindirizzati in caso di transazione negata (messaggio di errore). Nella stessa sezione è possibile definire se in caso di invio dei parametri responsesuccessurl/ responsefailurl con presenza degli URL in Virtual Terminal è necessario ignorare i parametri trasmessi. Al riguardo, vi invitiamo a fare riferimento ai paragrafi e del manuale di Virtual Terminal. In base al valore di txntype, cambiano anche i campi obbligatori da trasmettere al gateway per effettuare la transazione, che elenchiamo di seguito contrassegnati da : 11

12 Campo Possibili valori Sale PreAuth PostAuth Void timezone GMT CET EET txndatetime AAAA:MM:GG-hh:mm:ss hash storename mode payonly payplus fullpay chargetotal x.xx xxxx.xx currency 978 oid tdate 3.2 Campi opzionali e POSitivity Connect consente l invio da parte del form sul vostro sito Web di alcuni campi aggiuntivi opzionali che forniscono ulteriori informazioni sulla transazione. oid customerid invoicenumber comments transaction NotificationURL language Il campo consente di assegnare un codice ordine alla transazione; se non viene inviato, e POSitivity ne assegnerà uno in automatico. Se si decide di utilizzare un codice ordine personalizzato, è necessario tenere presente che non è possibile utilizzare lo stesso codice ordine in caso esista già almeno una transazione approvata per lo stesso; se esistono solo transazioni negate, è possibile utilizzare lo stesso oid finché non si ottiene un esito positivo. Può contenere qualsiasi valore, ad esempio il codice cliente. Può contenere qualsiasi valore, ad esempio il numero fattura. Se viene inviato, il valore comparirà direttamente nei risultati delle ricerche effettuate dal menu Reports Transazioni di Virtual Terminal. Può contenere un commento sulla transazione. L indirizzo URL assoluto al quale inviare in modalità server-to-server gli stessi parametri restituiti sulle pagine di risposta. L indirizzo utilizzato per la notifica deve essere in grado di ricevere o sulla porta 80 (http) o sulla porta 443 (https). L utilizzo di questa funzione è consigliato per evitare la perdita di dati in caso di mancato reindirizzamento alle pagine responsesuccessurl / responsefailurl generalmente imputabile all utente. É anche possibile impostare questo parametro accedendo a Virtual Terminal nella sezione Personalizzazione Impostazioni di Connect. Il campo va inviato nel caso si vogliano proporre al cliente le pagine di e POSitivity in una lingua diversa da quella predefinita. Italiano Inglese Tedesco Francese it_it en_gb de_de fr_fr 12

13 4 Invio di informazioni opzionali Le informazioni aggiuntive e opzionali per l esecuzione del pagamento raccolte nelle modalità PayPlus e FullPay possono essere trasmesse al sistema anche dal vostro form di pagamento in caso vogliate far inserire sul sito di BNL POSitivity esclusivamente i dati relativi alla carta di credito. In particolare in caso di utilizzo della modalità PayOnly o di un modulo personalizzato (ovvero bypassando le pagine di BNL POSitivity funzionalità non disponibile per un contratto di convenzionamento standard), consigliamo di trasmettere sempre qualche campo opzionale per identificare il cliente sul sistema. Se si utilizza una di queste modalità e non si inviano campi opzionali (ad esempio bname), sarà impossibile identificare il cliente consultando i nostri sistemi. 4.1 Informazioni per la fatturazione I campi che seguono vengono raccolti da e POSitivity nella modalità PayPlus. Se però volete evitare di chiedere al vostro cliente di inserire questi dati anche sulle pagine di BNL POSitivity (ad esempio perché li raccogliete già sul vostro sito Web), è possibile trasmetterci le informazioni già disponibili. Queste informazioni, se inviate al gateway tramite il vostro form o se raccolte tramite le pagine di e POSitivity in modalità PayPlus o FullPay, compariranno nel dettaglio dell ordine in Virtual Terminal. I dati andranno inviati al sistema seguendo le indicazioni riportate nella tabella che segue. Nome Formato Descrizione bcompany Caratteri alfanumerici, spazi e barre Azienda bname Caratteri alfanumerici, spazi e barre Nome baddr1 Caratteri alfanumerici e spazi Indirizzo baddr2 Caratteri alfanumerici e spazi Indirizzo bcity Caratteri alfanumerici e spazi Città bstate Massimo 30 caratteri Provincia bcountry 2 lettere (IT per Italia) Nazione bzip 5 cifre CAP phone Massimo 20 cifre Numero di telefono fax Massimo 20 cifre Numero di fax Massimo 45 caratteri alfanumerici Indirizzo Tra questi dati, consigliamo di inviare almeno i campi bname (nome) e phone (numero di telefono). 4.2 Informazioni per la spedizione Le seguenti informazioni, in aggiunta a quelle già specificate sopra per il pagamento e la fatturazione, vengono raccolte da e POSitivity in modalità FullPay. Per inviare al gateway queste informazioni direttamente dal vostro sito Web, è possibile raccogliere i dati sul vostro modulo utilizzando i nomi specificati per relativi i campi: 13

14 Nome Formato Descrizione sname Caratteri alfanumerici, spazi e barre Nome del destinatario saddr1 Caratteri alfanumerici e spazi Indirizzo di spedizione saddr2 Caratteri alfanumerici e spazi Indirizzo di spedizione scity Caratteri alfanumerici e spazi Città sstate Massimo 30 caratteri Provincia scountry 2 lettere (IT per Italia) Nazione szip 5 cifre CAP 4.3 Campi personalizzati e POSitivity consente di gestire anche dei campi personalizzati, che vengono restituiti insieme a tutte le altre variabili di sistema agli indirizzi responsesuccessurl e responsefailurl. É possibile inviare al sistema fino a 15 variabili personalizzate. Potrete successivamente utilizzare questi campi ad esempio, per associare il pagamento in seguito al completamento della transazione. Questi parametri vengono semplicemente restituiti alla pagina di conferma con lo stesso valore inviato, ma non verranno memorizzati: non saranno presenti nei dettagli presenti su Virtual Terminal. 5 Personalizzazione dell aspetto di Connect Le pagine predefinite residenti sui server di BNL POSitivity che verranno mostrate ai vostri clienti in seguito al trasferimento dal vostro sito Web avranno il seguente aspetto: 14

15 É possibile personalizzare l aspetto di queste pagine modificando: l immagine visualizzata in alto; i caratteri (fonts) utilizzati nella pagina; i colori utilizzati per lo sfondo, le descrizioni, i campi e i pulsanti. Nel caso in cui vogliate procedere al caricamento sulla pagina di un logo personalizzato, è sufficiente inviare una richiesta al nostro Servizio Esercenti all indirizzo ecommercesupport@bnlpositivity.it allegando l immagine e una descrizione della posizione richiesta per lo stesso. Per la modifica dei caratteri e dei colori della pagina, è possibile invece procedere autonomamente accedendo al menu Personalizzazione di Virtual Terminal. Vi invitiamo quindi a fare riferimento al paragrafo 4.4 del manuale di Virtual Terminal per la modifica di questi aspetti delle pagine di Connect. 6 3D Secure Il gateway e POSitivity include la possibilità di autenticare le transazioni effettuate dal vostro sito Web utilizzando Verified by Visa e MasterCard SecureCode. In breve, l acquisto online in modalità 3D Secure si compone di un passaggio aggiuntivo: 1. inserimento dei dati della carta di credito (sul sito dell esercente o su e POSitivity) 2. verifica dell attivazione 3D Secure sulla carta: a. se la carta risulta abilitata al servizio 3D Secure, il cliente viene rimandato al sito della sua banca per inserire la sua password personale; b. se la carta non supporta 3D Secure, la transazione procede senza ulteriori interventi. [ SITO ESERCENTE ] Carta n. [ LOGO BANCA ] [ SITO ESERCENTE ] Importo dell ordine: 150,00 Scadenza CVV Inserire password: Grazie per l acquisto! Acquista Prosegui Prosegui Al fine di ridurre al minimo la possibilità di riaddebito all esercente in caso di contestazione degli acquisti da parte dei titolari di carte di credito, BNL POSitivity offre a tutti i suoi clienti e-commerce l attivazione automatica del servizio 3D Secure; non è quindi necessario implementare l attivazione di questo servizio in particolare sul vostro modulo che reindirizza verso il gateway. Può accadere che l autenticazione 3D Secure non venga processata in modo corretto per problemi tecnici. Se uno dei sistemi coinvolti nel processo di autenticazione è temporaneamente non disponibile, il pagamento verrà gestito come una transazione non sicura (ECI 7). 15

16 In questi casi il trasferimento della responsabilità della transazione dall esercente alla banca che ha emesso la carta di credito non è garantita. Per questo motivo, il sistema vi protegge da possibili contestazioni, provvedendo a rifiutare le transazioni eseguite in modalità non sicura a causa di malfunzionamenti momentanei. 6.1 Gestione di transazioni 3D Secure per clienti API Se utilizzate la soluzione e POSitivity API per comunicare con il nostro gateway, vi ricordiamo che le transazioni iniziali degli ordini devono essere effettuate in modalità 3D Secure. API non include però un plug-in integrato per l autenticazione delle transazioni e per questo motivo, esclusivamente per transazioni Sale e Auth, è necessario appoggiarsi a Connect. Se avete comunque la necessità di ottenere una conferma in modalità server-to-server è possibile utilizzare il parametro aggiuntivo transactionnotificationurl descritto a pagina 11 per inviare l esito del pagamento a un altro URL oppure è possibile gestire gli acquisti in due fasi distinte: apertura di un autorizzazione Auth tramite Connect in modalità 3D Secure (se necessario con modulo personalizzato, in modo da non visualizzare le nostre pagine); chiusura dell autorizzazione con PostAuth + codice ordine in modalità server-to-server. In questo modo, la risposta finale della transazione può essere gestita senza appoggiarsi al browser, pur avendo aperto l autorizzazione in modalità sicura, con le garanzie offerte da tali programmi. 7 Gestione della risposta Al termine della procedura di pagamento, e POSitivity invierà i dettagli della transazione agli indirizzi responsesuccessurl o responsefailurl tramite dei campi nascosti. Di seguito trovate l elenco completo delle variabili restituite in seguito a un pagamento; durante la costruzione della pagina di conferma potete decidere quali di questi parametri visualizzare, in modo da fornire ai vostri clienti dei codici di riferimento nel caso abbiano necessità di assistenza in merito alla transazione effettuata sul vostro sito Web. Nome expmonth paymentmethod oid response_hash notification_hash chargetotal Descrizione Mese di scadenza della carta di credito Circuito utilizzato per il pagamento Codice assegnato all ordine Codice di risposta che garantisce l identità di BNL POSitivity Codice di risposta che garantisce l identità di BNL POSitivity (restituito solo se si utilizza transactionnotificationurl) Importo della transazione 16

17 currency cardnumber expyear refnumber response_code_3dsecure tdate txntype txndate_processed ccbin approval_code status timezone terminal_id processor_response_code Valuta della transazione Circuito e ultime 4 cifre della carta di credito Anno di scadenza della carta di credito Codice di riferimento della transazione Esito dell autenticazione 3D Secure (Verified by Visa/SecureCode) Identifica in modo univoco la transazione all interno dell ordine; va conservato ed inviato al gateway in caso di transazione Void Tipo di transazione (vendita, pre-autorizzazione...) Data e ora di elaborazione del pagamento Prime 6 cifre della carta (identificano la banca emittente) se transazione approvata Y: seguito dal codice autorizzativo se transazione negata N: seguito dalla motivazione Esito della transazione. Se contiene APPROVATO, APPROVED o GENEHMIGT (in base alla lingua utilizzata) la transazione è andata a buon fine; qualsiasi altro valore identifica una transazione negata. Fuso orario Codice del terminale virtuale Codice di risposta della transazione. Riporta il codice associato all errore; se la transazione è andata a buon fine contiene 00 o 000 Per costruire una buona pagina di conferma delle transazioni, è opportuno approfondire meglio alcuni dei parametri sopra elencati. status Consente di capire se la transazione è stata approvata o negata. In particolare: contiene APPROVED/APPROVATO/GENEHMIGT se la transazione è andata a buon fine; contiene DECLINED/RIFIUTATO se la transazione è stata negata; contiene DUPLICATE/DUPLICATO se la transazione viene respinta dal sistema per codice ordine già utilizzato o se la transazione è stata considerata come ripetuta; contiene FRAUD se la transazione viene respinta dal filtro anti-frode del sistema. Dal momento che il campo status può assumere molti valori diversi (DUPLICATE, FRAUD ), la transazione va considerata approvata esclusivamente se il parametro status contiene il valore APPROVED / APPROVATO / GENEHMIGT (in base al valore del campo language). Qualsiasi altro valore rappresenta una transazione non andata a buon fine. Fare riferimento alla pagina successiva per ottenere un esempio pratico di controllo della variabile per determinare cosa visualizzare sulla pagina di conferma. response_hash Consente di verificare se la risposta è stata effettivamente generata da BNL POSitivity, in modo da poter identificare in modo chiaro i tentativi di frode. La stringa viene creata con un hash SHA1 utilizzando i seguenti parametri nell ordine esatto: sharedsecret + approval_code + chargetotal + currency + txndatetime + storename Va evidenziato che il campo txndatetime non corrisponde al parametro txndate_processed restituito nella pagina di conferma, ma equivale alla data/ora inviata dalla vostra pagina al gateway con nome txndatetime. Dal momento che questo parametro non viene restituito di 17

18 default, vi consigliamo di inviare un parametro aggiuntivo (ad esempio chiamandolo dataora) assegnandogli lo stesso valore di txndatetime. Questo parametro personalizzato verrà restituito nella pagina di conferma con il nome da voi impostato e potrà essere impiegato al posto ti txndatetime nella costruzione del vostro response_hash, che andrà poi confrontato con quello restituito dal sistema. notification_hash In caso venga utilizzata la funzione di notifica delle transazioni ad un URL specificato tramite la variabile transactionnotificationurl (descritta a pagina 12), il campo response_hash illustrato sopra viene sostituito dal parametro notification_hash esclusivamente per la risposta restituita all URL di notifica; alle pagine responsesuccessurl e responsefailurl il sistema continuerà a restituire la variabile response_hash. La stringa viene creata con un hash SHA1 utilizzando i seguenti parametri nell ordine esatto: chargetotal + sharedsecret + currency + txndatetime + storename + approval_code Va segnalato che anche per questo parametro valgono le stesse osservazioni effettuate per il campo response_hash relative al valore del parametro txndatetime. response_code_3dsecure Fornisce l esito dell autenticazione 3D Secure. I possibili valori della variabile sono: 1 autenticazione avvenuta (Visa ECI 5) 2 autenticazione avvenuta senza AVV (Visa ECI 5) 3 autenticazione fallita per password errata (transazione negata) 4 tentata autenticazione (Visa ECI 6) 5 impossibile effettuare l autenticazione per mancata risposta da DS (Visa ECI 7) 6 impossibile effettuare l autenticazione per mancata risposta da ACS (Visa ECI 7) 7 carta non attivata per 3D Secure (Visa ECI 6) 8 valori 3D Secure ricevuti dalla banca non validi I dettagli della transazione vengono restituiti come parametri POST sulle pagine di conferma; sarà poi necessario decidere quali parametri mostrare a video utilizzando la sintassi del linguaggio scelto. Di seguito trovate un esempio di semplice pagina PHP che verifica l esito della transazione tramite la variabile status e, in base al valore della stessa, mostra determinati campi. Implementando questo tipo di controllo è possibile utilizzare la stessa pagina di conferma sia come responsesuccessurl che come responsefailurl; in alternativa è possibile costruirne due separate. <?php if (($_POST['status'] == 'APPROVED') ($_POST['status'] == 'APPROVATO') ($_POST['status'] == 'GENEHMIGT')) { echo "<b><u>transazione APPROVATA</u></b><br><br>"; echo "Codice ordine: ". $_POST['oid']."<br>"; echo "Data/ora della transazione: ". $_POST['txndate_processed']."<br>"; echo "Importo della transazione: ". $_POST['chargetotal']."<br>"; echo "Codice autorizzativo: ". $_POST['approval_code']."<br>"; echo "Codice di risposta: ". $_POST['processor_response_code']."<br>"; echo "Riferimento della transazione: ". $_POST['tdate']."<br>"; 18

19 else { echo"<b><u>transazione NEGATA</u></b><br><br>"; echo "<b>errore: ". $_POST['fail_reason']. "</b><br><br>"; echo "Codice ordine: ". $_POST['oid']."<br>"; echo "Data/ora della transazione: ". $_POST['txndate_processed']."<br>"; echo "Importo della transazione: ". $_POST['chargetotal']."<br>"; echo "Codice di risposta: ". $_POST['processor_response_code']."<br>";?> 8 File necessari da includere Di seguito riportiamo il codice del file ipg-util, nelle diverse versioni in ASP, PHP e Java. In questo file, che va incluso nella pagina che contiene il modulo che genera il valore hash, vanno modificate esclusivamente le variabili storeid e sharedsecret con i dati forniti dal Servizio Esercenti. Consigliamo, per motivi di sicurezza, di non inserire direttamente nel codice il valore Shared Secret utilizzato per la generazione del valore hash, ma ad esempio di leggerlo da un database. Al momento del passaggio in produzione e dell attivazione definitiva del POS virtuale, vi forniremo un nuovo Shared Secret, che andrà sostituito nel vostro script ipg-util. Per il passaggio in produzione, questo sarà l unico dato da sostituire, insieme all indirizzo POST URL. 8.1 Versione ASP Il file ipg-util.asp si appoggia anche al file sha1.js per la costruzione del valore hash; questo JavaScript viene fornito nell archivio.zip dal Servizio Esercenti al momento dell invio dei dati di attivazione per l ambiente di test. <script LANGUAGE=JScript RUNAT=Server src="sha1.js"></script> <script LANGUAGE=JScript RUNAT=Server> var today = new Date(); var formatteddate = today.formatdate("y:m:d-h:i:s"); function createhash(chargetotal, currency) { var storeid = "1003xxxxxxx"; var sharedsecret = "sharedsecret"; var stringtohash = storeid + formatteddate + chargetotal + currency + sharedsecret; var ascii = gethexfromchars(stringtohash); var hash = calcsha1(ascii); Response.Write(hash); function gethexfromchars(value) { var char_str = value; var hex_str = ""; var i, n; for(i=0; i < char_str.length; i++) { 19

20 n = chartobyte(char_str.charat(i)); if(n!= 0) { hex_str += bytetohex(n); return hex_str.tolowercase(); function getdatetime() { Response.Write(formattedDate); </script> 8.2 Versione PHP <?php $datetime = date("y:m:d-h:i:s"); function getdatetime() { global $datetime; return $datetime;?> function createhash($chargetotal, $currency) { $storeid = "1003xxxxxxx"; $sharedsecret = "sharedsecret"; $stringtohash = $storeid. getdatetime(). $chargetotal. $currency. $sharedsecret; $ascii = bin2hex($stringtohash); return sha1($ascii); 8.3 Versione Java Di seguito riportiamo anche la classe IPGIntegrationUtil da utilizzare nel caso in cui si decida di utilizzare Java come tecnologia per connettersi al gateway tramite Connect. import java.security.messagedigest; import java.text.simpledateformat; import java.util.date; public final class IPGIntegrationUtil { private static SimpleDateFormat dateformat = new SimpleDateFormat("yyyy:MM:dd-HH:mm:ss"); private String fmtdate = dateformat.format(new Date(System.currentTimeMillis())); private String storeid; private String sharedsecret; private String charge; private String currency; public IPGIntegrationUtil(String storeid, String sharedsecret, String charge, String currency) { super(); this.storeid = storeid; this.sharedsecret = sharedsecret; this.charge = charge; this.currency = currency; 20

21 public String createhash() { String stringtohash = storeid + fmtdate + charge + currency + sharedsecret; return calculatehashfromhex( new StringBuffer( stringtohash ) ); private String calculatehashfromhex(stringbuffer buffer) { String algorithm = "SHA1"; MessageDigest messagedigest = null; try { messagedigest = MessageDigest.getInstance(algorithm); catch (Exception e) { throw new IllegalArgumentException("Algorithm '" + algorithm + "' not supported"); StringBuffer result = new StringBuffer(); StringBuffer sb = new StringBuffer(); byte[] bytes = buffer.tostring().getbytes(); int bytelen = bytes.length; for (int i=0;i<bytelen;i++) { byte b = bytes[i]; sb.append(character.fordigit((b & 240) >> 4, 16)); sb.append(character.fordigit((b & 15), 16)); buffer = new StringBuffer(sb.toString()); messagedigest.update(buffer.tostring().getbytes()); byte[] message = messagedigest.digest(); int messagelen = message.length; for(int j=0;j<messagelen;j++) { byte b = message[j]; String apps=integer.tohexstring(b & 0xff); if(apps.length()==1){ apps = "0"+apps; result.append(apps); return result.tostring(); public String getcharge() { return charge; public String getsharedsecret() { return sharedsecret; public String getstoreid() { return storeid; public String getformattedsysdate() { return fmtdate; 21

22 22