BNL e-POSitivity Connect - Guida per l'integrazione
←
→
Trascrizione del contenuto della pagina
Se il tuo browser non visualizza correttamente la pagina, ti preghiamo di leggere il contenuto della pagina quaggiù
BNL e–POSitivity
Connect
Guida per l’integrazione
1
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
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.
3Introduzione
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
4visualizzato 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
52 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
6Il 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–POSitivityPrivate 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'.
82.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.
10Per 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 ×:
11Campo 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
124 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:
13Nome 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).
15In 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
16currency 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
17default, 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++) {
19n = 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;
}
20public 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;j22
Puoi anche leggere
