COMMERCIO ELETTRONICO Integrazione Front office web e Front office Mobile

Transcript

1 Procedura di adesione e utilizzo del servizio X-Pay - Specifiche Tecniche - COMMERCIO ELETTRONICO Integrazione Front office web e Front office Mobile Versione 1 Data Pag. 1/18

2 INDICE 1. GLOSSARIO SCOPO INTRODUZIONE UTILIZZO DA PARTE DELL UTENTE MODALITÀ OPERATIVE E SICUREZZA MESSAGGIO AVVIO PAGAMENTO NOTIFICA DELL ESITO ESITO TRAMITE MESSAGGIO DI NOTIFICA ON LINE ( INTERNET E SERVER TO SERVER) INVIO DI UN FILE XML O TXT UTILIZZO DEL MAC (MESSAGE AUTHENTICATION CODE) MAC MESSAGGIO DI AVVIO PAGAMENTO MAC MESSAGGIO ESITO PAGAMENTO ATTIVAZIONE POS VIRTUALE APPENDICE A FUNZIONAMENTO DEL SERVIZIO 3D SECURE Pag. 2/18

3 1. Glossario Acquirer Back office Contabilizzazione GET Hash http Issuer mac Merchant POST Secure code SHA-1 SSL Storno URL VBV Istituzione finanziaria che convenziona esercenti per l accettazione 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 dell esercente/ente interessato nell integrazione 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 un autorizzazione 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 Pag. 3/18

4 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 X-Pay di CartaSi gestito tecnicamente da Key Client SpA. Destinatari del documento sono quindi figure prettamente tecniche. 3. Introduzione Il POS VIRTUALE rappresenta una soluzione semplice ed efficace per i pagamenti tramite Internet (via web o mobile). Il POS VIRTUALE si basa su un meccanismo molto semplice: una volta terminata la fase di acquisto sul sito web/mobile dell esercente, l utente 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 l avvenuto pagamento (donazioni, pagamento fatture, etc). 4. Utilizzo da parte dell utente L utente che decide di acquistare al momento del pagamento viene indirizzato sul server sicuro del POS VIRTUALE, che propone una pagina in cui vengono mostrati l insegna dell esercente/ente, l importo della transazione e l identificativo della transazione. La pagina web/mobile richiede all acquirente 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 l acquirente ha aderito ai protocolli di sicurezza Verified by Visa o SecureCode MasterCard, avviene anche l autenticazione del titolare presso il sito dell Issuer. L esito positivo o negativo della richiesta di pagamento viene comunicato dal POS VIRTUALE con diverse modalità di seguito descritte -, in base alla configurazione concordata con l esercente in fase di configurazione del servizio. 5. Modalità operative e sicurezza L interazione con il merchant, come già precedentemente accennato, si basa su un meccanismo di delega: una volta che l utente ha terminato la compilazione dell ordine, il sito dell esercente 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. Pag. 4/18

5 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 l autenticazione del titolare della carta di credito (per i dettagli cfr Appendice A). Per autenticare i messaggi che il POS VIRTUALE e il sito dell esercente si scambiano (avvio ed esito), viene utilizzato un semplice meccanismo di mac (message authentication code). L adozione 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. L elaborazione dei pagamenti autorizzati ai fini dell accredito del corrispettivo viene, di norma, compiuto nel giorno lavorativo successivo a quello in cui il pagamento è avvenuto. E' facoltà del merchant posticipare la data dell accredito 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 dell esercente lo strumento di Amministrazione on-line, che permette di gestire le attività amministrative/controllo inerenti il negozio virtuale. Amministrazione on-line è infatti un Area 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. Pag. 5/18

6 6. MESSAGGIO avvio PAGAMENTO La URL delle pagine di pagamento messe a disposizione dal VIRTUAL POS, verso la quale dovrà essere indirizzato il browser dell utente, è: 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 l invio 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 dell utente deve contenere i campi indicati nella tabella seguente. Pag. 6/18

