BNL e-POSitivity Connect - Guida per l'integrazione

Pagina creata da Angelo Fusco
 
CONTINUA A LEGGERE
BNL e-POSitivity Connect - Guida per l'integrazione
BNL e–POSitivity
       Connect
   Guida per l’integrazione

              1
BNL e-POSitivity Connect - Guida per l'integrazione
BNL e–POSitivity
Connect

Guida per l’integrazione
Versione 2.6

           Introduzione                                                     4
1          Opzioni disponibili                                              4
    1.1        Pagina di pagamento e–POSitivity o modulo personalizzato?    4
    1.2        Modalità PayOnly                                             4
    1.3        Modalità PayPlus                                             5
    1.4        Modalità FullPay                                             5
    1.5        Circuiti di pagamento supportati                             5
2          Iniziare l’integrazione                                          6
    2.1        Dati necessari                                               6
    2.2        Pagina di esempio in ASP                                     6
    2.3        Pagina di esempio in PHP                                     7
    2.4        Pagina di esempio in ASP.NET (VB)                            7
    2.5        Pagina di esempio in ColdFusion                              9
    2.6        Transazioni ed esiti in ambiente di test                     9
    2.7        Notifica delle transazioni via e-mail                       10
3          Campi obbligatori e opzionali                                   10
    3.1        Campi obbligatori                                           11
    3.2        Campi opzionali                                             12
4          Invio di informazioni opzionali                                 13
    4.1        Informazioni per la fatturazione                            13
    4.2        Informazioni per la spedizione                              13
    4.3        Campi personalizzati                                        14
5          Personalizzazione dell’aspetto di Connect                       14
6          3D Secure                                                       15
    6.1        Gestione di transazioni 3D Secure per clienti API           16
7          Gestione della risposta                                         16
8          File necessari da includere                                     19
    8.1        Versione ASP                                                19
    8.2        Versione PHP                                                20
    8.3        Versione Java                                               20

                                                     2
BNL e-POSitivity Connect - Guida per l'integrazione
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’e-mail 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 e-mail ecommercesupport@bnlpositivity.it oppure
chiamando il numero verde 800 900912.

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 e-mail ecommercesupport@bnlpositivity.it in modo da
procedere alle abilitazioni necessarie e alla riattivazione del vostro ambiente di test.

                                                      3
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
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:
        http://www.maestrocard.com/it/esercizicommerciali/index.html

    •   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 800 976359. Per informazioni visitare:
        http://www.bnlpositivity.it/it/soluzioni-pagamento/Paypal.html

                                                      5
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 : 10012345678

    •   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 10.00 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 http://.../esitoOK.asp .

  Pagina di esempio di e–POSitivity
  
    Prima transazione con e–POSitivity
    
                                                       6
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.

  Pagina di esempio di e–POSitivity
  
    Prima transazione con e–POSitivity
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 & ".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

  BNL e-POSitivity
  
      Transazione su BNL e-POSitivity
      Inserire l'importo e premere 'Acquista'; confermare premendo su 'Continua'.
      
                                              8
2.5 Pagina di esempio in ColdFusion
Riportiamo di seguito una pagina ColdFusion con le caratteristiche della pagina ASP illustrata sopra.
É 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 e-mail
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 e-mail al vostro cliente verrà inviata esclusivamente se:
    •   in modalità PayPlus e FullPay il cliente inserisce il proprio indirizzo e-mail;
    •   in modalità PayOnly, il form che effettua l’invio delle variabili al gateway trasmette anche il
        parametro opzionale email contenente l’indirizzo e-mail del cliente.

Per informazioni sull’attivazione e sulla personalizzazione di questa funzionalità, vi invitiamo a fare
riferimento al capitolo 5 Notifica delle transazioni via e-mail 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 2.3.3 – Rimborsare un ordine del manuale di Virtual Terminal.

                                                      10
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               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).
    •   storename          Codice esercente fornito dal Servizio Esercenti.
    •   mode               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 12.34 per un importo di 12 Euro e 34 centesimi.
                           I separatori delle migliaia (1,000.01 o 1.000,01) non sono consentiti.
    •   currency           Valuta della transazione.
    •   oid                Obbligatorio esclusivamente per transazioni PostAuth e Void identifica
                           l’ordine a cui fa riferimento la transazione.
    •   tdate              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 4.3.1 e 4.3.2 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
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                      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.
    •   customerid               Può contenere qualsiasi valore, ad esempio il codice cliente.
    •   invoicenumber            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.
    •   comments                 Può contenere un commento sulla transazione.
    •   transaction              L’indirizzo URL assoluto al quale inviare in modalità server-to-server
        NotificationURL          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.
    •   language                 Il campo va inviato nel caso si vogliano proporre al cliente le pagine di
                                 e–POSitivity in una lingua diversa da quella predefinita.
                                                     Italiano               it_IT
                                                     Inglese                en_GB
                                                     Tedesco                de_DE
                                                     Francese               fr_FR

                                                    12
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
        email           Massimo 45 caratteri alfanumerici                Indirizzo e-mail

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
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
É 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 e-mail 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:       Scadenza                       Inserire password:
            € 150,00               CVV                                                  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
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                                                 Descrizione
 expmonth                          Mese di scadenza della carta di credito
 paymentMethod                     Circuito utilizzato per il pagamento
 oid                               Codice assegnato all’ordine
 response_hash                     Codice di risposta che garantisce l’identità di BNL POSitivity
                                   Codice di risposta che garantisce l’identità di BNL POSitivity (restituito
 notification_hash
                                   solo se si utilizza transactionNotificationURL)
 chargetotal                       Importo della transazione

                                                     16
currency                          Valuta della transazione
cardnumber                        Circuito e ultime 4 cifre della carta di credito
expyear                           Anno di scadenza della carta di credito
refnumber                         Codice di riferimento della transazione
response_code_3dsecure            Esito dell’autenticazione 3D Secure (Verified by Visa/SecureCode)
                                  Identifica in modo univoco la transazione all’interno dell’ordine; va
tdate
                                  conservato ed inviato al gateway in caso di transazione Void
txntype                           Tipo di transazione (vendita, pre-autorizzazione...)
txndate_processed                 Data e ora di elaborazione del pagamento
ccbin                             Prime 6 cifre della carta (identificano la banca emittente)
                                   • se transazione approvata  Y: seguito dal codice autorizzativo
approval_code
                                   • se transazione negata         N: seguito dalla motivazione
                                  Esito della transazione. Se contiene APPROVATO, APPROVED o
status                            GENEHMIGT (in base alla lingua utilizzata) la transazione è andata a
                                  buon fine; qualsiasi altro valore identifica una transazione negata.
timezone                          Fuso orario
terminal_id                       Codice del terminale virtuale
                                  Codice di risposta della transazione. Riporta il codice associato
processor_response_code
                                  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
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.
else {

         echo"TRANSAZIONE NEGATA";
         echo "ERRORE: " . $_POST['fail_reason'] . "";
         echo "Codice ordine: " . $_POST['oid'] ."";
         echo "Data/ora della transazione: " . $_POST['txndate_processed'] ."";
         echo "Importo della transazione: " . $_POST['chargetotal'] ."";
         echo "Codice di risposta: " . $_POST['processor_response_code'] ."";

}

?>

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.

   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
n = charToByte(char_str.charAt(i));
           if(n != 0) {
              hex_str += byteToHex(n);
           }
        }
     return hex_str.toLowerCase();
     }

     function getDateTime() {
        Response.Write(formattedDate);
     }

8.2 Versione PHP

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
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> 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
22
Puoi anche leggere