BNL e–POSitivity Connect

BNL e–POSitivity
Internet Payment Gateway
Connect
1
BNL e–POSitivity
Connect
Guida per l’integrazione
Versione 2.5
Indice
1
Introduzione
4
2
Opzioni disponibili
4
2.1
2.2
2.3
2.4
2.5
3
Pagina di pagamento e–POSitivity o modulo personalizzato?
Modalità PayOnly
Modalità PayPlus
Modalità FullPay
Circuiti di pagamento supportati
Iniziare l’integrazione
3.1
3.2
3.3
3.4
3.5
3.6
3.7
4
5
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 e-mail
Campi obbligatori e opzionali
4.1
4.2
5
5.1
5.2
5.3
4
4
5
5
5
6
6
7
7
9
9
10
10
Campi obbligatori
Campi opzionali
10
11
Utilizzo di moduli personalizzati
12
Informazioni per la fatturazione
Informazioni per la spedizione
Campi personalizzati
12
13
13
6
Personalizzazione dell’aspetto di Connect
14
7
3D Secure
14
7.1
8
Gestione di transazioni 3D Secure per clienti API
Gestione della risposta
15
16
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’email 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 [email protected]
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 ipgutil.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 desiderate passare alla nuova versione di Connect, vi invitiamo ad avvertire preventivamente il
Servizio Esercenti BNL POSitivity all’indirizzo e-mail [email protected] in modo da
procedere alle abilitazioni necessarie e alla riattivazione del vostro ambiente di test.
Consigliamo infatti, prima di procedere con le modifiche, di procedere con tutti i test necessari, come è
stato fatto prima del passaggio in produzione sulla precedente release.
3
1
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.
2
Opzioni disponibili
2.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.
2.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 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.
4
2.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.
2.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 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.
2.5 Circuiti di pagamento supportati
e–POSitivity consente di accettare una vasta gamma di circuiti eseguendo una sola integrazione:
3
•
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 vendite 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
Iniziare l’integrazione
Questa sezione propone un semplice esempio per integrare il vostro sito Web con e–POSitivity in
modalità FullPay, delegando quindi a BNL POSitivity la raccolta di tutti i dati possibili.
Le pagine di esempio sono proposte utilizzando ASP e PHP. In questa sezione si presuppone che lo
sviluppatore abbia una conoscenza di base del linguaggio di scripting scelto.
5
3.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.
3.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, spedizione 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 .
<!-- #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="https://test.ipg-online.com/connect/gateway/processing">
<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="http://.../esitoOK.asp">
<input type="hidden" name="responseFailURL" value="http://.../esitoKO.asp">
<input type="text" name="chargetotal" value="10.00">
<input type="submit" value="Acquista">
</form>
</body>
</html>
Il codice illustrato nel capitolo 9 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.
6
3.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="https://test.ipg-online.com/connect/gateway/processing">
<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="http://.../esitoOK.php">
<input type="hidden" name="responseFailURL" value="http://.../esitoKO.php">
<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.
3.4 Pagina di esempio in ASP.NET (VB)
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
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
7
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="http://.../esitoOK.asp" runat="server"/>
<asp:HiddenField id="responseFailURL" Value="http://.../esitoKO.asp" 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"/>
<asp:Button id="send" runat="server" Text="Continua" PostBackUrl="https://test.ipgonline.com/connect/gateway/processing"/>
</form>
</body>
</html>
8
3.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="https://test.ipg-online.com/connect/gateway/processing">
<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"http://.../esitoOK.asp">
<input type="hidden" name="responseFailURL" value="http://.../esitoKO.asp">
<input type="submit" value="Acquista">
</form>
</cfoutput>
3.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
4111111111111111
12/2012
147 o altro valore
(servizio non attivo)
MasterCard
5232050000010003
12/2012
003 o altro valore
secret123
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, ad esempio 10,00 EUR.
Le transazioni inviate con importi non interi – ad esempio 10,01 EUR oppure 13,99 EUR – verranno
quindi negate, in modo da consentire allo sviluppatore 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.
É 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/2013 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.
9
3.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.
4
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.
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.
4.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:
10
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.
Non va utilizzato se non si vogliono visualizzare le pagine di e–POSitivity.
•
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.
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 ×:
Campo
Possibili valori
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
Sale
PreAuth
PostAuth
Void
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
4.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 ID univoco alla transazione; se
non viene inviato, e–POSitivity ne assegnerà uno in automatico.
•
customerid
Può contenere qualsiasi valore, ad esempio il codice cliente.
•
invoicenumber
Può contenere qualsiasi valore, ad esempio il codice della fattura.
Se viene inviato, il valore comparirà associato alla transazione
direttamente nei risultati delle ricerche effettuate dal menu Reports
Transazioni di Virtual Terminal.
•
refer
Può contenere i dati di chi ha indirizzato il cliente al vostro negozio.
•
paymentMethod
Il campo va inviato al gateway se volete far scegliere all’esercente il
circuito a cui appartiene la carta di credito direttamente dal vostro
sito, per transazioni Sale e PreAuth. I possibili valori sono:
11
MasterCard
M
Visa
V
Maestro
MA
American Express
A
Diners
C
JCB
J
PayPal
•
comments
Può contenere un commento sulla 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).
•
transaction
L’indirizzo URL assoluto al quale inviare in modalità server-toserver 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.
NotificationURL
•
5
paypal
language
Il campo va inviato nel caso in cui 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
Utilizzo di moduli personalizzati
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 particolare in caso di utilizzo della modalità PayOnly o di un modulo personalizzato (ovvero
bypassando le pagine di BNL POSitivity), consigliamo di utilizzare 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.
Vi avvisiamo inoltre che BNL POSitivity non ha alcuna possibilità di recuperare i dati personali
dei titolari di carte di credito in un momento successivo alla transazione.
5.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.
12
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).
5.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:
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
5.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 parametro vengono semplicemente trasmessi alla pagina di conferma, ma non verranno
memorizzati: non saranno quindi presenti nei dettagli degli ordini presenti su Virtual Terminal.
13
6
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:
É 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 [email protected]
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.
7
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)
14
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.
Importo dell’ordine:
€ 150,00
Scadenza
Acquista
[ LOGO BANCA ]
[ SITO ESERCENTE ]
Inserire password:
CVV
Grazie per l’acquisto!
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 e-commerce
“normale” (GICC ECI 7).
In questi casi il trasferimento della responsabilità della transazione dall’esercente alla banca
che ha emesso la carta di credito non è garantita.
Se per questo motivo preferite che il vostro negozio processi esclusivamente transazioni 3D Secure,
potete richiedere al Servizio Esercenti l’attivazione di un blocco che rifiuti le transazioni nel caso in cui
i sistemi per l’autenticazione non siano disponibili.
7.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.
15
8
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
notification_hash
Codice di risposta che garantisce l’identità di BNL POSitivity
(restituito solo se si utilizza transactionNotificationURL)
chargetotal
Importo della transazione
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)
tdate
Identifica in modo univoco la transazione all’interno dell’ordine; va
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)
approval_code
• se transazione approvata Y: seguito dal codice autorizzativo
• se transazione negata
N: seguito dalla motivazione
status
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.
timezone
Fuso orario
terminal_id
Codice del terminale virtuale
processor_response_code
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;
16
− 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
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
17
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
echo
echo
echo
echo
echo
echo
"<b><u>TRANSAZIONE APPROVATA</u></b><br><br>";
"Codice ordine: " . $_POST['oid'] ."<br>";
"Data/ora della transazione: " . $_POST['txndate_processed'] ."<br>";
"Importo della transazione: " . $_POST['chargetotal'] ."<br>";
"Codice autorizzativo: " . $_POST['approval_code'] ."<br>";
"Codice di risposta: " . $_POST['processor_response_code'] ."<br>";
"Riferimento della transazione: " . $_POST['tdate'] ."<br>";
} 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>";
}
?>
18
Per ulteriori informazioni relativamente all’integrazione o se desiderate
ottenere l’accesso ad un ambiente di test pubblico, vi invitiamo a contattare
il Servizio Esercenti BNL POSitivity:
•
chiamando il numero verde 800 900 912 – opzione 4
•
scrivendo all’indirizzo e-mail [email protected]
•
compilando il modulo di contatto disponibile all’indirizzo:
http://www.bnlpositivity.it/it/contatti/contatti-epositivity.html
19