COMMERCIO ELETTRONICO Integrazione server to server

Transcript

1 Procedura di adesione e utilizzo del servizio X-Pay - Specifiche Tecniche - COMMERCIO ELETTRONICO Integrazione server to server Versione 1 Data Pag. 1/26

2 INDICE 1. GLOSSARIO SCOPO INTRODUZIONE PROCESSO DI PAGAMENTO MODALITÀ OPERATIVE E SICUREZZA MESSAGGI MESSAGGIO RICHIESTA AUTORIZZAZIONE MESSAGGIO AUTHRES RICHIESTA AUTENTICAZIONE 3D-SECURE MESSAGGIO NOTIFICA ESITO (XML) MESSAGGIO HTTP GET NOTIFICA ESITO MESSAGGIO ESITO TRAMITE REPORT GIORNALIERO IN FORMATO XML O TXT UTILIZZO DEL MAC (MESSAGE AUTHENTICATION CODE) MAC MESSAGGIO DI AVVIO PAGAMENTO MAC MESSAGGIO AUTHRES MAC MESSAGGIO ESITO PAGAMENTO(XML E HTTP) ATTIVAZIONE POS VIRTUALE APPENDICE A FUNZIONAMENTO DEL SERVIZIO 3D SECURE Pag. 2/26

3 1. Glossario 3D-Secure È il nome convenzionale con cui si definiscono i sistemi di protezione anti-frode studiati dai Circuiti Internazionali Visa (Verified by Visa) e MasterCard (MasterCard SecureCode). 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/26

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 in modalità detta Server to Server, gestito tecnicamente da KeyClient SpA. Destinatari del documento sono quindi figure prettamente tecniche. 3. Introduzione Il POS VIRTUALE con la modalità di integrazione Server to Server prevede che l esercente gestisca tramite il proprio negozio virtuale la comunicazione con il titolare, quindi sia la richiesta dei dati della carta di credito che la comunicazione dell esito del pagamento. Il negozio virtuale dell esercente anche con la modalità server to server in presenza di carte abilitate al 3D-Secure deve cedere la navigazione dell utente per la fase d autenticazione del titolare in quanto è gestita interamente dall Issuer che ha emesso la carta di credito. L utilizzo di questa modalità operativa è subordinata all ottenimento della certificazione PCI (Payment Card Industry) DSS (Data Security Standard) da parte dell esercente, questa certificazione è richiesta dai circuiti internazionali per favorire e migliorare la protezione dei dati di titolari di carta. Per ulteriori informazioni si rimanda al sito: 4. Processo di Pagamento Il seguente diagramma riassume le varie fasi in cui è suddiviso il processo di pagamento se l esercente opta per l integrazione tramite messaggi server to server; il processo di pagamento segue fasi differenti se il titolare aderisce o meno al Verified by Visa/SecureCode. Infatti se il titolare ha aderito al protocollo di sicurezza il processo di pagamento comprende la fase d autenticazione (steps da 4 a 7) svolta dall ente emittente della carta di credito (Issuer). Pag. 4/26

5 1 Acquirente 5 Server esercente Issuer 7 POS VIRTUALE 8 Sistemi autorizzativi 1. Definizione dell ordine: l acquirente navigando nel negozio virtuale dell Esercente sceglie il/i prodotto/i da acquistare (riempendo il carrello ), definisce l ordine di acquisto e fornisce all esercente i dati della carta di credito che intende utilizzare per il pagamento. 2. Richiesta di pagamento: l applicazione dell esercente spedisce i dati del pagamento che intende richiedere alla piattaforma POS VIRTUALE inviando tramite una chiamata server to server il messaggio avvio pagamento (cap.6.1.). Il messaggio contiene anche un campo CodTrans che identifica univocamente l ordine. 3. Verifica dell adesione al servizio Verified by Visa/SecureCode: il sistema POS VIRTUALE contatta i circuiti internazionali per verificare se la carta di credito dell acquirente ha aderito o meno ai protocolli di sicurezza. Se l acquirente non si è registrato al servizio, POS VIRTUALE effettua immediatamente il pagamento, quindi il passo successivo sarà lo step 8. Se invece l acquirente aderisce al servizio Verified by Visa/SecureCode, vengono eseguiti gli steps dal 4 al 7. Solo per acquirenti aderenti al Verified by Visa/SecureCode: Pag. 5/26

