Specifiche Tecniche

COMMERCIO ELETTRONICO
Autorizzazione di Pagamenti su Siti Remoti

Versione 4.1

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 1/18

INDICE 1. 2. 3. 4. 5. 6. 7. 7.1. 7.2. 7.3. 8. 8.1. 8.2. 9. GLOSSARIO ............................................................................................................................. 3 SCOPO ....................................................................................................................................... 4 INTRODUZIONE .................................................................................................................... 4 UTILIZZO DA PARTE DELLUTENTE .............................................................................. 4 MODALIT OPERATIVE E SICUREZZA ......................................................................... 4 MESSAGGIO AVVIO PAGAMENTO................................................................................ 6 NOTIFICA DELLESITO ...................................................................................................... 12 ESITO TRAMITE E-MAIL ........................................................................................................... 12 MESSAGGIO DI NOTIFICA ON LINE ( INTERNET E SERVER TO SERVER) ................................... 12 INVIO DI UN FILE XML O TXT ............................................................................................... 14 UTILIZZO DEL MAC (MESSAGE AUTHENTICATION CODE) .............................. 14 MAC MESSAGGIO DI AVVIO PAGAMENTO ............................................................................. 15 MAC MESSAGGIO ESITO PAGAMENTO ................................................................................... 16 ATTIVAZIONE POS VIRTUALE ...................................................................................... 17

APPENDICE A FUNZIONAMENTO DEL SERVIZIO 3D SECURE ................................. 18

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 2/18

1.

Glossario
Istituzione finanziaria che convenziona esercenti per laccettazione di carte di pagamento e/o offre servizi di cash advance (anticipo di contante). Utilizzato per le funzioni di gestione di un negozio: resoconti, elenchi, interrogazioni, disposizioni etc. Operazione che genera gli effetti contabili per una transazione precedentemente autorizzata. Operazione di comunicazione del protocollo http. 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. Protocollo applicativo utilizzato per trasmettere le pagine web. Istituto o banca emittente carte di credito. Codice di autenticazione del messaggio. In questo documento il termine viene utilizzato per indicare il sistema software di gestione di un negozio virtuale. Pi in generale, indica il sito dellesercente/ente interessato nellintegrazione del servizio di pagamenti on-line. Operazione di comunicazione del protocollo HTTP Protocollo per pagamenti sicuri definito da MasterCard Secure Hash Algorithm. Algoritmo per la generazione di hash. (Secure Socket Layer) Protocollo di trasporto standard dei dati ideato da Netscape Communication Operazione di annullamento di unautorizzazione concessa con la restituzione del denaro e/o della disponibilit di spesa al titolare della carta Universal resource locator Verified by Visa - Protocollo per pagamenti sicuri definito da Visa

Acquirer

Back office Contabilizzazione GET Hash http Issuer mac Merchant POST Secure code SHA-1 SSL Storno

URL VBV

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 3/18

2.

Scopo

Il presente documento destinato a chi sviluppa negozi virtuali, e contiene le informazioni tecniche necessarie per effettuare l'integrazione fra il proprio canale di vendita e il POS VIRTUALE gestito da Key Client SpA. Destinatari del documento sono quindi figure prettamente tecniche. Questo manuale non contiene una descrizione vera e propria del servizio, che viene invece riportata allinterno degli appositi documenti.

3.

Introduzione

Il POS VIRTUALE rappresenta una soluzione semplice ed efficace per i pagamenti online tramite Internet. Il POS VIRTUALE si basa su un meccanismo molto semplice: una volta terminata la fase di acquisto sul sito web dellesercente, lutente si reca presso il sito del POS VIRTUALE per effettuare il pagamento di quanto dovuto, e ritorna al negozio con una ricevuta rilasciata dal POS VIRTUALE stesso. A questo punto il negozio dar il via al processo di invio della merce, di fruizione del servizio (download di informazioni, software, etc), o semplicemente a registrare lavvenuto pagamento (donazioni, pagamento fatture, etc).

4.

Utilizzo da parte dellutente