7 NOME Obb. Descrizione Formato alias SI Codice identificativo del negozio (valore fisso comunicato da Key Client spa nella fase di attivazione definitiva) importo SI importo da autorizzare espresso in centesimi di euro senza sparatore, i primi 2 numeri a destra rappresentano gli euro cent, es.: 5000 corrisponde a 50,00 Da 1 a 30 caratteri Da 1 a 7 caratteri. divisa SI Il codice della divisa in cui l importo è espresso (EUR = Euro) 3 caratteri codtrans SI codice di identificazione del pagamento composto da caratteri alfanumerici, escluso il carattere #. Il codice dev essere univoco per ogni richiesta di autorizzazione, solo in caso di esito negativo dell autorizzazione il merchant può riproporre la stessa richiesta con medesimo codtrans per altre 2 volte, in fase di configurazione l esercente può scegliere di diminuire i 3 tentativi. Da 1 a 30 caratteri mail NO l indirizzo dell acquirente al quale inviare l esito del pagamento fino a 150 caratteri url NO url del merchant verso la quale il PG indirizza l utente al completamento della transazione 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) Fino a 500 caratteri session_id NO identificativo della sessione Fino a 200 caratteri toto o in parte senza il permesso scritto da parte di Key Client S.p.A. Pag. 7/18

8 NOME Obb. Descrizione Formato url_back SI url del merchant verso la quale il PG indirizza l utente che decide di annullare la transazione durante la fase di pagamento sulla pagina di cassa. l url verrà chiamata accodando i seguenti parametri: Variabile Valorizzazione importo importo da autorizzare divisa codtrans esito 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 200 caratteri Fino a 7 caratteri languageid descrizione languageid descrizione ITA Italiano GER Tedesco ENG Inglese JPN Giapponese SPA Spagnolo ITA-ENG Italiano/Inglese FRA Francese Se tale campo non viene specificato o viene lasciato vuoto verranno visualizzati i testi toto o in parte senza il permesso scritto da parte di Key Client S.p.A. Pag. 8/18