6 4. Restituzione della pagina di redirezione: POS VIRTUALE non inoltra il pagamento in quanto è subordinato all autenticazione dell acquirente, ma restituisce all esercente il messaggio AuthRes (cap. 6.2.) contenente il codice di una pagina html che, eseguita dal browser dell acquirente, lo redireziona verso l applicazione dell Issuer che deve verificarne l identità. Il processo di pagamento si interrompe quindi per consentire l autenticazione del titolare. 5. Redirezione dell acquirente: l applicazione dell esercente restituisce al browser dell acquirente l html ricevuto da POS VIRTUALE nel messaggio AuthRes. 6. Autenticazione: l acquirente visualizza la pagina dell Issuer in cui gli viene richiesto il dato necessario per la sua autenticazione(es. password). La fase d autenticazione del titolare è gestita interamente dall Issuer che ha emesso la carta di credito. 7. Notifica dell esito dell autenticazione: l applicazione dell Issuer restituisce alla piattaforma POS VIRTUALE l esito della fase d autenticazione. Se l acquirente non è stato in grado d autenticarsi il pagamento non può essere inoltrato, quindi il passo successivo sarà lo step 9; viceversa se l autenticazione si è conclusa positivamente POS VIRTUALE effettuerà il pagamento, quindi il passo successivo sarà lo step Pagamento : POS VIRTUALE effettua il pagamento della transazione inviando la richiesta ai sistemi autorizzativi ed ottenendone la relativa risposta. 9. Notifica dell esito all esercente: POS VIRTUALE comunica l esito della richiesta di pagamento all esercente tramite il messaggio di esito pagamento (Cap e 6.4.). Se la fase di autenticazione non è avvenuta, il messaggio di esito viene inviato in risposta al messaggio di avvio pagamento (transazione sincrona), sulla stessa connessione in cui POS VIRTUALE ha ricevuto la richiesta di pagamento. Viceversa se è avvenuta la fase d autenticazione e quindi il pagamento si è interrotto per attendere l esito di tale fase, il messaggio di esito sarà inviato al termine del pagamento (step8) su iniziativa del POS VIRTUALE tramite una chiamata server to server all URL (urlpost) comunicato dall esercente nel messaggio di apertura ordine. Inoltre in tal caso, al termine del pagamento il POS VIRTUALE redirige il browser del titolare verso il sito dell esercente, all URL (url) comunicato dall esercente nel messaggio di apertura ordine. 10. Notifica dell esito al titolare: l applicativo dell esercente comunica l esito del pagamento all acquirente. Pag. 6/26

7 5. Modalità operative e sicurezza L interazione con il merchant, come già precedentemente accennato, si basa su chiamate server tu server. La sicurezza dei messaggi scambiati è garantita dal Protocollo SSL 128 bit utilizzando certificati Server-side. Il POS VIRTUALE utilizzerà infatti per i propri URL un certificato SSL Server che garantirà la cifratura dei dati; l esercente dovrà a sua volta utilizzare un certificato Server in quanto acquisisce e invia al POS VIRTUALE dai sensibili. Il certificato utilizzato dall esercente deve essere emesso da una delle Certification Authority riconosciute. L esercente è responsabile della custodia del proprio certificato, dei suoi rinnovi e dell inoltro a Key Client entro tempi ragionevoli di eventuali certificati intermedi per consentire l installazione dei certificati rinnovati in sostituzione di quelli scaduti. 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. 6. Messaggi Pag. 7/26

8 6.1. Messaggio richiesta autorizzazione Rappresenta il messaggio di richiesta di un nuovo pagamento che l applicativo dell esercente deve inviare al POS VIRTUALE tramite una chiamata https in GET o POST server to server e deve contenere i campi descritti nella tabella della pagina seguente. L URL da chiamare è: Pag. 8/26

9 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. 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. Non sono ammessi caratteri speciali o riservati e in generale quelli superiori al codice ASCII 127 Da 1 a 30 caratteri mail NO l indirizzo dell acquirente al quale inviare l esito del pagamento fino a 150 caratteri url SI url del merchant verso la quale il POS VIRTUALE indirizza l utente al completamento della transazione passando,in GET, i parametri di risposta con il risultato della transazione. Si veda il capitolo 6.4 Fino a 500 caratteri pan SI Numero della carta di credito Da 14 a 19 caratteri scadenza SI Data di scadenza della carta di credito aaaamm toto o in parte senza il permesso scritto da parte di Keyclient S.p.A. Pag. 9/26