Lutente che decide di acquistare al momento del pagamento viene indirizzato sul server sicuro del POS VIRTUALE, che propone una pagina in cui vengono mostrati linsegna dellesercente/ente, limporto della transazione e lidentificativo della transazione. La pagina web richiede allacquirente i dati della carta di credito con la quale intende effettuare il pagamento. Il sistema effettua quindi il pagamento della transazione inviando la richiesta ai sistemi autorizzativi ed ottenendo la relativa risposta. Nel corso di questa fase, se lacquirente ha aderito ai protocolli di sicurezza Verified by Visa o SecureCode MasterCard, avviene anche lautenticazione del titolare presso il sito dellIssuer. Lesito positivo o negativo della richiesta di pagamento viene comunicato dal POS VIRTUALE con diverse modalit di seguito descritte -, in base alla configurazione concordata con lesercente in fase di configurazione del servizio.

5.

Modalit operative e sicurezza

Linterazione con il merchant, come gi precedentemente accennato, si basa su un meccanismo di delega: una volta che lutente ha terminato la compilazione dellordine, il sito dellesercente fa s che il suo browser si colleghi automaticamente al POS VIRTUALE per accedere al servizio di pagamento on-line, comunicando tutti i dati necessari.
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 4/18

A questo punto il POS VIRTUALE gestisce interamente il colloquio con il cliente relativo alla 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 sito di provenienza. Il sistema gestisce attualmente pagamenti con le carte appartenenti ai seguenti circuiti: Visa/Visa Electron MasterCard American Express Diners Maestro Jcb Il POS VIRTUALE gestisce, con gli acquirer abilitati (VISA, MASTERCARD e MAESTRO), le transazioni con i protocolli 3D Secure (3-Domain Secure) Verified by Visa e MasterCard Secure-Code, che assicurano una maggiore tutela sugli acquisti in Internet in quanto, per poter concludere un pagamento, richiedono lautenticazione del titolare della carta di credito (per i dettagli cfr Appendice A). Per autenticare i messaggi che il POS VIRTUALE e il sito dellesercente si scambiano (avvio ed esito), viene utilizzato un semplice meccanismo di mac (message authentication code). Ladozione del mac obbligatoria in quanto consente, al POS VIRTUALE e al merchant, di verificare che non siano stati manipolati i dati scambiati. Il metodo per calcolare il mac relativo alle richieste di pagamento e agli esiti indicato nel capitolo 8 di questo documento. Lelaborazione dei pagamenti autorizzati ai fini dellaccredito del corrispettivo viene, di norma, compiuto nel giorno lavorativo successivo a quello in cui il pagamento avvenuto. E' facolt del merchant posticipare la data dellaccredito dei movimenti, oppure stornare la transazione di pagamento qualora intervenissero ad esempio problemi logistici. Per facilitare la gestione degli ordini, il POS VIRTUALE mette a disposizione dellesercente lo strumento di Amministrazione on-line, che permette di gestire le attivit amministrative/controllo inerenti il negozio virtuale. Amministrazione on-line infatti unArea Riservata al merchant, all'interno della quale, in modo semplice e rapido, possibile consultare l'archivio dei pagamenti e-commerce oltre a poterne disporre la contabilizzazione o lo storno. I codici di accesso al back office vengono forniti al merchant in fase di attivazione del servizio.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 5/18

6.

MESSAGGIO avvio PAGAMENTO

La URL delle pagine di pagamento messe a disposizione dal VIRTUAL POS, verso la quale dovr essere indirizzato il browser dellutente, : https://ecommerce.keyclient.it/ecomm/ecomm/DispatcherServlet Il primo passo che il merchant deve compiere far generare al browser del cliente un messaggio di avvio del processo di pagamento verso il POS VIRTUALE. Questo pu essere fatto sia con una redirect, o un link, (utilizzando quindi il metodo HTTP GET), sia attraverso linvio di un form con campi nascosti (che pu utilizzare il metodo HTTP POST). Il messaggio di avvio della transazione che arriva al PG dal browser dellutente deve contenere i campi indicati nella tabella seguente.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 6/18

NOME alias

Obb. SI

Descrizione

Formato