9 in italiano/inglese NOME Obb. Descrizione Formato urlpost NO url del merchant verso la quale il PG invia al completamento della transazione passando, in modalità server to server on metodo POST, i parametri di risposta con l esito della transazione. Si veda il capitolo 7 Messaggio di notifica on line (solo se le esigenze del merchant richiedono questo tipo di esito Fino a 500 caratteri mac SI Message Code Authentication (vedi capitolo 8) 40 caratteri NB: i valori ei campi: url_back, url e urlpost devono cominciare con o https// ; le porte utilizzate non possono essere diverse da quelle standard: 80 o 443. Inoltre, se si richiede l urlpost su un indirizzo https, si richieda al servizio di attivazione (mail) l elenco dei certificati supportati dal POS VIRTUALE. toto o in parte senza il permesso scritto da parte di Key Client S.p.A. Pag. 9/18

10 toto o in parte senza il permesso scritto da parte di Key Client S.p.A. Pag. 10/18

11 Si vedano gli esempi che seguono (riportati per semplificità con metodo get): per farsi autorizzare un pagamento di 50 Euro ci si deve riferire all URL ecommerce.keyclient.it/ecomm/ecomm/dispatcherservlet?alias=valore& &url= per farsi autorizzare un pagamento di 50,12 Euro ci si deve riferire all URL ecommerce.keyclient.it/ecomm/ecomm/dispatcherservlet?alias=valore& &url= Dopo aver rimandato il compratore a tale URL, il merchant resta in attesa dell esito 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. Pag. 11/18

12 7. Notifica dell esito L esercente può scegliere di configurare la ricezione/visualizzazione dell esito del pagamento da parte del POS VIRTUALE in una o più delle seguenti modalità: l esercente riceverà una mail con i dettagli delle transazioni al recapito mail comunicato in fase di configurazione On-line su internet: l utente, una volta concluso il pagamento, viene reindirizzato direttamente sul sito dell esercente, all indirizzo indicato nel messaggio di avvio pagamento (nome campo url ). L utente quindi ritorna al sito dell esercente portando con sé i parametri (si veda cap. 6.2) che attestano la conclusione della transazione On-line server to server: l esercente può ricevere l esito direttamente dal POS VIRTUALE in modalità server to server. La chiamata contiene gli stessi parametri della modalità precedente, e viene eseguita verso l indirizzo indicato nel messaggio di avvio pagamento (nome campo: urlpost ), che attesta la conclusione della transazione (si veda cap. 6.2) Esito tramite Il merchant riceve una mail con il riferimento dell insegna del suo negozio e i seguenti parametri: importo, divisa, codice transazione, nome, cognome e indirizzo 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 (quest ultimo solo se il pagamento ha avuto esito positivo). Il merchant deve comunicare a Key Client l indirizzo a cui inviare gli esiti dei pagamenti Messaggio di notifica on line ( Internet e server to server) L esito dell operazione viene comunicato al merchant tramite due distinti percorsi. Il primo passa dal browser dell utente, il secondo avviene direttamente dal server del POS VIRTUALE verso il negozio. In particolare l esito viene comunicato al merchant utilizzando gli indirizzi indicati nei parametri url e urlpost : se valorizzati, il primo viene contattato - tramite la navigazione del browser dell utente - non appena il circuito autorizzativo risponde alla richiesta inoltrata dal PG; l utilizzo 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 l esito della transazione venga comunicato indipendentemente dalle azioni del cliente. Pag. 12/18

13 Il messaggio di conferma della transazione contiene i parametri riportati nella tabella seguente. Nome campo Descrizione Formato Valori alias Codice identificativo negozio Da 1 a 30 caratteri importo Importo Da 1 a 9 caratteri divisa Divisa 3 caratteri EUR session_id identificativo della sessione Fino a 200 caratteri codtrans Codice transazione Da 2 a 30 caratteri data Data della transazione aaaammgg orario Ora della transazione hhmmss esito Esito della transazione 2 caratteri OK o KO codaut Codice dell autorizzazione Da 2 a 6 caratteri assegnato $BRAND tipo di carta utilizzato Da 3 a 10 caratteri VISA, MasterCard, Amex, Diners, Jcb nome nome di chi ha effettuato il Da 1 a 30 caratteri pagamento cognome cognome di chi ha effettuato il Da 1 a 30 caratteri pagamento indirizzo di chi ha effettuato il pagamento Da 1 a 150 caratteri mac Message Code Authentication 40 caratteri nazionalita Dato opzionale, riporta la nazionalità della carta che ha eseguito il pagamento. pan Dato opzionale, riporta il numero della carta di credito che ha eseguito l acquisto mostrando solo i primi 6 e ultimi 4 digit scadenza_pan Dato opzionale, riporta la data di scadenza della carta che ha 3 caratteri sono usati i valori della codifica ISO alpha-3 Fino a 19 caratteri YYYYMM Pag. 13/18

14 eseguito il pagamento Invio di un file XML o TXT Il POS VIRTUALE, su richiesta dell esercente, 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 all invio. Di seguito si riportano i campi presenti nel report: NumeroOrdine DataUltimaOperazione OraUltimaOperazione Operazione Importo Valuta CodiceAutorizzazione Circuito TipoPagamento L indirizzo 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 l autenticità 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. Pag. 14/18

15 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" Pag. 15/18

16 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= orario=174003cod Aut=TESTOKesempiodicalcolomac allora il campo mac sarà: mac= HASH SHA( codtrans=ord_01esito=okimporto=10divisa=eurdata= orario= codAut=TESTOKesempiodicalcolomac ) Il valore ottenuto sarà: " d8614a933b fc313f810068ceb5804" 9. Attivazione Pos Virtuale Per l attivazione del servizio, l esercente deve : Pag. 16/18

17 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 l algoritmo 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 l esercente può chiedere: l incasso automatico dopo n. giorni dalla data di autorizzazione l annullamento automatico dopo n. giorni dalla data di autorizzazione In entrambe queste configurazioni l esercente ha comunque modo di incassare o annullare manualmente le operazioni dal back office prima di questi termini impostati. 4. comunicare il recapito se intende ricevere le notifiche di esito pagamento. Pag. 17/18

18 Appendice A Funzionamento del servizio 3D Secure L esercente 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 dall acquirer 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) l esercente, la società che ha emesso la carta, il titolare della carta di credito, aderiscono tutti a 3D Secure (VBV); 2) l esercente 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é l esercente 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) l esercente 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. Pag. 18/18