Manuale Tecnico per integrazione Connect

Transcript

Manuale Tecnico per integrazione Connect
BNL e–POSitivity
Connect
Guida per l’integrazione
1
BNL e–POSitivity
Connect
Guida per l’integrazione
Versione 2.6 per la distribuzione su www.bnlpositivity.it
Introduzione
4
1
4
Opzioni disponibili
1.1
1.2
1.3
1.4
1.5
2
Pagina di pagamento e–POSitivity o modulo personalizzato?
Modalità PayOnly
Modalità PayPlus
Modalità FullPay
Circuiti di pagamento supportati
Iniziare l’integrazione
2.1
2.2
2.3
2.4
2.5
2.6
2.7
3
6
Dati necessari
Pagina di esempio in ASP
Pagina di esempio in PHP
Pagina di esempio in ASP.NET (VBScript)
Pagina di esempio in ColdFusion
Transazioni ed esiti in ambiente di test
Notifica delle transazioni via e-mail
Campi obbligatori e opzionali
3.1
3.2
4
4.1
4.2
4.3
4
4
5
5
5
6
6
7
7
9
9
10
10
Campi obbligatori
Campi opzionali
11
12
Invio di informazioni opzionali
13
Informazioni per la fatturazione
Informazioni per la spedizione
Campi personalizzati
13
13
14
5
Personalizzazione dell’aspetto di Connect
14
6
3D Secure
15
6.1
7
Gestione di transazioni 3D Secure per clienti API
Gestione della risposta
16
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’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 [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 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 [email protected] 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 .
<!-- #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>
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.
<? 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.
2.4 Pagina di esempio in ASP.NET (VBScript)
Riportiamo di seguito una pagina .aspx che consente l’inserimento dell’importo da addebitare tramite una
casella di testo e chiede conferma prima di procedere.
<%@ Page Language="VBScript" ValidateRequest="False" %>
<script runat="server">
Private Sub Page_Load()
conferma_importo.Visible = False
send.Visible = False
End Sub
7
Private Sub Invia(sender As Object, e As EventArgs)
Dim adesso As DateTime = DateTime.Now
Dim adesso_stringa As String
Dim
Dim
Dim
Dim
Dim
store_id As String
importo_hash As String
shared_secret As String
hash_hex As String
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"/>
8
<asp:Button id="send" runat="server" Text="Continua" PostBackUrl="https://test.ipgonline.com/connect/gateway/processing"/>
</form>
</body>
</html>
2.5 Pagina di esempio in ColdFusion
Riportiamo di seguito una pagina ColdFusion con le caratteristiche della pagina ASP illustrata sopra.
<cfset DataTransazione = DateFormat(Now(),'yyyy:mm:dd') & "-" & TimeFormat(Now(),'HH:mm:ss')>
<cfset Importo = "10.00">
<cfset StoreNumber = "1003xxxxxxx ">
<cfset SharedSecret = "sharedsecret">
<cfset Stringa = StoreNumber & DataTransazione & Importo & 978 & SharedSecret>
<cfset StringaAscii = "">
<cfloop from="1" to="#Len(Stringa)#" index="idxCarattere">
<cfset StringaAscii = StringaAscii & FormatBaseN(Asc(Mid(Stringa, idxCarattere, 1)), 16)>
</cfloop>
<cfset Codice = LCase(Hash(StringaAscii,"SHA"))>
<cfoutput>
<form method="post" action="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>
2.6 Transazioni ed esiti in ambiente di test
Nell’ambiente di test è possibile effettuare delle transazioni utilizzando queste carte di credito:
Circuito
Numero
Scadenza
CVC
Password 3D Secure
Visa
MasterCard
4111111111111111
5232050000010003
12/2013
12/2013
147 o altro valore
003 o altro valore
(servizio non attivo)
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 <= 1.000 EUR ad esempio 10,00 EUR.
Le transazioni inviate con importi non interi – ad esempio 10,01 EUR o 13,99 EUR – o uguali/superiori a
1.000 EUR verranno negate, in modo da consentire di simulare dei casi di autorizzazioni negate.
In questo modo sarà possibile controllare l’esito della transazione e testare il comportamento della pagina
di conferma e dell’intero sistema (soprattutto dal vostro lato) sia in caso di transazioni andate a buon fine,
sia in caso di transazioni negate.
9
É 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
timezone
GMT · CET · EET
txndatetime
AAAA:MM:GG-hh:mm:ss
hash
storename
mode
payonly · payplus · fullpay
chargetotal
x.xx · xxxx.xx
currency
978
Sale
PreAuth
PostAuth
Void
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
×
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
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.
NotificationURL
•
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
Inglese
Tedesco
Francese
12
it_IT
en_GB
de_DE
fr_FR
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
bcompany
bname
baddr1
baddr2
bcity
bstate
bcountry
bzip
phone
fax
email
Formato
Descrizione
Caratteri alfanumerici, spazi e barre
Caratteri alfanumerici, spazi e barre
Caratteri alfanumerici e spazi
Caratteri alfanumerici e spazi
Caratteri alfanumerici e spazi
Massimo 30 caratteri
2 lettere (IT per Italia)
5 cifre
Massimo 20 cifre
Massimo 20 cifre
Massimo 45 caratteri alfanumerici
Azienda
Nome
Indirizzo
Indirizzo
Città
Provincia
Nazione
CAP
Numero di telefono
Numero di fax
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
sname
saddr1
saddr2
scity
sstate
scountry
szip
Formato
Descrizione
Caratteri alfanumerici, spazi e barre
Caratteri alfanumerici e spazi
Caratteri alfanumerici e spazi
Caratteri alfanumerici e spazi
Massimo 30 caratteri
2 lettere (IT per Italia)
5 cifre
Nome del destinatario
Indirizzo di spedizione
Indirizzo di spedizione
Città
Provincia
Nazione
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 [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.
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.
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 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
Codice assegnato all’ordine
oid
response_hash
notification_hash
chargetotal
Codice di risposta che garantisce l’identità di BNL POSitivity
Codice di risposta che garantisce l’identità di BNL POSitivity (restituito
solo se si utilizza transactionNotificationURL)
Importo della transazione
16
currency
cardnumber
expyear
refnumber
response_code_3dsecure
tdate
txntype
txndate_processed
ccbin
approval_code
status
timezone
terminal_id
processor_response_code
Valuta della transazione
Circuito e ultime 4 cifre della carta di credito
Anno di scadenza della carta di credito
Codice di riferimento della transazione
Esito dell’autenticazione 3D Secure (Verified by Visa/SecureCode)
Identifica in modo univoco la transazione all’interno dell’ordine; va
conservato ed inviato al gateway in caso di transazione Void
Tipo di transazione (vendita, pre-autorizzazione...)
Data e ora di elaborazione del pagamento
Prime 6 cifre della carta (identificano la banca emittente)
• se transazione approvata Y: seguito dal codice autorizzativo
• se transazione negata
N: seguito dalla motivazione
Esito della transazione. Se contiene APPROVATO, APPROVED o
GENEHMIGT (in base alla lingua utilizzata) la transazione è andata a
buon fine; qualsiasi altro valore identifica una transazione negata.
Fuso orario
Codice del terminale virtuale
Codice di risposta della transazione. Riporta il codice associato
all’errore; se la transazione è andata a buon fine contiene 00 o 000
Per costruire una buona pagina di conferma delle transazioni, è opportuno approfondire meglio alcuni dei
parametri sopra elencati.
•
status
Consente di capire se la transazione è stata approvata o negata. In particolare:
− contiene APPROVED/APPROVATO/GENEHMIGT se la transazione è andata a buon fine;
− contiene DECLINED/RIFIUTATO se la transazione è stata negata;
− contiene DUPLICATE/DUPLICATO se la transazione viene respinta dal sistema per codice
ordine già utilizzato o se la transazione è stata considerata come ripetuta;
− contiene FRAUD se la transazione viene respinta dal filtro anti-frode del sistema.
Dal momento che il campo status può assumere molti valori diversi (DUPLICATE, FRAUD…), la
transazione va considerata approvata esclusivamente se il parametro status contiene il valore
APPROVED / APPROVATO / GENEHMIGT (in base al valore del campo language).
Qualsiasi altro valore rappresenta una transazione non andata a buon fine.
Fare riferimento alla pagina successiva per ottenere un esempio pratico di controllo della
variabile per determinare cosa visualizzare sulla pagina di conferma.
•
response_hash
Consente di verificare se la risposta è stata effettivamente generata da BNL POSitivity, in modo da
poter identificare in modo chiaro i tentativi di frode.
La stringa viene creata con un hash SHA1 utilizzando i seguenti parametri nell’ordine esatto:
sharedsecret + approval_code + chargetotal + currency + txndatetime + storename
Va evidenziato che il campo txndatetime non corrisponde al parametro txndate_processed
restituito nella pagina di conferma, ma equivale alla data/ora inviata dalla vostra pagina al
gateway con nome txndatetime. Dal momento che questo parametro non viene restituito di
17
default, vi consigliamo di inviare un parametro aggiuntivo (ad esempio chiamandolo dataora)
assegnandogli lo stesso valore di txndatetime.
Questo parametro personalizzato verrà restituito nella pagina di conferma con il nome da voi
impostato e potrà essere impiegato al posto ti txndatetime nella costruzione del vostro
response_hash, che andrà poi confrontato con quello restituito dal sistema.
•
notification_hash
In caso venga utilizzata la funzione di notifica delle transazioni ad un URL specificato tramite la
variabile transactionNotificationURL (descritta a pagina 12), il campo response_hash
illustrato sopra viene sostituito dal parametro notification_hash esclusivamente per la
risposta restituita all’URL di notifica; alle pagine responseSuccessURL e responseFailURL il
sistema continuerà a restituire la variabile response_hash.
La stringa viene creata con un hash SHA1 utilizzando i seguenti parametri nell’ordine esatto:
chargetotal + sharedsecret + currency + txndatetime + storename + approval_code
Va segnalato che anche per questo parametro valgono le stesse osservazioni effettuate per il
campo response_hash relative al valore del parametro txndatetime.
•
response_code_3dsecure
Fornisce l’esito dell’autenticazione 3D Secure. I possibili valori della variabile sono:
1 – autenticazione avvenuta (Visa ECI 5)
2 – autenticazione avvenuta senza AVV (Visa ECI 5)
3 – autenticazione fallita per password errata (transazione negata)
4 – tentata autenticazione (Visa ECI 6)
5 – impossibile effettuare l’autenticazione per mancata risposta da DS (Visa ECI 7)
6 – impossibile effettuare l’autenticazione per mancata risposta da ACS (Visa ECI 7)
7 – carta non attivata per 3D Secure (Visa ECI 6)
8 – valori 3D Secure ricevuti dalla banca non validi
I dettagli della transazione vengono restituiti come parametri POST sulle pagine di conferma; sarà poi
necessario decidere quali parametri mostrare a video utilizzando la sintassi del linguaggio scelto.
Di seguito trovate un esempio di semplice pagina PHP che verifica l’esito della transazione tramite la
variabile status e, in base al valore della stessa, mostra determinati campi. Implementando questo tipo
di controllo è possibile utilizzare la stessa pagina di conferma sia come responseSuccessURL che come
responseFailURL; in alternativa è possibile costruirne due separate.
<?php
if (($_POST['status'] == 'APPROVED') || ($_POST['status'] == 'APPROVATO') || ($_POST['status']
== 'GENEHMIGT')) {
echo
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>";
}
18
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>";
}
?>
19
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
20