Specifiche Tecniche – MAIL ORDER E TELEPHONE ORDER

Procedura di adesione e utilizzo del servizio X-Pay
- Specifiche Tecniche –
MAIL ORDER E TELEPHONE ORDER
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 Key Client S.p.A.
Pag. 1/13
INDICE
1.
GLOSSARIO ............................................................................................................................. 3
2.
SCOPO ....................................................................................................................................... 4
3.
PROCESSO DI PAGAMENTO ............................................................................................. 4
4.
MODALITÀ OPERATIVE E SICUREZZA ......................................................................... 5
5.
MESSAGGI ............................................................................................................................... 6
5.1.
5.2.
5.3.
5.4.
5.5.
6.
UTILIZZO DEL “MAC” (MESSAGE AUTHENTICATION CODE) .......................... 12
6.1.
7.
MESSAGGIO RICHIESTA AUTORIZZAZIONE .............................................................................. 6
ESITO RICHIESTA AUTORIZZAZIONE......................................................................................... 9
DETTAGLIO VALORI TAG “CODICE ESITO”............................................................................. 10
MESSAGGIO DI ESITO TRAMITE E-MAIL .................................................................................. 11
REPORT GIORNALIERO IN FORMATO XML O TXT ................................................................ 11
“MAC” MESSAGGIO DI AVVIO PAGAMENTO ........................................................................... 12
ATTIVAZIONE POS VIRTUALE ...................................................................................... 13
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 2/13
1. Glossario
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
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
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 3/13
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:
1
Acquirente
Server
esercente
5
2
3
4
Sistemi
autorizzativi
POS VIRTUALE
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 4/13
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.
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 5/13
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 è:
https://ecommerce.keyclient.it/ecomm/ecomm/ServletMotoS2S
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 6/13
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 8 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
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
3 caratteri
Formato
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso
scritto da parte di Key Client S.p.A.
Pag. 7/13
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.
mac
SI
Message Code Authentication (vedi capitolo 7.1.)
40 caratteri
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:
https://ecommerce.keyclient.it/ecomm/ecomm/ServletMotoS2S?alias=payment_test_motos2s&importo=001&divisa=EUR&codTran
s=PROVA_010412_10&[email protected]&pan=5255999999999992&scadenza=201206&cv2=123&mac=277ef18458a418
75d5f5664a1e87744220bc7cde&parametro1=XXXXX&parametro2=NNNNN
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in toto o in parte senza il permesso
scritto da parte di Key Client S.p.A.
Pag. 8/13
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>[email protected]</mail>
<scadenza>201206</scadenza>
<pan>9992</pan>
<cv2>***</cv2>
</StoreRequest>
- <StoreResponse>
<tipoCarta>MasterCard</tipoCarta>
<codiceAutorizzazione>TESTOK</codiceAutorizzazione>
<dataOra>2012-04-12T10:07:07</dataOra>
<codiceEsito>0</codiceEsito>
<descrizioneEsito>autorizzazione concessa</descrizioneEsito>
<mac>59c509ab9544a17268c1b5a1b8a2455f</mac>
</StoreResponse>
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 9/13
</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>[email protected]</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
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
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 Key Client S.p.A.
Pag. 10/13
5.4.
Messaggio di 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.
5.5.
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.
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 11/13
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.
6.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=PROVA_010412_10divisa=EURimporto=001esempiodicalcolomac”
allora il campo mac sarà:
mac= HASH SHA(“codTrans=
PROVA_010412_10divisa=EURimporto=001esempiodicalcolomac”)
Il valore ottenuto sarà: "277ef18458a41875d5f5664a1e87744220bc7cde"
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 12/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 e-mail se intende ricevere le notifiche di esito pagamento.
Tutte le informazioni riportate nel presente documento sono confidenziali e non possono essere utilizzate in
toto o in parte senza il permesso scritto da parte di Key Client S.p.A.
Pag. 13/13