Procedura di adesione e utilizzo del servizio X-Pay
- Specifiche Tecniche -
COMMERCIO ELETTRONICO
Integrazione server to server
Versione 1
Data 04.2012
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 Keyclient S.p.A.
Pag. 1/26
INDICE
1.
GLOSSARIO ............................................................................................................................. 3
2.
SCOPO ....................................................................................................................................... 4
3.
INTRODUZIONE .................................................................................................................... 4
4.
PROCESSO DI PAGAMENTO ............................................................................................. 4
5.
MODALITÀ OPERATIVE E SICUREZZA ......................................................................... 7
6.
MESSAGGI ............................................................................................................................... 7
6.1.
6.2.
6.3.
6.4.
6.5.
6.6.
7.
UTILIZZO DEL “MAC” (MESSAGE AUTHENTICATION CODE) .......................... 20
7.1.
7.2.
7.3.
8.
MESSAGGIO RICHIESTA AUTORIZZAZIONE .............................................................................. 8
MESSAGGIO AUTHRES RICHIESTA AUTENTICAZIONE 3D-SECURE .................................... 12
MESSAGGIO NOTIFICA ESITO (XML) ..................................................................................... 14
MESSAGGIO HTTP GET NOTIFICA ESITO ................................................................................ 18
MESSAGGIO ESITO TRAMITE E-MAIL ....................................................................................... 20
REPORT GIORNALIERO IN FORMATO XML O TXT ................................................................ 20
“MAC” MESSAGGIO DI AVVIO PAGAMENTO ........................................................................... 21
“MAC” MESSAGGIO AUTHRES............................................................................................. 22
“MAC” MESSAGGIO ESITO PAGAMENTO(XML E HTTP) ......................................................... 23
ATTIVAZIONE POS VIRTUALE ...................................................................................... 24
APPENDICE A – FUNZIONAMENTO DEL SERVIZIO 3D SECURE ................................. 26
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 Keyclient S.p.A.
Pag. 2/26
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
Istituzione finanziaria che convenziona esercenti per l’accettazione di
carte di pagamento e/o offre servizi di cash advance (anticipo di
contante).
Back office
Utilizzato per le funzioni di gestione di un negozio: resoconti, elenchi,
interrogazioni, disposizioni etc.
Contabilizzazione
Operazione che genera gli effetti contabili per una transazione
precedentemente autorizzata.
GET
Operazione di comunicazione del protocollo http.
Hash
Insieme di N bit (es. 128, 160) ricavato da una stringa con un
procedimento matematico, in modo che a partire da stringhe diverse
non si abbia mai lo stesso risultato.
http
Protocollo applicativo utilizzato per trasmettere le pagine web.
Issuer
Istituto o banca emittente carte di credito.
mac
Codice di autenticazione del messaggio.
Merchant
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.
POST
Operazione di comunicazione del protocollo HTTP
Secure code
Protocollo per pagamenti sicuri definito da MasterCard
SHA-1
Secure Hash Algorithm. Algoritmo per la generazione di hash.
SSL
(Secure Socket Layer) Protocollo di trasporto standard dei dati ideato da
Netscape Communication
Storno
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
VBV
Verified by Visa - Protocollo per pagamenti sicuri definito da Visa
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 Keyclient S.p.A.
Pag. 3/26
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:
https://www.pcisecuritystandards.org
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).
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 Keyclient S.p.A.
Pag. 4/26
1
Acquirente
Server
esercente
5
10
2
6
4
9
3
Issuer
7
8
POS VIRTUALE
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:
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 Keyclient S.p.A.
Pag. 5/26
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 8.
8.
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. 6.3. 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.
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 Keyclient S.p.A.
Pag. 6/26
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
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 Keyclient S.p.A.
Pag. 7/26
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 è:
https://ecommerce.keyclient.it/ecomm/ecomm/Servlet3DS2S
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 Keyclient S.p.A.
Pag. 8/26
NOME
Obb.
Descrizione
Formato
alias
SI
Codice identificativo del negozio (valore fisso comunicato da Key Client spa nella fase di attivazione Da 1 a 30 caratteri
definitiva)
importo
SI
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 €
divisa
SI
Il codice della divisa in cui l’importo è espresso (EUR = Euro)
codTrans
SI
codice di identificazione del pagamento composto da caratteri alfanumerici. Il codice dev’essere Da 1 a 30 caratteri
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
mail
NO
l’indirizzo e-mail dell’acquirente al quale inviare l’esito del pagamento
url
SI
url del merchant verso la quale il POS VIRTUALE indirizza l’utente al completamento della Fino a 500 caratteri
transazione passando,in GET, i parametri di risposta con il risultato della transazione.
Si veda il capitolo 6.4
pan
SI
Numero della carta di credito
Da 14 a 19 caratteri
scadenza
SI
Data di scadenza della carta di credito
aaaamm
3 caratteri
fino a 150 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 Keyclient S.p.A.
Pag. 9/26
NOME
Obb.
Descrizione
cv2
SI
Codice CVV2/CVC2 composto da 3 numeri riportato sul retro delle carte di credito VISA, 3 o 4 caratteri
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. Fino a 4000 caratteri
Non c’è un limite al numero di parametri aggiuntivi ma la lunghezza complessiva della stringa complessivamente
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 Fino a 500 caratteri
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.
mac
SI
Formato
Messaggio Notifica esito (XML)”
Message Code Authentication (vedi capitolo 7.1.)
40 caratteri
NB: i valori ei campi: “url” e “urlpost” devono cominciare con “http://” 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.
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 Keyclient S.p.A.
Pag. 10/26
)
Si vedano gli esempi che seguono (riportati per semplicità con metodo GET):
richiesta autorizzazione di 1,00 Euro:
https://ecommerce.keyclient.it/ecomm/ecomm/Servlet3DS2S?alias=payment_testsoft&importo=100&divisa=EUR&codTrans=ID000000000025482A&[email protected]&url=http://www.testshoponline.aa/esito_url&urlpost=http://www.testshoponline.aa/esito_urlpost&pan=5255999999999992&scadenza=201506&cv2=123&mac=c3f2b5e07d6e3683578214bcdc93
d7fcbeee2686
richiesta autorizzazione di 12,45 Euro con parametro aggiuntivo:
https://ecommerce.keyclient.it/ecomm/ecomm/Servlet3DS2S?alias=payment_testsoft&importo=1245&divisa=EUR&codTrans=ID000000000025483A&[email protected]&url=http://www.testshoponline.aa/esito_url&urlpost=http://www.testshoponline.aa/esito_urlpost&parametro1=valore1&pan=5255999999999992&scadenza=201506&cv2=123&mac=f1ada7835
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.
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 Keyclient S.p.A.
Pag. 11/26
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 an max 8
attivazione definitiva)
TRANSACTION_ID
codice di identificazione del pagamento passato nel messaggio di avvio transazione.
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.)
Da 1 a 30 caratteri
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.
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 Keyclient S.p.A.
Pag. 12/26
Esempio di XML restituito:
<?xml version="1.0" encoding="ISO-8859-15"?>
<VPOSRES>
<TERMINAL_ID>7182815</TERMINAL_ID>
<AUTHRES>
<TRANSACTION_ID>ID000000000025486A</TRANSACTION_ID>
<HTML_CODE>
<![CDATA[
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>MDpay default response template for web</title>
</head>
<body bgcolor="#02014E" OnLoad="OnLoadEvent();" >
<form name="downloadForm"
action="https://acscartasi.ssb.it:443/pareq/3c39e317333731316334303133313131393630306533
3430/3ds/vereqauthid=31376271324E6B684F325544753350757664706C56644F513D3D"
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="https://svilecommerce.keyclient.it:443/mdpaympi/MerchantServer?msgid=4766030">
<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>
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 Keyclient S.p.A.
Pag. 13/26
</noscript>
</form>
<SCRIPT LANGUAGE="Javascript" >
<!-- about:blank -->
<!-function OnLoadEvent() {
document.downloadForm.submit();
}
//-->
</SCRIPT>
</body>
</html>
]]>
</HTML_CODE>
</AUTHRES>
<MAC>8617a62856c5e738aaa33427cad26231c3732977</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.
6.3.
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:
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 Keyclient S.p.A.
Pag. 14/26
•
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
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
Vedi tabella 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 Keyclient S.p.A.
Pag. 15/26
dai nomi dei parametri e
il loro valore
complessivamente non
deve superare i 4000
caratteri.
mac
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
0
20
103
104
108
109
Descrizione Esito
Autorizzazione concessa
Ordine non presente
Autorizzazione negata dall'emittente della carta
Errore generico
Ordine già registrato
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>ID000000000025483A</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>
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 Keyclient S.p.A.
Pag. 16/26
<dataOra>20120120T120257</dataOra>
<codiceEsito>0</codiceEsito>
<descrizioneEsito>autorizzazione concessa</descrizioneEsito>
<ParametriAggiuntivi>
<mail>[email protected]</mail>
<url>http://www.test-shoponline.aa/esito_url</url>
<urlpost>http://www.test-shoponline.aa/esito_urlpost</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>ID000000000025489A</codTrans>
<divisa>EUR</divisa>
<importo>1000</importo>
<mail>[email protected]</mail>
<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>
<mail>[email protected]</mail>
<url>http://www.keyclient.it</url>
<urlpost>http://www.keyclient.it</urlpost>
<parametro1>uno</parametro1>
</ParametriAggiuntivi>
<mac>3bd2fe91ce63e795b534b4b7123bf91fbeee0e72</mac>
</StoreResponse>
</RootResponse>
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 Keyclient S.p.A.
Pag. 17/26
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
session_id
identificativo della sessione
Fino a
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
codAut
Codice
dell’autorizzazione Da 2 a 6 caratteri
assegnato dall’emittente della
carta di credito
$BRAND
tipo di carta utilizzato
effettuare il pagamento
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
email
indirizzo e-mail di chi
effettuato il pagamento
mac
Message Code Authentication 40 caratteri
(vedi capitolo 7.3.)
EUR
200
OK o KO
per Da 3 a 10 caratteri
ha Da 1
caratteri
a
VISA,
MasterCard,
Amex, Diners, Jcb
150
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 Keyclient S.p.A.
Pag. 18/26
nazionalità
Dato opzionale, riporta la 3 caratteri
nazionalità della carta che ha
eseguito il pagamento.
pan
Dato opzionale, riporta il Fino a 19 caratteri
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 YYYYMM
di scadenza della carta che ha
eseguito il pagamento.
sono usati i valori
della codifica ISO
3166-1 alpha-3
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.
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 Keyclient S.p.A.
Pag. 19/26
6.5.
Messaggio esito tramite e-mail
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 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 (quest’ultimo solo se
il pagamento ha avuto esito positivo).
Il merchant deve comunicare a Key Client l’indirizzo e-mail a cui inviare gli esiti dei
pagamenti.
6.6.
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 e-mail 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).
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 Keyclient S.p.A.
Pag. 20/26
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.
7.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=ID000000000125484Adivisa=EURimporto=100esempiodicalcolomac”
allora il campo mac sarà:
mac= HASH
SHA(“codTrans=ID000000000125484Adivisa=EURimporto=100esempiodicalcolomac
”)
Il valore ottenuto sarà:
"b1b46a7f201dc30c6ce40b552bd9042be8d39a44"
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 Keyclient S.p.A.
Pag. 21/26
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>7182815</TERMINAL_ID>
<TRANSACTION_ID>ID000000000025469A</TRANSACTION_ID>
<HTML_CODE>
<![CDATA[
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>MDpay default response template for web</title>
</head>
<body bgcolor="#02014E" OnLoad="OnLoadEvent();" >
<form name="downloadForm"
action="https://acscartasi.ssb.it:443/pareq/3c63af6a3337313163343031363331313330333
061373130/3ds/vereqauthid=33377337556F4D48656B7659417264576D43654738783551
3D3D"
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
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 Keyclient S.p.A.
Pag. 22/26
NYBUYxDdDvhKNJFN34IB9lQiilpCRBUyK4Ys0GmljsWgbhwny8aRsBoFiN2uWidv
XB+vclfgA8Gam7">
<input type="hidden"
name="TermUrl"
value="https://svilecommerce.keyclient.it:443/mdpaympi/MerchantServer?msgid=4766033">
<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à:
"dc5eb0846af2e77dcca30be5b158a99150712b70"
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)
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 Keyclient S.p.A.
Pag. 23/26
 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=20120202orario=161341esempiodi
calcolomac
allora il campo mac sarà:
mac= HASH
SHA(codTrans=MC9divisa=EURimporto=1codAut=data=20120202orario=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
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 Keyclient S.p.A.
Pag. 24/26
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 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 Keyclient S.p.A.
Pag. 25/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.
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 Keyclient S.p.A.
Pag. 26/26