Documento Tecnico per l`Integrazione al servizio BANKPASS Web

Documento Tecnico per l’Integrazione al servizio
BANKPASS Web
WEB
Release n. 2.2
Data: Ottobre 2004
SOCIETÀ PER I SERVIZI BANCARI - S.S.B. S.p.A.
Sede Sociale e Direzione Generale: via Faravelli, 14 – 20149 Milano - Cap. Soc. Euro 10.763.984,27 int.vers. - C.F. e P. IVA e registro delle Imprese di
Milano 10596540152 – R.E.A. di Milano n. 1385874 - Tel. +39 02.3484.1 - Telex 313824 S.S.B. MI - Fax +39 02.3310.5661
Fax: Direzione Direzione Marketing e vendite: +39 02.3484.4098 – Divisione E-Business: +39 02.3484.4086 – Divisione Issuing e Divisione Acquiring: +39 02.3484.4010
Sommario
SOMMARIO ...................................................................................................................................................................... 2
GLOSSARIO ...................................................................................................................................................................... 3
SCOPO .............................................................................................................................................................................. 4
INTRODUZIONE ............................................................................................................................................................ 4
Utilizzo da parte dell’utente Bankpass Web...............................................................................................................................4
INTEGRAZIONE BANKPASS WEB ............................................................................................................................ 7
I MESSAGGI ................................................................................................................................................................... 10
Messaggio di avvio transazione Bankpass Web ....................................................................................................... 10
Messaggio di conferma dell’avvenuto pagamento Bankpass Web ........................................................................... 14
API BACKOFFICE........................................................................................................................................................ 16
APPENDICE................................................................................................................................................................... 17
APPENDICE A (FAQ)..................................................................................................................................................... 17
APPENDICE B (RIFERIMENTI) ........................................................................................................................................ 19
APPENDICE C GENERAZIONE MAC (FLUSSO ACQUISTO) ....................................................................................... 20
C1 Generazione del MAC per i messaggi di avvio transazione............................................................................... 20
C2 Generazione del MAC per il messaggio esito .................................................................................................... 21
APPENDICE E PARAMETRI TAUTOR, TCONTAB E SCENARI POSSIBILI ....................................................................... 22
TAUTOR ................................................................................................................................................................... 22
TCONTAB................................................................................................................................................................. 22
Contabilizzazione immediata I .................................................................................................................................................22
Contabilizzazione differita D ...................................................................................................................................................22
Scenari possibili........................................................................................................................................................ 23
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 2 di 23
Glossario
Backoffice
Usato per far riferimento alla funzioni di gestione di un negozio: resoconti,
elenchi, interrogazioni , disposizioni etc.
CC
Carta di credito
Contabilizzazione Operazione che crea gli effetti contabili per una transazione che era stata
precedentemente autorizzata
Credit
Operazione contabile per la restituzione di una somma di denaro ad un cliente
GET
Operazione di comunicazione del protocollo HTTP
Hash
Insieme di N bit (es. 128, 160) ricavato da una stringa con un procedimento
matematico in modo che a partire da stringhe diverse non si abbia mai lo stesso
risultato
HTTP
Protocollo applicativo utilizzato per trasmettere le pagine web. Standard RFC 2068
MAC
Codice di autenticazione del messaggio
MD5
Algoritmo per la generazione di un identificativo univoco di 16 byte di un
messaggio. Definito nella RFC 1321
Merchant system Sistema softare di gestione di un negozio virtuale. Negozio virtuale
PFE
Processor di FrontEnd: SSB Spa
POST
Operazione di comunicazione del protocollo HTTP
Secure code
Protocollo per pagamenti sicuri definito da MasterCard
SHA-1
Secure Hash Algorithm. Algoritmo per la generazione di hash. Standard NIST
FIPS 180-1
Split
Operazione per suddividere/ridurre un pagamento già effettuato.
SSL
Secure Socket Layer protocollo di trasporto standard ideato da Netscape
Communication
Storno
Operazione di annullamento di una autorizzazione concessa con la restituizione del
denaro e/o del limite di spesa al titolare della carta
URL
Universal resource locator
VBV
Verified by Visa - Protocollo per pagamenti sicuri definito da Visa
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 3 di 23
Scopo
Il presente documento contiene le informazioni tecniche necessarie a chi sviluppa negozi virtuali, per effettuare
l'integrazione fra il proprio canale di vendita ed il sistema BankPass Web. Destinatari del documento sono quindi figure
prettamente tecniche. Questo manuale non contiene una descrizione vera e propria del servizio BankPass che viene
invece riportata negli appositi documenti.
Introduzione
Il sistema BankPass rappresenta una soluzione semplice ed efficace per i pagamenti online tramite Internet.
BankPass Web si basa su un meccanismo molto semplice: una volta terminata la fase di acquisto sul sito web
dell’esercente l’utente si reca presso il sito del PFE per effettuare il pagamento di quanto dovuto, e ritorna al negozio
con una ricevuta rilasciata dal PFE stesso. A questo punto il negozio darà il via al processo di invio della merce, o di
fruizione del servizio in caso di siti tipo pay per view (download di informazioni, software, etc).
Il cliente finale, potrà scegliere quale modalità di pagamento utilizzare fra quelle rese disponibili dal servizio: aderente
Bankpass Web utilizzando gli strumenti del proprio Wallet oppure SSL.
Le modalità disponibili Bankpass web
Utente aderente BankPass Web
Utente
Modalità SSL
Utilizzo da parte dell’utente Bankpass Web
L’utente finale aderente, o non aderente al servizio, è chiamato a compilare dei campi di semplici pagine HTML. Non è
necessario l’ausilio di un agente esterno al browser, quindi nessun plug-in od activex da “scaricare” ed installare.
Il fatto che l’utente in generale debba solo compilare delle form significa che non vi è nessuna restrizione di piattaforma
hardware, o di sistema operativo: l’utente potrà utilizzare qualsiasi computer che abbia a disposizione un browser
abilitato ad SSL 128 bit (praticamente tutti quelli oggi in commercio).
L’utente finale, che viene "rediretto" dal negozio al sito BankPass Web, viene accolto da una schermata che gli permette
di scegliere la modalità con la quale intende effettuare il pagamento. I clienti aderenti a BankPass Web, dovranno
scegliere la banca che ha rilasciato il propro Wallet tramite un apposito menù, potranno poi effettuare l'operazione di
login al Wallet. I clienti che intendono completare il pagamento fornendo direttamente i dati della propria carta di
credito, dovranno fare "click" sui loghi delle carte di credito accettate (modalità SSL).
Una volta scelta la modalità di pagamento la navigazione del cliente dipende strettamente da essa. Una descrizione più
dettagliata è fornita nel seguito. Completata l'operazione di pagamento il PFE comunica l'esito al merchant system, ed
il cliente può ritornare al negozio portando con se la "ricevuta" che attesta la conclusione della transazione.
Nella pagina successiva viene riportato un diagramma che illustra la navigazione del cliente finale all'interno del
sistema complessivo con le varie azioni possibili.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 4 di 23
Negozio
Annulla
Redirect Avvio
Annulla
Annulla
Scelta
Modalità
Cliente
aderente
Cliente non
aderente
Pagamento concluso
Transazione conclusa
positivamente
Invio email e
comunicazione al
merchant system
dell'esito
Figura 1
Nel seguito vengono brevemente descritte le due modalità di pagamento precedentemente citate:
Modalità SSL
L’utente finale che sceglie la modalità SSL deve compilare dei campi in un form, dove vengono raccolti gli estremi
della sua carta di credito.
Per l'utilizzo della modalità SSL non è necessaria una registrazione da parte dell'acquirente. Questa modalità rende
possibile gli acquisti da parte di clienti esteri non aderenti a BankPass Web.
Una volta iniziato il processo di pagamento, l’utente può completare l'inserimento dei dati, oppure annullare
l’operazione e tornare al sito del negozio. Se sceglie di proseguire la richiesta di transazione viene inviata al PFE ed
elaborata.
Nel caso in cui l’autorizzazione sia stata concessa l’esito viene comunicato sia all’utente che al negozio, dopodichè il
cliente, facendo click su un pulsante, fa si che il suo browser ritorni su una pagina del negozio di provenienza (la URL
di tale pagina viene indicata nel messaggio di redirect iniziale).
Se l’esito è negativo all’utente viene mostrato un breve messaggio che spiega il motivo della negazione; a questo punto
l’utente può scegliere se riprovare ad inviare la transazione oppure se tornare al negozio.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 5 di 23
Modalità BankPass (consumatore aderente)
Il cliente che sceglie la modalità BankPass Web deve essere aderente al sistema BankPass Web. La scelta viene
effettuata semplicemente scegliendo la banca che ha rilasciato il wallet, riempiendo i campi "login" e "password"
disponibili e facendo click sul pulsante "entra". Il cliente una volta autenticato, vedrà apparire l'elenco degli strumenti
(carte di credito o Bancomat) disponibili nel proprio wallet compatibili con quelli accettati dal sito dell'esercente.
Scelto lo strumento con il quale intende pagare dà il via al processo di pagamento.
Terminata la transazione il sistema si comporta come nella modalità SSL: nel caso in cui l’autorizzazione sia stata
concessa l’esito viene comunicato sia all’utente sia al negozio, dopodichè il cliente facendo click su un pulsante fa si
che il suo browser vada su una pagina del merchant system. Se l’esito è negativo all’utente viene mostrato un breve
messaggio che spiega il motivo della negazione; a questo punto l’utente può scegliere se riprovare ad inviare la
transazione oppure se tornare al negozio.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 6 di 23
Integrazione Bankpass Web
L’interazione con il merchant system, come già precedentemente accennato, si basa su un meccanismo di delega: una
volta che l’utente ha terminato la compilazione dell’ordine, il merchant system fa si che il suo browser si colleghi
automaticamente al PFE per accedere al servizio di pagamento on-line, comunicando tutti i dati necessari. A questo
punto il PFE gestisce tutto il colloquio con il cliente riguardante la transazione. L'utente ha la possibilità di portare a
termine l'operazione o di annullarla; in entrambi i casi il suo browser verrà indirizzato verso le opportune pagine del
negozio di provenienza. Questo risulta vero per tutte le modalità di pagamento disponibili.
Per rendere possibile l'indirizzamento del browser dell'utente verso le pagine corrette, nel primo messaggio inviato al
PFE il merchant system inserisce tre campi speciali che contengono tre URL:
•
•
•
La URL verso la quale mandare l’utente in caso di annullamento del processo di pagamento e ritorno alla modifica
del basket (URLBACK)
La URL verso la quale mandare l’utente in caso di completamento della transazione con esito positivo
(URLDONE)
La URL che il PFE deve utilizzare per comunicare direttamente l’esito della transazione compiuta (URLMS)
La URL per l’avvio del processo di pagamento verso la quale indirizzare il browser dell’utente è:
Ambiente di TEST:
http://sis-test-bankpass.ssb.it/bankpass/master/main?PAGE=MASTER
Ambiente di PRODUZIONE:
https://sis-bankpass.ssb.it/bankpass/master/main?PAGE=MASTER
N.B. Rimane inteso che tutte le URL con protocollo HTTPS del sistema Bankpass Web (pagina di pagamento, area
Back Office esercente, area wallet consumatore) sono accessibili tramite browser abilitato al protocollo SSL 128 bit.
Nei diagrammi sottostanti è riportato un modello molto semplificato del comportamento del sistema.
: Utente
1. Redirect avvio
: Browser
Cliente
Negozio
Virtuale
1.1. Redirect avvio
2. Pagamento
4. Esito
3. Esito
PFE
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 7 di 23
Il successivo diagramma riprende lo schema fornito in precedenza e lo dettaglia. In esso viene mostrata la navigazione
del cliente finale all'interno del sistema. Le frecce rappresentano gli eventi (azioni del cliente) e ad esse sono associate
le URL verso le quali viene indirizzato il browser. In colore scuro sono indicate le "pagine" del negozio.
Pagina di avvio
pagamento
Fine chiusura basket
Pagina di rientro
per Annulla
Annulla: URLBACK
GET-POST
URLSTART
Annulla: URLBACK
Scelta
Modalità
Annulla: URLBACK
Cliente non
aderente
Cliente
aderente
Transazione conclusa
Positivamente
Torna al negozio: URLDONE
Pagina pagamento
concluso per il cliente
Il server PFE invia le email e
Comunica direttamente al
Merchant system l'esito
GET verso URLMS
Ricezione esito
Di seguito viene illustrato schematicamente il processo seguito durante un acquisto:
1.
terminata la fase di checkout il merchant system fa si che il browser dell’utente si colleghi al PFE comunicando
l’importo, la valuta, il numero d’ordine, etc. e le 3 URL di cui sopra: URLBACK, URLDONE ed URLMS
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 8 di 23
2.
il server SSL del PFE presenta all’utente una pagina che contiene:
• i dati dell’ordine ricevuti
• la possibilità di scegliere la modalità di pagamento
• un pulsante per tornare al basket del negozio (Annulla, Torna al negozio)
3.
l’utente sceglie la modalità e segue il processo specifico; conferma il pagamento inviando i dati al PFE
5.
Il PFE elabora i dati della carta; se l’esito è positivo notifica il merchant system del venditore tramite un messaggio
HTTP con GET o POST.
6.
IL PFE invia all’utente una pagina HTML contenente l’esito della transazione.
7.
se la risposta è positiva l’utente facendo click su un pulsante verrà indirizzato verso URLDONE, se è negativa
potrà riprovare oppure tornare al negozio venendo reindirizzato su URLBACK (ritorno al basket). Il server del
PFE comunica direttamente al negozio l'esito della transazione eseguendo esso stesso una GET o POST (la
modalità POST è in fase di rilascio) HTTP verso la URL URLMS
Per autenticare i messaggi che il PFE ed il merchant system si scambiano (avvio ed esito) viene utilizzato un semplice
meccanismo di MAC (message authentication code).
L’esito delle operazioni eseguite viene comunicato sia all’utente, sia al negozio, anche attraverso l’invio di messaggi di
e-mail. Tale comunicazione avviene sia in caso di esito positivo, che in caso di esito negativo.
I messaggi inviati non sono personalizzabili.
Nell’anagrafica del negozio virtuale è possibile specificare se si desidera usufruire del servizio di notifica delle
operazioni tramite e-mail oppure no.
Invio logo:
L’amministratore del backoffice dopo essersi autenticato tramite user-ID e password può inviare il proprio logo
accedendo all’interno della gestione negozi, in particolare nel dettaglio negozio. Il logo del negozio deve avere
dimensioni massime di 140x70pixel e minime di 70x70 pixel e pesantezza massima di 20 Kb.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 9 di 23
I messaggi
Messaggio di avvio transazione Bankpass Web
Il primo passo che il merchant system deve compiere è far generare al browser del cliente un messaggio di avvio del
processo di pagamento verso il PFE. Questo può essere fatto sia con una redirezione, od un link, (utilizzando quindi il
metodo HTTP GET) sia attraverso l’invio di una form con campi nascosti (che può utilizzare il metodo HTTP POST).
NB: la pagina di pagamento necessità di scrivere cookies di sessione, si consiglia per tanto di non inserirla
all'interno di frames, potrebbero esserci problemi con alcune impostazioni dei browser.
Il messaggio di avvio della transazione che arriva al PFE dal browser dell’utente deve contenere i seguenti campi:
Campi comuni
Nome
Obbligatorio Descrizione
IMPORTO
S
Importo espresso nell’unità minima della valuta (centesimi di
euro). Lunghezza minima 2 massima 8
VALUTA
S
Valuta: codice ISO (EUR = 978)
NUMORD
S
IDNEGOZIO
S
Identificativo univoco dell’ordine: deve essere un codice alfanumerico lungo al massimo 50 caratteri. La sua univocità
deve essere garantita per almeno 5 anni.
Identificatore del negozio del merchant assegnato dalla
BANCA, Codice Riconoscimento Negozio(CRN)
URLBACK
S
URLDONE
S
URLMS
S
URL del merchant system verso la quale il PFE effettua la
GET o POST di conferma dell’avvenuto pagamento. (può
contenere eventuali parametri impostati dal negozio). Il
sistema appende ad essa i parametri dell'esito. Lunghezza
massima 400 caratteri
TCONTAB
S
TAUTOR
S
Tipo di contabilizzazione da utilizzare per questo ordine:
• D differita
• I immediata
Vedi appendice E
Tipo di autorizzazione da utilizzare per questo ordine:
• D differita
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
URL completa verso la quale eseguire una redirect per
rimandare l’utente al negozio (può comprendere tutti gli
eventuali parametri da passare) nel caso di annullamento del
processo di pagamento. Lunghezza massima 254 caratteri
URL completa verso la quale redirigere il browser del cliente
a transazione avvenuta con successo (può comprendere tutti
gli eventuali parametri da passare). Il sistema appende ad
essa i parametri dell'esito. Lunghezza massima 254 caratteri
Pag. 10 di 23
• I immediata
Vedi appendice E
Campo di firma della transazione: rende immodificabile da
parte dell'utente finale i dati dell'ordine. Per il calcolo si veda
appendice C1.
MAC
S
LINGUA
N
Lingua nella quale devono essere mostrati i messaggi di
interazione con l’utente finale. Il campo è facoltativo; di
default la lingua è quella Italiana.
I codici sono quelli accettati secondo lo standard ISO 3166.
Attualmente sono disponibili:
ITA italiano
EN/US/USA inglese
DEU tedesco
FRA francese
SPA spagnolo
EMAILESERC
N
Contiene l'indirizzo email al quale inviare la email di esito
della transazione. Se non è presente viene utilizzato quello
disponibile nella anagrafica PFE del negozio. Lunghezza
minima 7 caratteri alfanumerici massima 50
OPTIONS
N
Contiene gli indicatori delle opzioni aggiuntive che
s'intendono attivare per il pagamento in corso. L’ordine con il
quale appaiono le opzioni è indifferente. Il contenuto del
campo non è case sensitive. Vedere paragrafo corrispondente
per dettagli ulteriori
Obbligatorio: S = si, N = no
Campi aggiuntivi utilizzabili dal sistema per gli utenti che scelgono la modalità SSL
Nome
EMAIL
Obbligatorio Descrizione
N
Indirizzo di e-mail del cliente.
In modalitò SSL se il campo non è presente verrà richiesto
all’utente insieme ai dati della carta di credito.
Lunghezza minima 7 caratteri alfanumerici massima 50.
Nota: i nomi dei campi delle tabelle sopra riportate sono tutti maiuscoli e sono case sensitive.
L’ordine nel quale appaiono i campi nel messaggio di avvio è indifferente.
Nel processo di comunicazione tra il merchant ed il PFE vi è il rischio che un soggetto estraneo, intercettato il
messaggio, cerchi di alterarne il contenuto, rispedendolo poi al destinatario finale. Questo evento può essere scoperto
introducendo un processo di autenticazione tramite un MAC (Message Authentication Code) dei messaggi che vengono
trasmessi.
Il metodo seguito per generare il MAC è il seguente: viene calcolato un hash MD5 o SHA-1 della stringa risultante dal
concatenamento dei parametri da trasmettere e di una stringa segreta (stringa di N byte, attualmente 50, condivisa dal
PFE e dal singolo merchant system). Il destinatario, possedendo la stessa stringa segreta, può verificare il MAC e quindi
l’autenticità dei parametri ricevuti.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 11 di 23
Esistono due stringhe segrete in possesso dell’esercente:
• “chiave di avvio”: è la stringa per il calcolo del MAC nei messaggi di avvio pagamento sopra descritto
• “chiave di esito-API”: è la stringa per la verifica del MAC nei messaggi di esito emessi dal PFE e per l’uso delle
API backoffice
I metodi per calcolare il MAC relativo alle richieste di pagamento e agli esiti (comunicati dal PFE) sono indicati
rispettivamente nelle appendici C1 e C2 di questo documento. Le stringhe segrete vengono comunicate, in maniera
sicura, al negozio dal PFE al momento dell’attivazione del servizio.
Il contenuto dei campi URLDONE , URLBACK ed URLMS è a completa discrezione del negozio. Per quanto riguarda
URLDONE ed URLMS si tenga presente che i dati identificativi dell’ordine vengono comunque appesi dal PFE in
fondo a queste due stringe come viene documentato nel paragrafo sottostante. La lunghezza massima di URLDONE e
URLBACK è di 254 caratteri mentre dell’URLMS è di 400 caratteri.
Se le stringhe originali che rappresentano le URL del merchant system comprendono parametri o dei caratteri
particolari, esse dovranno essere passate in formato MIME application/x-www-form-urlencoded (I caratteri particolari
sono trasformati in %XX ).
La redirezione del browser dell’utente verso le URL URLDONE ed URLBACK è effettuata tramite il metodo HTTP
GET.
Le URL URLDONE e URLBACK devono cominciare con “http://” o “https//” (o un qualsiasi altro schema HTTP
valido interpretabile dai browser).
La URL URLMS deve cominciare con “http://”; la porta utilizzata non può essere diversa da quella standard: 80.
I valori sopra indicati devono comunque rispettare la prima indicazione e, cioè, devono essere trasmessi in formato
MIME application/x-www-form-urlencoded.
Campo OPTIONS
Il campo OPTIONS permette di attivare varie opzioni aggiuntive per il pagamento in corso. Le opzioni sono indicate
tramite una lettera dell’alfabeto. Le opzioni oggi disponibili sono:
• A - il sistema metterà in URLDONE ed URLMS il campo BPW_MODPAG che indica la modalità di
pagamento utilizzata dal cliente:
o pagamento aderente Bankpass:
01
o pagamento non aderente Bankpass:
02
• Β - il sistema accetta due ulteriori campi nel messaggio in ingresso: NOME e COGNOME. Il valore di tali
campi, se presenti, viene memorizzato associato all’ordine in corso. I campi non sono modificabili dal
cliente e non sono visualizzati. Per garantire la non modificabilità dei valori i campi entrano a par parte
della stringa per il calcolo del MAC. I campi NOME e COGNOME non sono comunque obbligatori
• C - il sistema permetterà all’utente finale di effettuare solo pagamenti SSL saltando il passo di scelta della
modalità. All’utente apparirà direttamente la maschera d'inserimento dei dati della carta di credito.1
NB: il circuito PAGOBANCOMAT è disponibile solo con OPTIONS=D
• D - il sistema permetterà all’utente finale di effettuare solo pagamenti di tipo Bankpass. Non si potrà
accedere alla parte di pagamenti SSL.
1
Nel caso si utilizza il parametro OPTIONS=C, per l’accesso diretto alla procedura di pagamento SSL, se la schermata
d'inserimento dei campi per il pagamento (PAN, data scadenza, ecc…) è contenuta in un frameset di un sito Esercente
non HTTPS, nel browser del Consumatore non compare il “lucchetto” simbolo della connessione sicura SSL; questo
nonostante la connessione verso BANKPASS sia in ogni caso una connessione SSL.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 12 di 23
• E - il sistema metterà in URLDONE ed URLMS il campo BPW_ TIPO_TRANSAZIONE che indica la
tipologia di pagamento effettuato (cfr. tabella valori campo BPW_TIPO_TRANSAZIONE).
L’ordine con il quale le opzioni appaiono non è rilevante.
Le opzioni possono essere indifferentemente indicate con lettere maiuscole o minuscole: OPTIONS=a equivale a
OPTIONS=A
Esempi
Gli esempi sotto riportati non sono funzionanti: essi forniscono solo una indicazione di massima di come poter avviare
il processo di pagamento.
Sotto viene riportato un esempio che utilizza una GET per avviare una transazione con il sistema BankPass di test
http://sis-testbankpass.ssb.it/bankpass/master/main?URLBACK=http%3A%2F%2Fdemo.demo.net%2Fdemoshop%2Fbackfromtl.ht
ml%3FIdShop%3D00000000000&MAC=809b6bc84df7c41e5899c0435fd2ef5b&NUMORD=ord9856&TAUTOR=I&
URLMS=http%3A%2F%2Fdemo.demo.net%2Findex.html&[email protected]&VALUTA=978&PAG
E=MASTER&TCONTAB=D&IDNEGOZIO=010500000000001&[email protected]&LINGUA=IT
A&IMPORTO=5200&URLDONE=http%3A%2F%2Fdemo.demo.net%2Fmimesys%2Furlok.html%3Foper%3D900
da notare i campi URLDONE, URLBACK, ed URLMS che sono in formato cosiddetto urlencoded.
L’esempio sottostante dimostra invece l’attivazione del sistema BankPass attraverso l’uso di una form.
<html>
<body>
<br><center>
Test BankPass
<form action="http://sis-test-bankpass.ssb.it/bankpass/master/main?PAGE=MASTER"
method="POST">
<input type="hidden" name="PAGE" value="MASTER">
IMPORTO=5000<br>
<input type="hidden" name="IMPORTO" value="5000">
VALUTA=978<br>
<input type="hidden" name="VALUTA" value="978">
LINGUA=ITA<br>
<input type="hidden" name="LINGUA" value="ITA">
IDNEGOZIO=000000000000001<br>
<input type="hidden" name="IDNEGOZIO" value="010500000000001">
NUMORD=13331<br>
<input type="hidden" name="NUMORD" value="A13331">
<input type="hidden" name="URLDONE"
value="http://demo.demo.net/mimesys/urlok.html?oper=900">
<input type="hidden" name="URLBACK"
value="http://demo.demo.net/demoshop/backfromtl.html?IdShop=00000000000">
<input type="hidden" name="URLMS"
value="http://demo.ssb.net/[email protected]&CARRELLO=02">
<input type="hidden" name="TCONTAB" value="D">
<input type="hidden" name="TAUTOR" value="I">
<input type="hidden" name="OPTIONS" value="a">
<input type="hidden" name="EMAIL" value="[email protected]">
<input type="hidden" name="EMAILESERC" value="[email protected]">
<input type="hidden" name="MAC" value="a45f96a0bd4f8456a8fcfc9f6e1e2d27">
<input type=submit value="Avvia..." >
</form>
</body>
</html>
Le URL nei campi hidden devono essere riportate normalmente perché i browser provvedono automaticamente ad
eseguire la necessaria codifica quando l'utente esegue la submit.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 13 di 23
Messaggio di conferma dell’avvenuto pagamento Bankpass Web
L’esito dell’operazione, in caso di autorizzazione concessa, viene comunicato al merchant system tramite due distinti
percorsi. Il primo passa dal browser dell’utente, il secondo avviene direttamente dal server del PFE verso il negozio.
In particolare l’esito viene comunicato al merchant utilizzando gli indirizzi indicati nei parametri URLDONE e
URLMS, il primo viene contattato, a discrezione dell'acquirente, solo al termine della transazione; il secondo invece
viene contattato dal server del PFE, indipendentemente dalle azioni del cliente, non appena il circuito autorizzativo
risponde alla richiesta inoltrata dal sistema BankPass. L’utilizzo del secondo indirizzo dà una buona certezza che l’esito
della transazione venga comunicato al merchant system indipendentemente dalle azioni del cliente.
In fase di adesione si può scegliere se utilizzare URLMS per ottenere comunicazione tramite questo meccanismo solo
per le transazioni con esito positivo, o per tutte le transazioni: con esito positivo e negativo. L'opzione consigliata è la
prima: comunicazione dei soli esiti positivi.
Nel caso si scelga la seconda opzione bisogna tener presente il fatto che il cliente, in caso di insuccesso della prima
transazione, può eseguire diversi tentativi di pagamento consecutivi per uno stesso ordine. In questo caso il merchant
system si vedrebbe comunicare N esiti negativi per gli N insuccessi, ed alla fine un esito positivo.
Il messaggio di conferma della transazione contiene i seguenti dati:
Nome campo
NUMORD
Descizione
numero d’ordine: valore copiato dal campo del messaggio di avvio NUMORD
IDNEGOZIO
Codice Riconoscimento Negozio(CRN): valore copiato dall’omonimo campo del
messaggio di avvio
AUT
Numero autorizzazione: identificativo della autorizzazione assegnato dall’emittente
della carta (solo in caso di esito positivo). Se l’autorizzazione non è stata concessa, il
campo è valorizzato con “NULL”
IMPORTO
Importo: valore copiato dall’omonimo campo del messaggio di avvio
VALUTA
Valuta: valore copiato dall’omonimo campo del messaggio di avvio
IDTRANS
Identificativo della transazione assegnato dal sistema BankPass
MAC
Valore per l’autenticazione del messaggio di conferma. Per il calcolo si veda
l’appendice C2
ESITO
Esito della transazione. Vedi pagina successiva
TAUTOR
Tipo di autorizzazione: I immediata D differita. Valore copiato dall’omonimo campo
del messaggio di avvio
Tipo di contabilizzazione: I immeditata D differita. Valore copiato dall’omonimo
campo del messaggio di avvio
Questo campo è presente solo se richiesto tramite il campo options (A); indica la
modalità di pagamento utilizzata dal cliente (pagamento aderente Bankpass: 01,
pagamento non aderente Bankpass: 02)
Tipo di carta utilizzata dal cliente per il pagamento. Vedi pagina successiva
TCONTAB
BPW_MODPAG
CARTA
BPW_TIPO_TRANSAZIONE
Questo campo è presente solo se richiesto tramite il campo options (E); inidca il tipo
di transzione effettuato (cfr. tabella valori campo BPW_TIPO_TRANSAZIONE)
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 14 di 23
Il messaggio che il merchant system si vedrà recapitare alle URL URLMS ed URLDONE sarà così costituito:
URLMS:
URLMS + &<conferma> + &MAC=<mac>
URLDONE:
URLDONE +&<conferma> + &MAC=<mac>
Dove:
<conferma> = “NUMORD=<numero d’ordine> + &IDNEGOZIO=<merchant id> + &AUT=<numero autor>
+&IMPORTO=<importo> +&IDTRANS= <id.transazione BankPass>&VAL=<valuta>&<TAUTOR>=<tipo
autorizzazione>&ESITO=<esito>&BPW_MODPAG =<modalità di pagamento (se presente)>&CARTA=<tipo
carta><TCONTAB>=<tipo contabil>”
Il campo ESITO può assumere i seguenti valori
Codice
00
01
02
03
04
05
06
Descrizione
Successo
Negata dal sistema
Negata per problemi sull'anagrafica negozio
Negata per problemi di comunicazione con i circuiti
autorizzativi
Negata dall'emittente della carta
Negata per numero carta errato
Errore imprevisto durante l’elaborazione della richiesta
Nota: nella attuale implementazione l’unico valore assunto da ESITO in URLDONE è 00
Il campo CARTA può assumere i seguenti valori:
Codice
01
02
04
06
07
08
09
10
Descrizione
Visa
Mastercard
Maestro
Amex
Diners
JCB
PagoBancomat
Carta Aura
Il campo BPW_TIPO_TRANSAZIONE può assumere i seguenti valori:
Codice
TT01
TT04
TT05
TT06
TT07
TT08
TT09
TT10
Descrizione
SSL
Bankpass Pagobancomat
Bankpass Carte di Credito
VBV
Secure Code
VBV Esercente
Secure Code Esercente
VBV Titolare non autenticato
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 15 di 23
Ad URLMS ed URLDONE verrà appeso un “?” punto interrogativo nel caso in cui non sia già presente.
NOTA BENE: i nomi dei campi sono tutti maiuscoli e case sensitive; non deve essere fatta nessuna assunzione
riguardo l’ordine con il quale i parametri sono passati nelle GET o POST HTTP.
Il campo MAC non viene calcolato nel caso in cui l'esito della transazione sia negativo. Esso viene quindi
valorizzato con la stringa costante "NULL".
Per ulteriori informazioni relative al calcolo e alla verifica del MAC per i messaggi di esito vedere l’appendice C2.
E’ preciso compito del negozio ricalcolare il MAC utilizzando la stringa segreta “esito-API” in suo possesso, e
verificare che esso coincida con quello inserito nel messaggio arrivato. In mancanza di questo processo di
verifica è possibile che il merchant system consideri validi messaggi di conferma non autenticamente spediti dal
PFE ma inviati da terzi.
Nello sviluppo della integrazione si tenga presente che i messaggi HTTP recapitati ad URLDONE, URLMS ed
URLBACK potranno in futuro, grazie all’evoluzione del sistema, presentare parametri aggiuntivi non inizialmente
presenti. Le applicazioni devono quindi ignorare eventuali parametri da loro non riconosciuti senza presentare
malfunzionamenti. Per evitare la sovrapposizione dei nomi dei parametri con quelli già utilizzati dagli esercenti, ogni
eventuale nuovo parametro avrà il prefisso “BPW_“. L’uso di tale prefisso per i nomi dei propri parametri presenti
in URLDONE, URLMS, od URLBACK può precludere la compatibilità dell’integrazione con le future versioni
del sistema.
Nel caso in cui la comunicazione al merchant system tramite URLMS fallisse non sono previsti meccanismi di
ripetizione del messaggio. Il sito ha la possibilità di interrogare il sistema BankPass tramite l'API backoffice per
verificare lo stato di eventuali ordini rimasti in stato "pending" durante la fase di pagamento.
API BackOffice
Per chi volesse integrare il Back Office BANKPASS Web con il proprio applicativo per la gestione delle vendite è
disponibile il manuale con tutte le specifiche API.
Potete richiederlo inviando una mail a [email protected]
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 16 di 23
Appendice
Appendice A (FAQ)
Di seguito alcune domande ricorrenti
Sezione Comune
D: A cosa serve il MAC?
R: Il MAC è una quantità, generata concatenando alcuni parametri e una chiave segreta conosciuta solo da
BANKPASS Web e dal Merchant, permette al Merchant ed a BANKPASS Web di verificare la paternità dei messaggi
scambiati.
D: Come si usa il MAC?
R: Il destinatario del messaggio deve calcolare il MAC (utilizzando la chiave segreta di cui è in possesso e i parametri
che sono richiesti a seconda che si tratti di una richiesta di pagamento o di un messaggio di esito) e verificare che
coincida con il MAC calcolato e spedito, assieme ai parametri stessi, dal mittente. Se i valori coincidono la transazione
proviene effettivamente dai nostri server, in caso contrario è stata in qualche modo contraffatta ed è da considerare non
valida.
D: Come si calcola il MAC?
R: Il MAC viene calcolato effettuando un hash MD5 o SHA-1 (vedi appendice alla documentazione per un elenco di
possibili metodi per calcolare l'hash MD5 o SHA-1) di una stringa che varia a seconda se si sta autenticando una
richiesta di pagamento da inviare a BANKPASS Web o se si stanno verificando degli esiti ricevuti da BANKPASS
Web.
Nel primo caso la stringa è (esempio senza nessun OPTIONS):
NUMORD=<numero
d'ordine>&IDNEGOZIO=<idnegozio(CRN)>&IMPORTO=<importo>&VALUTA=<valuta>&TCONTAB=<
tipo di contabilizzazione>&TAUTOR=<tipo di autorizzazione>&<stringa segreta>
Nel secondo invece è (esempio senza nessun OPTIONS):
NUMORD=<numero d'ordine>&IDNEGOZIO=<identificativo del
merchant(CRN)>&AUT=<numero di
autorizzazione>&IMPORTO=<importo>&VALUTA=<valuta>&IDTRANS=<Id
transazione>&TCONTAB=<tipo contabilizzazione>&TAUTOR=<tipo
autorizzazione>&ESITO=<esito transazione>&<stringa segreta >
In entrambi i casi bisogna porre attenzione che l'ordine in cui i parametri compaiono sia esattamente quello sopra
indicato. In seguito il valore ottenuto viene convertito in Esadecimale.
D: Come posso personalizzare l'interfaccia grafica per il pagamento?
R: E' possibile inserire il logo del merchant. In particolare il logo deve avere una dimensione massima di 140x70 Pixel,
un "peso" massimo di 20Kb e deve essere in formato GIF o JPG.
D: Il cliente non “clicca” su "completa l'acquisto" una volta avvenuta la transazione e il vostro sistema non mi
comunica l’avvenuto pagamento(URLDONE non viene chiamato), come posso fare?
R: BANKPASS invia sempre attraverso l’url “URLMS” al merchant, indipendentemente dalle azioni dell’acquirente,
l’esito della transazione. Potete richiedere che vi vengano comunicate solo le informazioni relative ai pagamenti
autorizzati oppure di tutte le transazioni, sia con esito positivo sia con esito negativo.
Ambiente di TEST
D: Ho impostato correttamente tutti i parametri richiesti, nonostante ciò ricevo un messaggio di "errore parametri errati
o insufficienti", come mai?
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 17 di 23
R1: Verificare di aver passato tutti i parametri obbligatori richiesti (contrassegnati con S nella tabella del messaggio di
avvio)
R2: Il valore dell'importo può essere stato trasmesso in maniera errata, verificare che l'importo sia espresso in
centesimi di Euro, senza alcun tipo di punteggiatura.
R3: Controllare che tutti i campi rispettano la corretta formattazione richiesta
D: Ho impostato correttamente tutti i parametri richiesti, nonostante ciò ricevo un messaggio di "errore di
autenticazione", come mai?
R1: Verificare di aver calcolato il MAC correttamente (in formato esadecimale e con tutti i parametri richiesti)
R2: il MAC potrebbe essere corretto ma i valori passati a BANKPASS non corrispondono a quelli utilizzati per
calcolarlo(esempio: calcolo MAC con NUMORD=123, NUMORD inviato al sistema è: NUMORD=a123)
R3: verificare di aver utilizzato correttamente i codici di collaudo e non quelli reali.
R4: verificare il calcolo del MAC come da risposta alla domanda: "D: Come si calcola il MAC?"
D: Il mio negozio genera correttamente dei numeri d'ordine univoci, nonostante ciò ricevo un messaggio di "numero
d'ordine duplicato", come mai?
R: Durante la fase di test più merchant utilizzano lo stesso identificativo di test e i numeri d'ordine di diversi merchant
vengono tutti archiviati sotto lo stesso identificativo, può succedere quindi che il vostro numero d'ordine sia già stato
utilizzato in precedenza. Nell'ambiente di produzione il problema non si verifica.
D: Stò effettuando dei test e il vostro servizio mi risponde "non riesco ad inviare la pagina", dove sbaglio?
R: Il messaggio in questione viene utilizzato quando nel messaggio di avvio pagamento manca il campo
“PAGE=MASTER” oppure non è stato inserito tutto in maiuscolo.
Ambiente di PRODUZIONE
D: Il mio negozio è stato passato in produzione e ha smesso di funzionare, durante la fase di test tutto funzionava
correttamente, cosa è successo?
R: Quando si effettua il passaggio in produzione è necessario apportare alcune correzioni alla configurazione del
negozio stesso, per prima cosa la pagina cui il sito deve inviare le informazioni diventa https://sisbankpass.ssb.it/bankpass/master/main?PAGE=MASTER, in secondo luogo è necessario sostituire l'identificativo(CRN)
del merchant di test con quello di produzione il quale viene comunicato via posta prioritaria e le chiavi di avvio e esito
anch’esse inviate per posta prioritaria all’indirizzo della sede operativa del Merchant
D: Il mio negozio è stato passato in produzione e ha smesso di funzionare, durante la fase di test tutto funzionava
correttamente, ora mi segnala:”errore di autenticazione, user-ID o Password errate”, cosa è successo?
R: Il MAC calcolato non è corretto, potrebbe dipendere da un errata trascrizione della chiave MAC di avvio oppure
l’IDNEGOZIO non corretto.
D: Sono passato in produzione e non vedo più i loghi per pagare con le carte di credito, cosa è successo?
R: Il convenzionamento con i circuiti non è completato oppure non pervenuto, chiedere alla propria banca di effettuare
le verifiche sullo stato del convenzionamento acquirer.
D: Sono passato in produzione e in alto a sinistra nella pagina di pagamento manca un immagine, cosa è successo?
R: in quello spazio viene inserito il logo del negozio, non è ancora pervenuto o è in fase di caricamento.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 18 di 23
Appendice B (Riferimenti)
Di seguito vengono indicate varie fonti dalla quali è possibile attingere risorse eventualmente utili per l’integrazione in
un merchant system.
SSB S.p.A. non fornisce nessun tipo di garanzia né di supporto relativamente
ai prodotti di terze parti sotto indicati.
Per ottenere l’hash MD5 o l’hash SHA-1 che costituisce il MAC il server PFE utilizza l’oggetto Java MessageDigest
del JDK SUN.
Alcuni moduli (commerciali) per calcolare l’hash MD5 in visual basic sono reperibili agli indirizzi:
http://www.aspencrypt.com/index.html
http://www.hotscripts.com/ASP/Scripts_and_Components/Security_Systems/
http://www.anei.com/aneimd5.asp
http://www.aspin.com/func/search?qry=md5&cat=all&IMAGE1.x=25&IMAGE1.y=7
In PHP3 è disponibile nelle librerie standard la funzione md5 per effettuare il calcolo dell’hash su di una stringa.
Per la definizione dello standard MD5 si può consultare:
http://www.columbia.edu/~ariel/ssleay/rfc1321.html
Per la definizione dello standard SHA-1 si può consultare:
http://csrc.nist.gov/cryptval/shs.html
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 19 di 23
Appendice C Generazione MAC (FLUSSO ACQUISTO)
C1 Generazione del MAC per i messaggi di avvio transazione
Il MAC che deve essere trasmesso allegato ai messaggi di avvio del processo di pagamento viene ottenuto con il
procedimento qui descritto.
Il merchant ed il PFE condividono una stringa segreta di 50 caratteri. Per produrre il MAC dei dati si esegue un hash del
concatenamento tra il testo da firmare e la stringa segreta.
La funzione di hash può essere scelta dall’esercente a piacere fra due algoritmi standard: SHA-1 (detto anche SHA) ed
MD5. Dato che i due algoritmi producono un diverso numeri di bit (160 il primo, 128 il secondo) il sistema è in grado
di riconoscere automaticamente il tipo di funzione utilizzato per la generazione del MAC. Il sito del negozio può variare
a proprio piacimento l’algoritmo utilizzato.
Per i messaggi di avvio transazione, il testo da firmare deve contenere i campi:
•
•
•
•
•
•
•
•
•
NUMORD
IDNEGOZIO
IMPORTO
VALUTA
TCONTAB
TAUTOR
OPTIONS (se presente)
NOME
(se presente per OPTIONS B)
COGNOME (se presente per OPTIONS B)
Il MAC (se OPTIONS non presente) sarà:
MAC = Hash (NUMORD=<idoper>& IDNEGOZIO=<merchantid>&IMPORTO=<importo>
&VALUTA=<valuta>&TCONTAB=<tipo contab>&TAUTOR=<tipo autor>&<stringa segreta avvio> )
Il MAC con OPTIONS=AB e NOME COGNOME presenti sarà:
MAC = Hash (NUMORD=<idoper>& IDNEGOZIO=<merchantid>&IMPORTO=<importo>
&VALUTA=<valuta>&TCONTAB=<tipocontab>&TAUTOR=<tipoautor>&OPTIONS=AB&NOME=<nom>&
COGNOME=<cogn>&<stringa segreta avvio> )
L’ordine con il quale appaiono i campi è ovviamente fondamentale. La stringa segreta da utilizzate è quella
denominata “chiave di avvio”.
Un esempio di tale stringa potrebbe essere:
NUMORD=A4845b2&IDNEGOZIO=123456789012345&IMPORTO=100&VALUTA=978&TCONTAB=I&TAUTOR=D&Absd830923fk32..
Il MAC, essendo il risultato di un hash, per essere trasmesso in HTTP deve essere codificato opportunamente. A tale
scopo si deve utilizzare una conversione in esadecimale.
Il risultato di tale conversione e’ una stringa di 32 caratteri se la funzione di hash usata è MD5. Se invece si è utilizzato
SHA-1 il risultato sarà una stringa di 40 caratteri.
Il MAC non è case sensitive. Lettere maiuscole e minuscole possono essere utilizzate indistintamente.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 20 di 23
C2 Generazione del MAC per il messaggio esito
Il MAC che BankPass allega ai messaggi di esito spediti verso il merchant system viene ottenuto con il procedimento
qui descritto.
Il merchant ed il PFE condividono una stringa segreta di 50 caratteri. Per produrre il MAC dei dati si esegue un hash del
concatenamento tra il testo da firmare ed una stringa segreta. Si noti che il PFE utilizza una stringa segreta diversa da
quella di avvio per calcolare il MAC dei messaggi di esito; questa stringa viene detta chiave di “esito-API” perché viene
utilizzata anche per l’accesso alle API backoffice.
La funzione di hash utilizzata dal sistema per generare il MAC è la medesima che l’esercente ha adottato per la
generazione del MAC del messaggio di avvio. Dato che gli algoritmi SHA-1 ed MD5 producono un diverso numeri di
bit (160 il primo, 128 il secondo) il sistema è in grado di riconoscere automaticamente il tipo di funzione utilizzato per
la generazione del MAC del messaggio di avvio, ed utilizzare a sua volta lo stesso algoritmo per rispondere.
In sostanza se il MAC del messaggio di avvio è calcolato con MD5, anche il MAC dell’esito sarà calcolato con MD5.
Viceversa se il MAC del messaggio di avvio è calcolato con SHA-1, anche il MAC dell’esito sarà calcolato con SHA-1.
Per i messaggi conferma, il testo firmato contiene i campi:
•
•
•
•
•
•
•
•
•
•
•
NUMORD
IDNEGOZIO
AUT (Se l’autorizzazione non è presente, il campo è valorizzato con “NULL”)
IMPORTO
VALUTA
IDTRANS
TCONTAB
TAUTOR
ESITO
BPW_MODPAG (presente perché richiesto tramite OPTIONS A)
BPW_TIPO_TRANSAZIONE (se richiesto tramite OPTIONS E)
Il MAC senza BPW_MODPAG sarà:
MAC = Hash_ ( “ NUMORD =<numero d’ordine>&IDNEGOZIO=<merchant id>&AUT=<numero
autor>&IMPORTO=<importo> &VALUTA=<valuta>&IDTRANS=<id.transazione>&TCONTAB=<tipo
contab>&TAUTOR=<tipo autor>&ESITO=<esito>&<stringa segreta esito-API>” )
L’ordine con il quale appaiono i campi è ovviamente fondamentale. La stringa segreta da utilizzate è quella
denominata “chiave di esito-API”.
Un esempio di tale stringa potrebbe essere:
NUMORD=A4845b2&IDNEGOZIO=123456789012345&AUT=HJ89KR&IMPORTO=100&VALUTA=978&IDTRANS=HK84HL2G&TCONTAB=
I&TAUTOR=I&ESITO=00&Absd830923fk32..
Il MAC, essendo il risultato di un hash, per essere trasmesso in HTTP deve essere codificato opportunamente. A tale
scopo si deve utilizzare una conversione in esadecimale. Il risultato di tale conversione e’ una stringa di 32 caratteri se
la funzione di hash usata è MD5. Se invece si è utilizzato SHA-1 il risultato sarà una stringa di 40 caratteri.
Il MAC non deve essere trattato come case sensitive. Il server PFE utilizza lettere minuscole.
N.B. Se l’esito della transazione è negativo il MAC non sarà calcolato e sarà valorizzato a “NULL”.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 21 di 23
Appendice E parametri TAUTOR, TCONTAB e scenari possibili
Di seguito viene illustrato brevemente il significato dei parametri TAUTOR e TCONTAB in relazione alle possibili
modalità di utilizzo del sistema BankPass
TAUTOR
Autorizzazione immediata I
La modalità di autorizzazione immediata prevede che durante la fase di pagamento online venga immediatamente
inviata la richiesta di autorizzazione ai circuiti internazionali. Una volta conclusa la transazione in modo positivo
l’esercente ha la certezza che quanto dovuto dal cliente è stato “prenotato” dal suo plafond.
Autorizzazione differita D
La modalità di autorizzazione differita prevede che durante la fase di pagamento online le transazioni siano prese in
carico ma non inoltrate ai circuiti (viene comunque effettuato un controllo della validità della carta presso l’issuer).
L’esercente che utilizza questa modalità di accettazione dei pagamenti è in grado, in un secondo tempo, di far elaborare
le richieste di autorizzazione pendenti che lo riguardano. Le richieste di autorizzazione differita possono pervenire a
PIB per un importo inferiore a quello originale; l’esercente può inoltrare una serie di autorizzazioni differite fino a
coprire il totale originale.
TCONTAB
Contabilizzazione immediata I
La modalità di contabilizzazione immediata permette all’esercente di rendere automaticamente contabili tutte le
transazioni autorizzate. Senza un suo intervento, la sera stessa del giorno in cui è avvenuta la transazione, il processor di
front end esegue il clearing in automatico del movimento per l’intero importo autorizzato.
Questa modalità può essere ad esempio utilizzata nel caso in cui si vendano beni/servizi immediatamente fruibili da
parte del compratore (software, musica, servizi online, etc.9).
Contabilizzazione differita D
La modalità di contabilizzazione differita prevede che le operazioni autorizzate debbano essere esplicitamente rese
contabili dall’esercente. Per eseguire l’operazione di contabilizzazione di un movimento l’esercente ha a disposizione
un predeterminato numero di giorni dalla data autorizzazione.
Questa modalità mette a disposizione dell’esercente le seguenti operazioni:
• contabilizzazione totale: un movimento viene reso contabile per l’intero ammontare della cifra autorizzata.
• contabilizzazione parziale: un movimento viene reso contabile per un ammontare inferiore alla cifra
autorizzata; una operazione di contabilizzazione parziale può far riferimento ad un'autorizzazione per la quale
era già stata richiesta una contabilizzazione parziale (split shipment) a patto che non sia scaduto il termine
ultimo di contabilizzazione.
• annullamento: viene annullata una operazione di contabilizzazione eseguita durante la giornata, il movimento è
nuovamente contabilizzabile.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Pag. 22 di 23
Scenari possibili
Di seguito sono riportati alcun possibili scenari di utilizzo del sistema
Funzionalità
Pagamento di beni immateriali (download o servizi)
Meccanismo utilizzabile
Avvio pagamento con autorizzazione immediata
TAUTOR=I, contabilizzazione immediata o differita
Pagamento di beni materiali inscindibili sempre disponibili Avvio pagamento con autorizzazione immediata
TAUTOR=I, contabilizzazione immediata o differita
Pagamento di beni materiali da procurare
Avvio pagamento con autorizzazione differita
(TAUTOR=D) ed 1 richiesta di autorizzazioni successiva
con contabilizzazione immediata
Split shipment (divisione): consegna in più tempi della
merce
Ipotesi:
• Il negozio sa a priori che consegnerà a pezzi
• L’importo totale è noto a priori
Avvio pagamento con autorizzazione differita
(TAUTOR=D) ed N richieste di autorizzazioni successive
con contabilizzazione immediata
Split shipment (divisione): consegna in più tempi della
merce
Ipotesi:
• Il negozio non sapeva a priori di dover consegnare a
rate
• È stata inviata una autorizzazione online per l’intero
importo
In questa situazione si deve eseguire lo split (divisione )
dell'autorizzazione: questa operazione tramuta un ordine
online in uno in differito.
Documento Tecnico per l’Integrazione al
servizio BANKPASS Web - WEB
Dopo l’operazione di split (divisione) si potranno inviare
N richieste di autorizzazione come per una normale
autorizzazione differita
Pag. 23 di 23