MAIL ORDER E TELEPHONE ORDER Integrazione server to server

Transcript

1 Procedura di adesione e utilizzo del servizio X-Pay - Specifiche Tecniche MAIL ORDER E TELEPHONE ORDER Integrazione server to server Versione 1 Data Pag. 1/13

2 INDICE 1. GLOSSARIO SCOPO PROCESSO DI PAGAMENTO MODALITÀ OPERATIVE E SICUREZZA MESSAGGI MESSAGGIO RICHIESTA AUTORIZZAZIONE ESITO RICHIESTA AUTORIZZAZIONE DETTAGLIO VALORI TAG CODICE ESITO MESSAGGIO DI ESITO TRAMITE REPORT GIORNALIERO IN FORMATO XML O TXT UTILIZZO DEL MAC (MESSAGE AUTHENTICATION CODE) MAC MESSAGGIO DI AVVIO PAGAMENTO ATTIVAZIONE POS VIRTUALE Pag. 2/13

3 1. Glossario Acquirer Back office Contabilizzazione GET Hash http Issuer mac Merchant POST SHA-1 SSL Storno 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 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 URL Universal resource locator Pag. 3/13

4 2. Scopo Il presente documento descrive le caratteristiche tecniche e il funzionamento del sistema M.O.T.O. (Mail Order Telephone Order) del POS virtuale X-Pay di CartaSi, gestito tecnicamente da Keyclient SpA nella modalità Server to Server ; è quindi destinato a chi desiderasse integrare sul proprio sistema la funzione di richiesta autorizzazione di pagamenti tramite carta di credito, i cui dati siano stati comunicati dal titolare carta al merchant via mail, telefono, ecc Considerato il contenuto, destinatari del documento sono quindi figure prettamente tecniche. 3. Processo di Pagamento Il seguente diagramma riassume le varie fasi in cui è suddiviso il processo di pagamento: Acquirente 1 Server esercente Sistemi autorizzativi 4 POS VIRTUALE Pag. 4/13

5 1) Definizione dell ordine: l acquirente, dopo aver concordato con il merchant il tipo di acquisto e il relativo importo, fornisce al merchant stesso (via mail, telefono, fax) i dati della carta di credito che intende utilizzare per il pagamento. 2) Richiesta di pagamento: il merchant inserisce i dati della carta di credito sul proprio sistema, che spedisce i dati del pagamento alla piattaforma POS VIRTUALE tramite una chiamata server to server (messaggio avvio pagamento, cfr. Cap. 5.1). Il messaggio contiene anche il parametro codtrans che identifica univocamente ciascun ordine. 3) Pagamento: POS VIRTUALE invia la richiesta ai sistemi autorizzativi. 4) Esito richiesta: POS VIRTUALE riceve dai sistemi autorizzativi l esito della richiesta di autorizzazione. 5) Notifica dell esito all esercente: POS VIRTUALE comunica al sistema dell esercente, sulla stessa connessione in cui ha ricevuto la richiesta di pagamento, l esito della richiesta di autorizzazione, tramite il messaggio di esito pagamento (cfr. Cap. 5.2). 6) Notifica dell esito al titolare: se richiesto dall esercente, POS VIRTUALE invia una mail di esito pagamento all esercente stesso e al titolare carta (cfr. Cap. 5.4). 4. 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 dati 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. Pag. 5/13

6 Trattandosi di un convenzionamento di tipo M.O.T.O., POS VIRTUALE non può gestire, con gli acquirer abilitati (VISA, MASTERCARD e MAESTRO), le transazioni con i protocolli 3D Secure (3-Domain Secure) Verified by Visa e MasterCard SecureCode. Per autenticare i messaggi che il POS VIRTUALE e il sito dell esercente si scambiano (avvio ed esito), viene utilizzato un meccanismo di mac (message authentication code). L adozione del mac è obbligatoria in quanto consente, al POS VIRTUALE e al merchant, di accertare che i dati scambiati non siano stati manipolati. Il metodo per calcolare il mac relativo alle richieste di pagamento e agli esiti è indicato nel Capitolo 6 di questo documento. L elaborazione dei pagamenti autorizzati ai fini dell accredito del corrispettivo viene, di norma, compiuta nel giorno lavorativo successivo a quello in cui il pagamento è avvenuto. E' facoltà del merchant chiedere a Key Client di posticipare la data dell elaborazione dei movimenti, riservandosi di effettuare egli stesso la conferma tramite il back office a sua disposizione, oppure stornare sempre tramite il back office la transazione di pagamento qualora intervenissero ad esempio problemi per la fornitura del bene o del servizio acquistato dal titolare carta. Per facilitare la gestione degli ordini, POS VIRTUALE mette a disposizione dell esercente appunto lo strumento di back office, denominato Amministrazione on-line, che permette di gestire le attività amministrative e di controllo dei pagamenti virtuali. 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. Il merchant può a sua volta creare altri utenti per l accesso al back office, anche con poteri differenziati tra loro. Per informazioni complete si rimanda alla Guida Utente disponibile sulla home page del back office. 5. Messaggi 5.1. Messaggio richiesta autorizzazione Rappresenta il messaggio di richiesta autorizzazione 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. Il messaggio deve contenere i campi descritti nella tabella della pagina seguente. L URL da invocare è: Pag. 6/13

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 8 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 pan SI Numero della carta di credito Da 14 a 19 caratteri scadenza SI Data di scadenza della carta di credito aaaamm NOME Obb. Descrizione Formato toto o in parte senza il permesso scritto da parte di Key Client S.p.A. Pag. 7/13