10 NOME Obb. Descrizione Formato cv2 SI Codice CVV2/CVC2 composto da 3 numeri riportato sul retro delle carte di credito VISA, MASTERCARD, MAESTRO, DINERS e JCB. 4DBC composto da 4 numeri riportato sul fronte delle carte AMERICAN EXPRESS. Parametri aggiuntivi NO Possono essere specificati n parametri aggiuntivi che verranno restituiti nei messaggi di esito. Non c è un limite al numero di parametri aggiuntivi ma la lunghezza complessiva della stringa composta dai nomi dei parametri e il loro valore complessivamente non deve superare i 4000 caratteri. urlpost SI url del merchant verso la quale il POS VIRTUALE invia l XML di notifica al completamento della transazione passando, in modalità server to server con metodo POST, i parametri di risposta con l esito della transazione. La notifica a tale url verrà effettuata soltanto in presenza di una procedura asincrona ovvero transazione con carta 3D-Secure. Per quanto riguarda invece le transazioni con carte NO 3D-Secure l XML con l esito del pagamento viene restituito direttamente al chiamante (procedura sincrona). Si veda il capitolo 6.3. Messaggio Notifica esito (XML) 3 o 4 caratteri Fino a 4000 caratteri complessivamente Fino a 500 caratteri mac SI Message Code Authentication (vedi capitolo 7.1.) 40 caratteri NB: i valori ei campi: url e urlpost devono cominciare con o https// ; le porte utilizzate non possono essere diverse da quelle standard: 80 o 443. Per una corretta gestione delle chiamate si ricorda di attenersi agli standard RFC 2396 e RFC 3986 Inoltre, se si indica l urlpost su un indirizzo https, si richieda al servizio di attivazione ([email protected] ) l elenco delle CA supportate. toto o in parte senza il permesso scritto da parte di Keyclient S.p.A. Pag. 10/26

11 Si vedano gli esempi che seguono (riportati per semplicità con metodo GET): richiesta autorizzazione di 1,00 Euro: d7fcbeee2686 richiesta autorizzazione di 12,45 Euro con parametro aggiuntivo: 8acaaea85b0bb029bd74bec963c5452 Dopo aver inviato la richiesta a tale URL, il merchant resta in attesa dell esito di pagamento(cap. 6.3.), che riceverà in modalità sincrona quindi sulla stessa connessione in presenza di carte non aderenti al 3D-secure. Con carte iscritte riceverà in risposta, sempre sulla stessa connessione il messaggio AUTHRES (cap. 6.2.) contenete il codice HTML da stampare sul browser dell utente. toto o in parte senza il permesso scritto da parte di Keyclient S.p.A. Pag. 11/26

12 6.2. Messaggio AUTHRES richiesta autenticazione 3D-Secure Questo messaggio XML viene restituito dal POS VIRTUALE in risposta al messaggio di avvio transazione se il pagamento non può essere inoltrato in quanto deve essere preceduto dalla fase d autenticazione della carta di credito del titolare prevista dai protocolli 3D-Secure. Il messaggio viene inoltrato usando la stessa connessione con cui è stato ricevuto il messaggio avvio transazione, i parametri presenti nel messaggio sono descritti nella seguente tabella. NOME Descrizione Formato TERMINAL_ID Codice identificativo del negozio (valore fisso comunicato da Key Client spa nella fase di attivazione definitiva) an max 8 TRANSACTION_ID codice di identificazione del pagamento passato nel messaggio di avvio transazione. Da 1 a 30 caratteri HTML_CODE Codice HTML da restituire al browser dell utente per reindirizzarlo verso la pagina di autenticazione dell issuer. mac Message Code Authentication (vedi capitolo 7.2.) 40 caratteri -- NB: Il parsing delle risposte XML effettuato non deve essere validante: grazie alla evoluzione del sistema in futuro potranno essere aggiunti ulteriori elementi ai messaggi. Le applicazioni devono ignorare gli elementi sconosciuti senza provocare malfunzionamenti. toto o in parte senza il permesso scritto da parte di Keyclient S.p.A. Pag. 12/26