Codice identificativo del negozio (valore fisso comunicato da Key Client spa nella fase di attivazione Da 1 a 30 caratteri definitiva) importo da autorizzare espresso in centesimi di euro senza sparatore, i primi 2 numeri a destra Da 1 a 7 caratteri. rappresentano gli euro cent, es.: 5000 corrisponde a 50,00 Il codice della divisa in cui limporto espresso (EUR = Euro) 3 caratteri codice di identificazione del pagamento composto da caratteri alfanumerici, escluso il carattere #. Da 1 a 30 caratteri Il codice devessere univoco per ogni richiesta di autorizzazione, solo in caso di esito negativo dellautorizzazione il merchant pu riproporre la stessa richiesta con medesimo codTrans per altre 2 volte, in fase di configurazione lesercente pu scegliere di diminuire i 3 tentativi. lindirizzo e-mail dellacquirente al quale inviare lesito del pagamento fino a 150 caratteri url del merchant verso la quale il PG indirizza lutente al completamento della transazione Fino a 500 caratteri passando,in GET, i parametri di risposta con il risultato della transazione. Si veda il capitolo 7 Messaggio di notifica on line (solo se le esigenze del merchant richiedono questo tipo di esito) identificativo della sessione Fino a 200 caratteri

importo divisa codTrans

SI SI SI

mail url

NO NO

session_id

NO

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 7/18

NOME url_back

Obb. SI

Descrizione

Formato

url del merchant verso la quale il PG indirizza lutente che decide di annullare la transazione Fino a 200 caratteri durante la fase di pagamento sulla pagina di cassa. lurl verr chiamata accodando i seguenti parametri: Variabile importo divisa codTrans esito Valorizzazione importo da autorizzare EUR codice identificativo del pagamento assegnato dal merchant ANNULLO

languageId

NO

identificativo della lingua che verr visualizzata sulla pagina di cassa; le lingue disponibili sono: Fino a 7 caratteri languageId ITA ENG SPA FRA descrizione Italiano Inglese Spagnolo Francese languageId GER JPN ITA-ENG descrizione Tedesco Giapponese Italiano/Inglese

Se tale campo non viene specificato o viene lasciato vuoto verranno visualizzati i testi
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 8/18

in italiano/inglese NOME urlpost Obb. NO Descrizione Formato