8 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. 3 o 4 caratteri mac SI Message Code Authentication (vedi capitolo 7.1.) 40 caratteri Fino a 4000 caratteri complessivamente Per una corretta gestione delle chiamate si ricorda di attenersi agli standard RFC 2396 e RFC 3986 Riportiamo di seguito un esempio di chiamata in modalità GET: s=prova_010412_10&mail=mail@titolarecarta.it&pan= &scadenza=201206&cv2=123&mac=277ef18458a418 75d5f5664a1e bc7cde&parametro1=XXXXX&parametro2=NNNNN toto o in parte senza il permesso scritto da parte di Key Client S.p.A. Pag. 8/13

9 5.2. Esito richiesta autorizzazione Il server KeyClient, ricevuti i dati, esegue la verifica della presenza di tutti i campi e la validità degli stessi. In caso di esito positivo, invia la richiesta di autorizzazione all emittente della carta (o gestore della autorizzazioni in sua vece) attraverso i circuiti internazionali e resta in attesa di risposta. Alla ricezione della risposta restituisce un XML composto da due sezioni: - StoreRequest - StoreReponse In StoreRequest sono replicati i campi di chiamata, con eccezione del campo pan che sarà valorizzato con le sole ultime 4 cifre e del campo cvv2 che sarà valorizzato con *** In StoreResponse sono presenti i seguenti tag: tipocarta: Tipologia di carta utilizzata codiceautorizzazione: codice di autorizzazione dell emittente della carta, valorizzato solo in caso di esito positivo dataora: data/ora del pagamento, valorizzato solo in caso di esito positivo codiceesito: 0 per esito positivo, maggiore di 0 (tre cifre) per esito negativo descrizione Esito: descrizione dell esito ParametriAggiuntivi: Parametri utili all applicazione del merchant per una più corretta gestione interna. mac: Quantità di sicurezza calcolata secondo quando specificato nel capitolo 6. Di seguito un esempio di XML di risposta per esito positivo: - <RootResponse> - <StoreRequest> <alias>payment_test_motos2s</alias> <codtrans>prova_010412_10</codtrans> <divisa>eur</divisa> <importo>001</importo> <mail>mail@titolarecarta.it</mail> <scadenza>201206</scadenza> <pan>9992</pan> <cv2>***</cv2> </StoreRequest> - <StoreResponse> <tipocarta>mastercard</tipocarta> <codiceautorizzazione>testok</codiceautorizzazione> <dataora> t10:07:07</dataora> <codiceesito>0</codiceesito> <descrizioneesito>autorizzazione concessa</descrizioneesito> <mac>59c509ab9544a17268c1b5a1b8a2455f</mac> </StoreResponse> Pag. 9/13

10 </RootResponse> e un XML di risposta per esito negativo: - <RootResponse> - <StoreRequest> <alias>payment_test_motos2s</alias> <codtrans>prova_010412_20</codtrans> <divisa>eur</divisa> <importo>100</importo> <mail>mail@titolarecarta.it</mail> <scadenza>201206</scadenza> <pan>9992</pan> <cv2>***</cv2> </StoreRequest> - <StoreResponse> <tipocarta /> <codiceautorizzazione /> <dataora /> <codiceesito>103</codiceesito> <descrizioneesito>autorizzazione negata dall'emittente della carta</descrizioneesito> <mac>bf7bd76743dc3f5dca9d6b1393abe1c9</mac> </StoreResponse> </RootResponse> 5.3. Dettaglio valori tag codice Esito codice Esito 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 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. Pag. 10/13

11 5.4. Messaggio di 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. Pag. 11/13

12 6. 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. 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=prova_010412_10divisa=eurimporto=001esempiodicalcolomac allora il campo mac sarà: mac= HASH SHA( codtrans= PROVA_010412_10divisa=EURimporto=001esempiodicalcolomac ) Il valore ottenuto sarà: "277ef18458a41875d5f5664a1e bc7cde" Pag. 12/13

13 7. Attivazione Pos Virtuale Per l attivazione del servizio, l esercente: 1. deve ricevere da Key Client la chiave da utilizzare per implementare l algoritmo di calcolo del MAC; 2. può 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. 3. comunicare il recapito se intende ricevere le notifiche di esito pagamento. Pag. 13/13