13 Esempio di XML restituito: <?xml version="1.0" encoding="iso "?> <VPOSRES> <TERMINAL_ID> </TERMINAL_ID> <AUTHRES> <TRANSACTION_ID>ID A</TRANSACTION_ID> <HTML_CODE> <![CDATA[ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" " <html> <head> <title>mdpay default response template for web</title> </head> <body bgcolor="#02014e" OnLoad="OnLoadEvent();" > <form name="downloadform" action=" 3430/3ds/vereqauthid= E6B684F C56644F513D3D" method="post"> <input type="hidden" name="pareq" value="ejxvum1pwjaq/iue79lry9qnhe3qyvxuqtcp38zcglgiy3sdwl+3huo06yd77qx PPXfF17U1Jn4x+d4ajc+mabKVGZTFZCiUlMBhqHExXZqdxoOxTbmtNB3BiCG5QFdk83V WtRqzfHebzLWIeACApIe4MTaJNfQnUAGTCm4EBxUC5UjOcayyjdGKhiykAZIOYb7dV6 09aR669y4A9/Zbr9u2HhOCxAMk1yYWe281rvhYFvqjivm8uF+9J7Onr+Uhjsu0rN/SNnpMJ0 h8bhzzazqd2t0bdcagxsij7pyybtyrnqxlgrpuvz0dwhue6rlqh/jrqddpa6r8pcmvus4v CM2x3lbGZTiCXxsL0+Q6ieH3sECEcvpJOVMgQyFZxIXryKchuSq8e/BDz1s3PsalDKWKJA UKgkkplN9AF/OspRscDUB2tB4g8dWkXy7pV++sf1/iB2NMqeE="> <input type="hidden" name="termurl" value=" <input type="hidden" name="md" value="d6a7882acb6d8d32645da85b381fd3ad.ecdvas"> <!-- To support javascript unaware/disabled browsers --> <noscript> <center>please click the submit button below.<br> <input type="submit" name="submit" value="submit"></center> Pag. 13/26

14 </noscript> </form> <SCRIPT LANGUAGE="Javascript" > <!-- about:blank --> <!-- function OnLoadEvent() { document.downloadform.submit(); } //--> </SCRIPT> </body> </html> ]]> </HTML_CODE> </AUTHRES> <MAC>8617a62856c5e738aaa33427cad26231c </MAC> </VPOSRES> n.b. gli elementi in italico non fanno parte dell html da restituire al browser del titolare, indicano al parser xml di ignorare il contenuto del tag in quanto contiene caratteri specifici del protocollo xml Messaggio Notifica esito (XML) Il POS VIRTUALE fornirà all esercente il risultato del pagamento in 2 modalità differenti a seconda che sia avvenuta o meno la fase d autenticazione precedentemente descritta: Pag. 14/26

15 Fase d autenticazione non avvenuta (carte non aderenti al 3D-secure) Il messaggio XML di esito viene inoltrato usando la stessa connessione con cui è stato ricevuto il messaggio di avvio transazione. Fase d autenticazione avvenuta Il messaggio di esito viene inoltrato dal POS VIRTUALE tramite una chiamata server to server all indirizzo riportato nel campo: urlpost indicato dall esercente nel messaggio di avvio transazione, al termine della fase d autenticazione e del successivo pagamento. Inoltre, quando redirige il browser dell acquirente verso l indirizzo riportato nel campo url (comunicato dall esercente nel messaggio di apertura dell ordine) il POS VIRTUALE inoltra copia dell esito pagamento con un messaggio http GET descritto nel capitolo: 9. L XML contenente l esito del pagamento è composto da due sezioni: - StoreRequest - StoreResponse In StoreRequest sono replicati i campi del messaggio di avvio transazione, con eccezione del campo pan che sarà valorizzato con le sole ultime 4 cifre e del campo cvv2 che sarà sostituito con il carattere: *. In StoreResponse sono presenti i tag descritti nella seguente tabella: Nome campo Descrizione Formato Valori dataora Data e ora della transazione aaaammggthhm mss codiceesito Esito della transazione Da 1 a 3 caratteri Vedi tabella 1 codiceautorizzazion e Codice dell autorizzazione assegnato Da 2 a 6 caratteri tipocarta tipo di carta utilizzato Da 3 a 10 caratteri VISA, MasterCard, Amex, Diners, Jcb descrizioneesito Descrizione esito ottenuto Da 1 a 30 caratteri Vedi tabella 1 ParametriAggiuntivi Possono essere specificati n parametri aggiuntivi che verranno restituiti nei messaggi di esito. Non c è un limite al numero di parametri aggiuntivi ma la lunghezza complessiva della stringa composta Fino a 4000 caratteri complessivament e Pag. 15/26

16 mac dai nomi dei parametri e il loro valore complessivamente non deve superare i 4000 caratteri. Message Code Authentication (vedi capitolo 7.3.) 40 caratteri NB: Il parsing delle risposte XML effettuato non deve essere validante: grazie alla evoluzione del sistema in futuro potranno essere aggiunti ulteriori elementi ai messaggi. Le applicazioni devono ignorare gli elementi sconosciuti senza provocare malfunzionamenti. Tabella codici esito: codiceesito Descrizione Esito 0 Autorizzazione concessa 20 Ordine non presente 103 Autorizzazione negata dall'emittente della carta 104 Errore generico 108 Ordine già registrato 109 Errore tecnico Tabella 1 Di seguito un esempio di XML di risposta per esito positivo: <?xml version="1.0" encoding="utf-8"?> <RootResponse> <StoreRequest> <alias>payment_test-soft</alias> <codtrans>id a</codtrans> <divisa>eur</divisa> <importo>1245</importo> <mail>[email protected]</mail> <scadenza>201506</scadenza> <pan>9992</pan> <cv2>***</cv2> </StoreRequest> <StoreResponse> <tipocarta>mastercard</tipocarta> <codiceautorizzazione>005400</codiceautorizzazione> Pag. 16/26

17 <dataora> t120257</dataora> <codiceesito>0</codiceesito> <descrizioneesito>autorizzazione concessa</descrizioneesito> <ParametriAggiuntivi> <url> <urlpost> <parametro1>valore1</parametro1> </ParametriAggiuntivi> <mac>d01e9a394d331cb427cc8358b1125afdc94ab12d</mac> </StoreResponse> </RootResponse> Di seguito un XML di risposta per esito negativo: <?xml version="1.0" encoding="utf-8"?> <RootResponse> <StoreRequest> <alias>payment_test-soft</alias> <codtrans>id a</codtrans> <divisa>eur</divisa> <importo>1000</importo> <scadenza>201506</scadenza> <pan>9992</pan> <cv2>***</cv2> </StoreRequest> <StoreResponse> <tipocarta/> <codiceautorizzazione/> <dataora/> <codiceesito>103</codiceesito> <descrizioneesito>autorizzazione negata dall'emittente della carta</descrizioneesito> <ParametriAggiuntivi> <url> <urlpost> <parametro1>uno</parametro1> </ParametriAggiuntivi> <mac>3bd2fe91ce63e795b534b4b7123bf91fbeee0e72</mac> </StoreResponse> </RootResponse> Pag. 17/26

18 6.4. Messaggio http GET notifica esito effettuata l autenticazione sul sito dell issuer il browser dell utente viene reindirizzato verso l indirizzo riportato nel campo url, ritornando sul sito del merchant viene notificato l esito del pagamento passando in GET i parametri descritti nella seguente tabella. Nome campo Descrizione Formato Valori importo Importo preso dal messaggio di Da 1 a 9 caratteri richiesta divisa Divisa 3 caratteri EUR session_id identificativo della sessione Fino a 200 caratteri codtrans Codice transazione preso dal Da 2 a 30 caratteri messaggio di richiesta 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 dall emittente della carta di credito $BRAND tipo di carta utilizzato per effettuare il pagamento nome nome di chi ha effettuato il pagamento cognome cognome di chi ha effettuato il pagamento indirizzo di chi ha effettuato il pagamento mac Message Code Authentication (vedi capitolo 7.3.) Da 3 a 10 caratteri Da 1 a 30 caratteri Da 1 a 30 caratteri Da 1 a 150 caratteri 40 caratteri VISA, MasterCard, Amex, Diners, Jcb Pag. 18/26

19 nazionalità 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 eseguito il pagamento. 3 caratteri sono usati i valori della codifica ISO alpha-3 Fino a 19 caratteri YYYYMM NB: Nello sviluppo della integrazione si tenga presente che i messaggio HTTP potrà 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. Pag. 19/26

20 6.5. Messaggio 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 Report giornaliero in formato 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. 7. 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). Pag. 20/26

21 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. E precisa responsabilità del destinatario del messaggio verificare la correttezza del MAC e quindi l autenticità e l integrità dei dati ricevuti. Alla ricezione del messaggio il destinatario deve calcolare il MAC, utilizzando la chiave segreta di cui è in possesso e i parametri che sono necessari a seconda del tipo di messaggio e verificare che coincida con il MAC ricevuto dal mittente. Solo se i 2 valori coincidono il destinatario deve proseguire con l elaborazione del messaggio ricevuto 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=id adivisa=eurimporto=100esempiodicalcolomac allora il campo mac sarà: mac= HASH SHA( codtrans=id adivisa=eurimporto=100esempiodicalcolomac ) Il valore ottenuto sarà: "b1b46a7f201dc30c6ce40b552bd9042be8d39a44" Pag. 21/26

22 7.2. mac messaggio AUTHRES Per il messaggio AUTHRES, il testo da firmare deve contenere i tag e relativo valore per i seguenti campi: TERMINAL_ID TRANSACTION_ID HTML_CODE stringa segreta Il mac sarà calcolato nel seguente modo: mac= HASH SHA(<TERMINAL_ID>valore</TERMINAL_ID><TRANSACTION_ID>valore</TRA NSACTION_ID><HTML_CODE>valore</HTML_CODE>stringa segreta) Un esempio di calolo mac per un messaggio AUTHRES sarà: mac= HASH SHA('<TERMINAL_ID> </TERMINAL_ID> <TRANSACTION_ID>ID A</TRANSACTION_ID> <HTML_CODE> <![CDATA[ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" " <html> <head> <title>mdpay default response template for web</title> </head> <body bgcolor="#02014e" OnLoad="OnLoadEvent();" > <form name="downloadform" action=" /3ds/vereqauthid= F4D48656B D D3D" method="post"> <input type="hidden" name="pareq" value="ejxvuttoajeq/rxcq5hetu2wde0qtobbggij+mi23czdlqw6rcgvt10w1k YPc+bSOXOmsCycteMHa/bOarizdZ292k6ZD7qJFAIz1tUwHy7sTsOndXW5qTTp4R 4FdIahyJkiq7yGzOxupjOdKMYxBtRCWFs3HWvcHi45FRJfJwzLFBMG6BSHKltbLUl KU8IBNQjMZl95d9QsDe+dAezdhy683/YRAhQBoF8S83206lB8KHO9eptMlth+PS9oY RS5vyoen/xMjPz3+wBQzIA881ZTTJrbIaLPcT8JtBo/ZOvYVd+uFp0weJzq5IBt7DM8A RIDfx0Q9HS2MketZBqYnxHYw3ZT2ZARFLzYkNva6OkYXw7liVDDF8KoxDIRCW Pag. 22/26

23 NYBUYxDdDvhKNJFN34IB9lQiilpCRBUyK4Ys0GmljsWgbhwny8aRsBoFiN2uWidv XB+vclfgA8Gam7"> <input type="hidden" name="termurl" value=" <input type="hidden" name="md" value="4e7311c0eef2f0c861d81963b419c637.ecdvas"> <!-- To support javascript unaware/disabled browsers --> <noscript> <center>please click the submit button below.<br> <input type="submit" name="submit" value="submit"></center> </noscript> </form> <SCRIPT LANGUAGE="Javascript" > <!-- about:blank --> <!-- function OnLoadEvent() { document.downloadform.submit(); } //--> </SCRIPT> </body> </html> ]]> </HTML_CODE> esempiodicalcolomac'); Il valore ottenuto sarà: "dc5eb0846af2e77dcca30be5b158a b70" 7.3. mac messaggio esito pagamento(xml e http) Per il messaggio di esito transazione, il testo da firmare deve contenere i campi: codtrans divisa importo codaut (nel esito in XML corrisponde al campo: codiceautorizzazione) Pag. 23/26

24 data (nel esito in XML corrisponde ai valori che precendono il valore T nel campo: dataora) orario (nel esito in XML corrisponde ai valori che seguono il valore T nel campo: dataora) stringa segreta Il mac sarà calcolato nel seguente modo: mac= HASH SHA(codTrans=<valore codtrans>divisa=<valore divisa> importo=<valore importo>codaut=<valore codaut>data=<valore data>orario<valore orario> <chiave segreta) Un esempio di tale stringa potrebbe essere: codtrans=mc9divisa=eurimporto=1codaut=data= orario=161341esempiodi calcolomac allora il campo mac sarà: mac= HASH SHA(codTrans=MC9divisa=EURimporto=1codAut=data= orario=161341ese mpiodicalcolomac) Il valore ottenuto sarà: 9053bd3274c87fc3d810f2f4ecf9fc4f8a28420b 8. Attivazione Pos Virtuale Per l attivazione del servizio, l esercente deve : 1. ricevere da Key Client la chiave da utilizzare per implementare l algoritmo di calcolo del MAC; 2. 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 Pag. 24/26

25 In entrambe queste configurazioni l esercente ha comunque modo di incassare o annullare manualmente le operazioni dal back office prima di questi termini impostati. 3. comunicare il recapito se intende ricevere le notifiche di esito pagamento. Pag. 25/26

26 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. 26/26