url del merchant verso la quale il PG invia al completamento della transazione passando, in Fino a 500 caratteri modalit server to server on metodo POST, i parametri di risposta con lesito della transazione. Si veda il capitolo 7 Messaggio di notifica on line (solo se le esigenze del merchant richiedono questo tipo di esito

mac

SI

Message Code Authentication (vedi capitolo 8)

40 caratteri

NB: i valori ei campi: url_back, url e urlpost devono cominciare con http:// o https//; le porte utilizzate non possono essere diverse da quelle standard: 80 o 443. Inoltre, se si richiede lurlpost su un indirizzo https, si richieda al servizio di attivazione (mail) lelenco dei certificati supportati dal POS VIRTUALE.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 9/18

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 10/18

Si vedano gli esempi che seguono (riportati per semplificit con metodo get): per farsi autorizzare un pagamento di 50 Euro ci si deve riferire allURL https:// ecommerce.keyclient.it/ecomm/ecomm/DispatcherServlet?alias=valore& importo=5000&divisa=EUR&codTrans=990101-00001&mail=xxx@xxxx.it &url=http://www.xxxxx.it&session_id=xxxxxxxx&mac=yyyy&languageId=ITA per farsi autorizzare un pagamento di 50,12 Euro ci si deve riferire allURL https:// ecommerce.keyclient.it/ecomm/ecomm/DispatcherServlet?alias=valore& importo=5012&divisa=EUR&codTrans=990101-00001&mail=xxx@xxxx.it &url=http://www.xxxxx.it&session_id=xxxxxxxx&mac=yyyy&languageId=ENG Dopo aver rimandato il compratore a tale URL, il merchant resta in attesa dellesito di pagamento, che ricever in modalit da concordare (mail, on line su Internet e/o comunicazione server to server). In caso di esito positivo, il pagamento viene garantito dalle compagnie delle carte di credito, secondo le norme fissate nei documenti contrattuali.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 11/18

7.

Notifica dellesito

Lesercente pu scegliere di configurare la ricezione/visualizzazione dellesito del pagamento da parte del POS VIRTUALE in una o pi delle seguenti modalit: E-Mail: lesercente ricever una mail con i dettagli delle transazioni al recapito mail comunicato in fase di configurazione On-line su internet: lutente, una volta concluso il pagamento, viene reindirizzato direttamente sul sito dellesercente, allindirizzo indicato nel messaggio di avvio pagamento (nome campo url). Lutente quindi ritorna al sito dellesercente portando con s i parametri (si veda cap. 6.2) che attestano la conclusione della transazione On-line server to server: lesercente pu ricevere lesito direttamente dal POS VIRTUALE in modalit server to server. La chiamata contiene gli stessi parametri della modalit precedente, e viene eseguita verso lindirizzo indicato nel messaggio di avvio pagamento (nome campo: urlpost), che attesta la conclusione della transazione (si veda cap. 6.2). 7.1. Esito tramite e-mail

Il merchant riceve una mail con il riferimento dellinsegna del suo negozio e i seguenti parametri: importo, divisa, codice transazione, nome, cognome e indirizzo e-mail di chi ha effettuato il pagamento, tipo di carta utilizzato, esito del pagamento (positivo o negativo), data della transazione, ora della transazione e codice di autorizzazione (questultimo solo se il pagamento ha avuto esito positivo). Il merchant deve comunicare a Key Client lindirizzo e-mail a cui inviare gli esiti dei pagamenti. 7.2. Messaggio di notifica on line ( Internet e server to server)

Lesito delloperazione viene comunicato al merchant tramite due distinti percorsi. Il primo passa dal browser dellutente, il secondo avviene direttamente dal server del POS VIRTUALE verso il negozio. In particolare lesito viene comunicato al merchant utilizzando gli indirizzi indicati nei parametri url e urlpost: se valorizzati, il primo viene contattato - tramite la navigazione del browser dellutente - non appena il circuito autorizzativo risponde alla richiesta inoltrata dal PG; lutilizzo del secondo indirizzo permette al server del POS VIRTUALE di inviare i dati in modalit POST direttamente al server del merchant, avendo cos una buona certezza che lesito della transazione venga comunicato indipendentemente dalle azioni del cliente.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 12/18

Il messaggio di conferma della transazione contiene i parametri riportati nella tabella seguente. Nome campo alias importo divisa session_id codTrans data orario esito codAut $BRAND Descrizione Codice identificativo negozio Importo Divisa identificativo della sessione Codice transazione Data della transazione Ora della transazione Esito della transazione Codice assegnato Formato Da 1 a 30 caratteri Da 1 a 9 caratteri 3 caratteri Fino a caratteri aaaammgg hhmmss 2 caratteri OK o KO 200 EUR Valori

Da 2 a 30 caratteri

dellautorizzazione Da 2 a 6 caratteri Da 3 a 10 caratteri VISA, MasterCard, Amex, Diners, Jcb

tipo di carta utilizzato

nome cognome email mac nazionalita

nome di chi ha effettuato il Da 1 a 30 caratteri pagamento cognome di chi ha effettuato il Da 1 a 30 caratteri pagamento indirizzo e-mail di chi effettuato il pagamento Message Code Authentication ha Da 1 a caratteri 40 caratteri sono usati i valori della codifica ISO 3166-1 alpha-3 150

Dato opzionale, riporta la 3 caratteri nazionalit della carta che ha eseguito il pagamento. Dato opzionale, riporta il Fino a 19 caratteri numero della carta di credito che ha eseguito lacquisto mostrando solo i primi 6 e ultimi 4 digit

Pan

Scadenza_pan Dato opzionale, riporta la data YYYYMM di scadenza della carta che ha eseguito il pagamento.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 13/18

7.3.

Invio di un file XML o TXT

Il POS VIRTUALE, su richiesta dellesercente, pu inviare giornalmente ad uno o pi indirizzi di posta elettronica un file in formato XML o TXT contenente tutte le transazioni di pagamento effettuate sino alla mezzanotte della giornata precedente allinvio. Di seguito si riportano i campi presenti nel report: NumeroOrdine DataUltimaOperazione OraUltimaOperazione Operazione Importo Valuta CodiceAutorizzazione Circuito TipoPagamento Lindirizzo e-mail viene comunicato a in fase di attivazione.

8.

Utilizzo del mac (Message Authentication Code)

Il mac (Message Authentication Code) viene utilizzato per rendere non modificabili i parametri passati tra i due sistemi interessati dal colloquio, Key Client e il merchant. Il metodo seguito per generare il mac il seguente: viene calcolato un hash SHA-1 della stringa risultante dal concatenamento dei parametri indicati per ciascun messaggio, e una stringa segreta (stringa di N byte, condivisa dal POS VIRTUALE e dal singolo merchant). Il destinatario, possedendo la stessa stringa segreta, pu verificare il mac e quindi lautenticit dei parametri ricevuti. 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 40 caratteri.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 14/18

8.1.

mac messaggio di avvio pagamento

Per il messaggio di avvio transazione, il testo da firmare deve contenere i campi: codTrans divisa importo stringa segreta Il mac sar calcolato nel seguente modo: mac= HASH SHA(codTrans=<valore codTrans>divisa=<valore divisa>importo=<valore importo><chiave segreta)

Un esempio di tale stringa potrebbe essere: codTrans=testCILME534divisa=EURimporto=1esempiodicalcolomac allora il campo mac sar: mac= HASH SHA(codTrans=testCILME534divisa=EURimporto=1esempiodicalcolomac) Il valore ottenuto sar: "992e40c00b79ad1a6e4a5a8c61e776e696796a79"

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 15/18

8.2.

mac messaggio esito pagamento

Per il messaggio di esito transazione, il testo da firmare deve contenere i campi: codTrans esito importo divisa data orario codAut stringa segreta Il mac sar calcolato nel seguente modo: mac= HASH SHA(codTrans=<valore codTrans>esito=<valore esito> importo=<valore importo>divisa=<valore divisa>data=<valore data>orario<valore orario>codAut=<valore codAut><chiave segreta) Un esempio di tale stringa potrebbe essere: codTrans=ORD_01esito=OKimporto=10divisa=EURdata=20110616orario=174003cod Aut=TESTOKesempiodicalcolomac

allora il campo mac sar: mac= HASH SHA(codTrans=ORD_01esito=OKimporto=10divisa=EURdata=20110616orario=1740 03codAut=TESTOKesempiodicalcolomac) Il valore ottenuto sar: " d8614a933b63486417245fc313f810068ceb5804"

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 16/18

9.

Attivazione Pos Virtuale

Per lattivazione del servizio, lesercente deve : 1. inviare a Key Client (ecommerce@keyclient.it) n. 1 logo relativo al negozio virtuale di dimensioni h 50 x L 70 pixel e n. 1 logo di dimensioni a scelta; 2. ricevere da Key Client la chiave da utilizzare per implementare lalgoritmo di calcolo del MAC; 3. modificare la modalit standard di gestione ordini. Di norma gli ordini ricevuti vengono incassati giornalmente al termine del giorno solare; per esigenze operative differenti lesercente pu chiedere: lincasso automatico dopo n. giorni dalla data di autorizzazione lannullamento automatico dopo n. giorni dalla data di autorizzazione In entrambe queste configurazioni lesercente ha comunque modo di incassare o annullare manualmente le operazioni dal back office prima di questi termini impostati. 4. comunicare il recapito e-mail se intende ricevere le notifiche di esito pagamento.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 17/18

Appendice A Funzionamento del servizio 3D Secure

Lesercente che aderisce a 3D Secure viene esonerato da qualsiasi responsabilit sulla base delle regole stabilite dai circuiti internazionali. Infatti, se il titolare della carta di credito contesta una spesa, la responsabilit della transazione passa dallacquirer alla societ che ha emesso la carta di credito: un processo denominato liability shift. La liability shift viene applicata secondo le regole Visa e MasterCard riassunte di seguito. Per Visa la liability shift viene applicata nei seguenti due casi: 1) lesercente, la societ che ha emesso la carta, il titolare della carta di credito, aderiscono tutti a 3D Secure (VBV); 2) lesercente aderisce a VBV, ma la societ che ha emesso la carta o il titolare non aderiscono a VBV. Esistono alcune eccezioni a questo secondo caso, per le quali la liability shift non viene applicata. Questo pu succedere per: A) i pagamenti effettuati sui nuovi canali (es. mobile) B) le carte aziendali extraeuropee durante le transazioni internazionali C) le carte anonime prepagate Per MasterCard, la liability shift viene sempre applicata purch lesercente abbia aderito a 3D Secure (MasterCard Secure Code). Esiste una sola eccezione, che riguarda le carte emesse in USA, Canada, Messico, Centro America, Caraibi e Sud America. Per le carte emesse in questi Paesi, affinch la liability shift sia valida, sono necessarie contemporaneamente le tre seguenti condizioni: A) lesercente ha aderito a MasterCard Secure Code B) la societ che ha emesso la carta ha aderito a MasterCard Secure Code C) il titolare della carta di credito si autenticato correttamente Sia per le carte Visa, sia per le carte MasterCard, una volta completata la fase d'autenticazione tramite password, la transazione prosegue secondo il normale processo autorizzativo.

Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso scritto da parte di Key Client S.p.A.

Pag. 18/18