PagOnline

Gateway di pagamento
PagOnline
Carte di Credito
Allegato Tecnico Ver. 2.5.0
Data
Autore
Descrizione Modifiche
Versione
06/06/2003
Staff e-comm.
Nuova versione del sito. Nuove modalità di
dialogo con il sito dell’esercente: parametri
inserimento ordine, risposta pagine ok e ko,
parametri messaggi di stato, risposta comandi
remoti. Nuovi stati ordine
V2.0.0
28/07/2003
Staff e-comm.
Aggiunta gestione back office di utenze
aggiuntive, rispetto all’amministratore di
esercente
V2.0.1
23/09/2003
Staff e-comm.
Aggiunta sezione istruzioni e loghi per esercente
V2.0.2
01/10/2003
Staff e-comm.
Aggiunta sezione calcolo MAC
V2.0.3
16/10/2003
Staff e-comm.
Aggiunto software client MacPoster nativo
windows
V2.0.4
28/04/2004
Staff e.comm.
Aggiunta funzione moto inserimento ordine.
Visualizzazione brand carta di credito.
V2.1.0
29/03/2005
Staff e-comm.
Gestione logo negozio dell’esercente. ID
autorizzazione nell’event listener. Gestione
CVV2. Migliorate performance
V2.2.0
05/05/2006
Staff e-comm.
Migliorate performance del prodotto. Nuovo
client di accesso dal negozio virtuale
V2.3.0
10/01/2008
Staff e-comm.
Aggiunta gestione Rimborso degli ordini (refund)
Nuova API di rimborso
V2.4.0
26/01/2011
Staff e-comm.
Distinzione utenza accesso al backoffice e utenza
per interfacciamento (Colloquio tra il Payment
Gateway e Merchant: messaggi di stato)
V2.4.0
01/02/2012
Staff e-comm
Aggiornamento dei comandi server to server
V2.5.0
PagOnline
Allegato Tecnico
Indice generale
................................................................................................................................................1
1. Definizioni...........................................................................................................................3
2. Overview............................................................................................................................ 3
3. Gestione del merchant....................................................................................................... 4
4. Dati di test per simulazione acquisto................................................................................. 4
5. Colloquio tra il merchant e il Payment Gateway................................................................ 5
5.1. Parametri obbligatori...................................................................................................6
5.2. Parametri facoltativi.................................................................................................... 7
6. Colloquio tra il Payment Gateway e il merchant................................................................ 7
6.1. Stati dell'ordine........................................................................................................... 8
6.2. Parametri opzionali................................................................................................... 12
7. Modalità e istruzioni per il calcolo del MAC..................................................................... 13
7.1. Chiamata al gateway di pagamento per inserire una richiesta di pagamento.........14
7.2. Chiamata del gateway di pagamento sulle URL dedicate all'event listening...........15
8. Backoffice ........................................................................................................................16
8.1 Operazioni di gestione .............................................................................................. 16
8.2 Operazioni di monitoraggio .......................................................................................16
8.3 Operazioni di configurazione..................................................................................... 16
9. Comandi eseguibili in modalità server to server (API) ....................................................17
9.1 Interfaccia di chiamata (API) .................................................................................... 17
9.2 Parametri di input comuni ......................................................................................... 18
10. API comandi .................................................................................................................. 19
10.1 Comando CONFIRM .............................................................................................. 19
10.2 Comando CANCEL .................................................................................................20
10.3 Comando ORDER_STATE ..................................................................................... 21
10.4 Comando SEND_STATE ........................................................................................ 22
10.5 Comando REFUND_CARD .................................................................................... 23
10.7 Comando DAILY_REPORT .................................................................................... 24
2
PagOnline
Allegato Tecnico
1. Definizioni
Termine
Significato
Merchant
Persona giuridica amministratrice del negozio virtuale.
Esercente
Vedi merchant
Payment Gateway
Piattaforma informativa per effettuare pagamenti via Internet
POS Virtuale
Gateway di pagamento per permettere di acquistare beni o servizi via Internet
ISP
Fornitore del servizio informativo per il negozio virtuale
Backoffice
Pannello di controllo, accessibile previa autenticazione, per la gestione del POS
virtuale
Event listener
Pagina in ascolto sul server del ISP che riceve, in modalità asincrona, i cambiamenti
di stato degli ordini
MAC
Message code authentication - codice utilizzato per autenticare un messaggio digitale
MD5
Message Digest algorithm 5 - algoritmo crittografico - standard RFC 1321
Tabella 1: Glossario termini utili
2. Overview
PagOnline è il sistema di pagamento elettronico UniCredit che permette di effettuare pagamenti di
beni/servizi acquistati via Internet con l'utilizzo di carte di credito.
L'applicazione è facilmente interfacciabile con qualsiasi sito di commercio elettronico attraverso
protocolli standard.
3
PagOnline
Allegato Tecnico
3. Gestione del merchant
Il merchant che aderisce a PagOnline, riceverà una UserID ed una Password con cui accedere al
proprio backoffice raggiungibile all'indirizzo https://pagamenti.unicredito.it/.
Durante il primo accesso viene chiesto al merchant di cambiare la password temporanea e di
completare i propri dati anagrafici; attraverso l'area di backoffice il merchant potrà gestire
interamente il sistema di pagamento del proprio negozio virtuale. Potrà ad esempio visualizzare e
stornare ordini, configurare interfacce di listening e stringa di sicurezza, profilare utenti ecc. ..
Per permettere di effettuare dei test di comunicazione tra il sistema informativo del merchant e
PagOnline o per accedere al backoffice viene messo a disposizione un account di test:
Login
9999888
Password
9999888
Con questo account è possibile configurare e testare l'intero funzionamento di PagOnline sia per
quanto concerne l'interfaccia tra il negozio virtuale e PagOnline sia per le funzionalità di backoffice.
4. Dati di test per simulazione acquisto
Per consentire all'esercente di simulare il processo di pagamento testando il funzionamento del
servizio del proprio sito di e-commerce attraverso l'utenza di test è possibile utilizzare i dati della
carta di test a seguire. Tutti i tentativi di pagamento sull'utenza di test dovranno avere importi
inferiori a € 100,00.
Parametro
Valore
Titolare carta
Nome a piacere
Tipo di carta
VISA
PAN della carta
4444499922200000
CVV2
111
Data scadenza
11/2019
Tabella 2: Dati della carta di test
Gli ordini effettuati con carta di prova non potranno mai essere contabilizzati e quindi non
potranno mai raggiungere lo stato "contabilizzato." Inoltre i tentativi di pagamento effettuati con la
carta di prova, nel caso dell'ambiente di produzione, daranno sempre esito negativo.
Se si volesse testare un pagamento con esito positivo fuori dall'ambiente di test, sarà necessario
utilizzare una carta di credito reale e successivamente stornare l'importo autorizzato attraverso
l'area di backoffice.
4
PagOnline
Allegato Tecnico
5. Colloquio tra il merchant e il Payment Gateway
Il merchant deve predisporre un'interfaccia web sul proprio sistema informativo che permetta al
cliente di accedere al gateway di pagamento PagOnline per concludere l'acquisto del bene o
servizio.
La comunicazione tra l'ISP ed il servizio di pagamento avviene con l'invio di parametri che
riguardano l'ordine da pagare (identificativo ordine, importo, causale, valuta ecc.), i dati del
merchant e infine il parametro crittografico di sicurezza (MAC - che certifica i dati di passaggio).
Importante: è consigliato evitare di far coincidere l'utenza di accesso a backoffice con l'utenza
utilizzata per colloquiare con PagOnline durante la transazione. Questo eviterà che, a seguito di
un blocco dell'utenza di amministrazione per l'accesso a backoffice, non ne consegua un blocco
dell'operatività nei pagamenti.
Generazione dell'utenza dedicata alle transazioni:
1. Nell'area di backoffice selezionare dal menù la voce Configurazione e successivamente
Gestione utenti, infine cliccare sul pulsante Aggiungi
2. Compilare i campi nome utente, password e conferma password. Deselezionare la casella
Cambio password
3. Dal riquadro Permessi utente selezionare esclusivamente la casella Inserimento ordini
4. Dal riquadro Stabilimenti associati selezionare tutti gli stabilimenti
5. Cliccare sul pulsante Conferma
Nelle tabelle di seguito vengono riportati i parametri obbligatori e facoltativi del protocollo di
comunicazione tra il merchant e PagOnline che dovranno essere spediti con metodo GET al
seguente indirizzo:
https://pagamenti.unicredito.it/initInsert.do
Per ragioni di sicurezza si consiglia di non far transitare i dati dell’ordine in modalità client/server
ma richiamare PagOnline attraverso un http client in modalità server to server.
PagOnline restituirà il codice HTML da mostrare al client che permetterà al cliente di proseguire
nella transazione senza poter avere accesso alle informazioni del merchant.
5
PagOnline
Allegato Tecnico
5.1. Parametri obbligatori
Nome
Tipo
Descrizione
Valori consentiti
numeroCommerciante
Numerico
Codice identificativo del merchant
userID
Alfanumerico
Nome utente per l'accesso al sistema di
pagamento
password
Alfanumerico
Password per l'accesso al sistema di
pagamento
numeroOrdine
Alfanumerico
Codice identificativo dell'ordine
totaleOrdine
Numerico
Importo espresso come numero intero. Le
ultime due cifre rappresentano i decimali
valuta
Numerico
Codice ISO valuta (solo EURO)
flagDeposito
Alfanumerico
Modalità di deposito automatico o manuale Y = autodeposito,
N = manuale
urlOk
Alfanumerico
Indirizzo dell'esercente a cui verrà
reindirizzato il compratore in
caso di transazione con esito positivo
urlKo
Alfanumerico
Indirizzo dell'esercente a cui verrà
reindirizzato il compratore in
caso di transazione con esito negativo
tipoRispostaApv
Alfanumerico
Modalità manuale o automatica per
reindirizzare il cliente da
PagOnline verso il sito dell'esercente
click, wait
flagRiciclaOrdine
Alfanumerico
Indica se si intende riutilizzare un
identificativo ordine che fa
riferimento ad un precedente ordine
abbandonato
Y = ricicla,
N = non riciclare
stabilimento
Numerico
Codice identificativo del punto vendita
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
978
Tabella 3: Parametri obbligatori per la procedura di inserimento ordine
Importante: nel caso si utilizzi il parametro flagDeposito=N, l'ordine rimarrà preautorizzato 30
giorni di calendario per il pagamento con carta di credito.
6
PagOnline
Allegato Tecnico
5.2. Parametri facoltativi
Nome
Tipo
Descrizione
Valori consentiti
tipoPagamento
Alfanumerico
Metodo di pagamento scelto
CartCred
causalePagamento
Alfanumerico
Descrizione della transazione
Max. 90 caratteri
emailCompratore
Alfanumerico
Email del cliente a cui inoltrare l'esito della
transazione
langCompratore
Alfanumerico
Lingua del compratore
it, en, de, fr, es
Tabella 4: Parametri facoltativi per la procedura di inserimento ordine
Importante: per autenticare i dati passati dal sistema informativo del merchant a PagOnline, è
necessario calcolare un MAC che permetta di autorizzare i dati e la provenienza della chiamata.
Il calcolo del MAC verrà descritto nel capitolo 8 "Modalità e istruzioni per il calcolo del MAC."
6. Colloquio tra il Payment Gateway e il merchant
Il sistema Payment Gateway PagOnline tiene aggiornato il merchant sugli sviluppi di un pagamento
tramite messaggi http asincroni.
In altre parole l'esercente deve configurare almeno un URL del proprio server –attraverso la
funzionalità interna all'area di backoffice– per ricevere messaggi (tale URL è detto event listener:
ascoltatore di eventi di stato dell'ordine) con lo stato attuale e precedente di un generico pagamento
ad ogni cambiamento dello stato stesso.
L'esercente può indicare infatti da 1 a n event listener e gli URL specificati utilizzano il protocollo
http, i parametri vengono inviati con metodo GET. Tra i parametri inviati con l'evento c'è
nuovamente il MAC a garanzia che sia il sistema di pagamenti stesso ad aver inviato il messaggio
all'esercente. La modalità di calcolo di questo MAC segue la stessa regola del calcolo di quello
inviato nella richiesta inserimento ordine: "tutto ciò che si riceve a sinistra del MAC è stato
utilizzato per il calcolo del MAC stesso;" questa è la ragione per cui si utilizza il GET in invio, per
non perdere l'ordine dei parametri.
Questi messaggi vengono mandati come parametro proprio all'URL segnalata dal commerciante (o
dal provider internet che gestisce il sito del commerciante).
I messaggi di stato inviati alle listener sono di due tipi:
7
•
automatico, indica il cambio di stato di un ordine nel sistema e viene inviato in
corrispondenza di ogni evento che crea una modifica di stato nell'ordine
•
su richiesta, viene richiesto con invocazione remota (v. sez. 10.4) o tramite backoffice
dall'esercente, oppure invocato a seguito dell'esecuzione dei comandi di storno e
contabilizzazione richiesti sul sistema.
PagOnline
Allegato Tecnico
Esempi di possibili stringhe di parametri inviati dal sistema al commerciante sono di seguito
riportate (si osservino attentamente le modifiche introdotte rispetto alla versione 1.x.x del software);
si veda oltre la tabella dei possibili stati, il diagramma di flusso seguente.
6.1. Stati dell'ordine
Valore
Descrizione
Tipo
ON
ordine inserito nuovo
intermedio
RO
ordine inserito richiesto
intermedio
IN
ordine inserito in attesa di input del cliente
intermedio
AR
ordine in attesa di risposta dal circuito autorizzativo
intermedio
OK
ordine autorizzato e in attesa di conferma
importante
KO
ordine non autorizzato
definitivo
IC
ordine confermato
importante
CO
ordine contabilizzato
importante
AB
ordine abbandonato
definitivo
ST
ordine stornato (nei limiti indicati nella sez. 10.2 - comando CANCEL)
definitivo
EX
ordine scaduto (dopo i limiti indicati nella sez. 10.2 - comando CANCEL)
definitivo
IP
ordine in rimborso parziale
intermedio
IT
ordine in rimborso totale
intermedio
CP
ordine rimborsato parzialmente
definitivo
CT
ordine rimborsato totalmente
definitivo
RC
rimborso cancellato
definitivo
Tabella 5: Stati raggiungibili da un ordine e codice di stato corrispondente
A seguire una spiegazione per gli stati ordine considerati importanti:
8
•
statoattuale=OK: la richiesta di autorizzazione del pagamento –con deposito differito– ha
avuto esito positivo
•
statoattuale=IC: il deposito del pagamento –a seguito della richiesta di autorizzazione con
autodeposito o a seguito della conferma di un deposito differito– ha avuto esito positivo
•
statoattuale=KO: la richiesta di autorizzazione del pagamento ha avuto esito negativo
PagOnline
Illustrazione 1: Diagramma degli stati dell'ordine
9
Allegato Tecnico
PagOnline
Allegato Tecnico
Ordine richiesto:
TIMECREATED=21.09.2010+20%3A30%3A18&statoattuale=RO&PREVIOUSSTATE=ON&CURRENTSTATE=RO&ti
pomessaggio=PAYMENT_STATE&DESCRIZIONE=CAMBIO+DI+STATO&datacreazione=21.09.2010+20%3A30%
3A18&stabilimento=99988&MerchantNumber=9999888&descrizione=CAMBIO+DI+STATO&OBJECT=PAYME
NT&TIMEGENERATED=21.09.2010+20%3A30%3A18&MERCHANTNUMBER=9999888&statoprecedente=ON&MERC
HANTACCOUNT=999988801&numeroOrdine=acquistibenza20101209556743&numeroCommerciante=99998
88&datagenerazione=21.09.2010+20%3A30%3A18&ORDERNUMBER=acquistibenza20101209556743&Stab
ilimento=99988&mac=2d4lntO9Q%2FXRYtzNhC5Iqg%3D%3D&MAC=QDBIyW90z221ZuHfZWQtow%3D%3D
Ordine inserito:
TIMECREATED=21.09.2010+20%3A30%3A18&statoattuale=IN&PREVIOUSSTATE=RO&CURRENTSTATE=IN&ti
pomessaggio=PAYMENT_STATE&DESCRIZIONE=CAMBIO+DI+STATO&datacreazione=21.09.2010+20%3A30%
3A18&stabilimento=99988&MerchantNumber=999988&descrizione=CAMBIO+DI+STATO&OBJECT=PAYMEN
T&TIMEGENERATED=21.09.2010+20%3A30%3A18&MERCHANTNUMBER=9999888&statoprecedente=RO&MERCH
ANTACCOUNT=999988801&numeroOrdine=acquistibenza20101209556743&numeroCommerciante=999988
8&datagenerazione=21.09.2010+20%3A30%3A18&ORDERNUMBER=acquistibenza20101209556743&Stabi
limento=99988&mac=Nj4eOUgkTfxPdEhx43KXaQ%3D%3D&MAC=0liynw9HveEjKX1+V%2F5tog%3D%3D
In particolare a ogni listener del merchant vengono sempre inviati i seguenti parametri di default:
Nome
Tipo
Descrizione
tipomessaggio
Alfanumerico Tipo oggetto
datacreazione
Alfanumerico Ora di invio del messaggio
numeroCommerciante
Numerico
Numero esercente
stabilimento
Numerico
Stabilimento esercente
numeroOrdine
Alfanumerico Numero ordine
statoprecedente
Alfanumerico Stato ordine precedente
statoattuale
Alfanumerico Stato ordine attuale
descrizione
Alfanumerico Descrizione del messaggio
mac
Alfanumerico Codice di sicurezza
Tabella 6: Parametri fissi inviati alle interfacce di listening
Caso 1. messaggi di stato automatici
•
Il parametro tipomessaggio assume il valore "PAYMENT_STATE"
•
Il parametro descrizione assume il valore "CAMBIO DI STATO"
Caso 2. messaggi di stato su richiesta
10
•
Il parametro tipomessaggio assume il valore "PAYMENT_STATE"
•
Il parametro statoprecedente assume il valore "indefinito"
PagOnline
•
Allegato Tecnico
Il parametro descrizione può assumere i seguenti valori:
a) nel caso di invocazione a seguito dell'esecuzione dei comandi, contiene la descrizione
dell'esecuzione del comando
b) nel caso di invocazione da remoto da parte del merchant, contiene il parametro
descrizione inviato dal merchant o –se non presente– la scritta ”Richiesta remota
dell'esercente”
c) nel caso di invocazione dal backoffice da parte del merchant, contiene il parametro
descrizione specificato nella form o –se non presente– la scritta "Richiesta da backoffice
dell'esercente"
Si osservi come quando viene richiesto l'invio dell'evento al listener riguardante un ID ordine che
non è presente nel sistema, viene generato un evento con i parametri valorizzati nel seguente modo:
•
identificazione del merchant: numero e stabilimento specificati nella richiesta
•
numeroOrdine=uello
•
tipomessaggio=PAYMENT_STATE
•
statoattuale=ordine_non_trovato
•
mac,
•
gli altri parametri che normalmente vengono inviati con l'evento, conterranno il valore
"indefinito" tipico dei parametri non valorizzabili
specificato nella richiesta
valorizzato come al solito
Se viene poi effettuata una richiesta di invio di un evento senza specificare un valore per il
parametro descrizione, vengono impostati i seguenti valori di default:
a) se la richiesta è avvenuta tramite una chiamata remota, descrizione=Richiesta remota
b) dell'esercente se la richiesta è avvenuta tramite il backoffice, descrizione=Richiesta da
backoffice dell'esercente
c) se la richiesta è avvenuta a seguito di un cambio di stato del pagamento,
descrizione=CAMBIO DI STATO
11
PagOnline
Allegato Tecnico
6.2. Parametri opzionali
Nome
Tipo
Descrizione
Valori ammessi
tipoPagamento
Alfanumerico Tipologia di pagamento utilizzata CartCred
importototale
Alfanumerico Importo totale
Residuoapprovazione
Numerico
Residuo di approvazione
totaledepositato
Numerico
Importo depositato
expvaluta
Numerico
Esponente valuta (decimali)
datamodifica
Alfanumerico Data ultima modifica pagamento
valuta
Numerico
Codice ISO valuta
-2
978
Tabella 7: Parametri opzionali inviati alle interfacce di listening
Importante: Si osservi che, come ogni altra applicazione web, non può essere garantita una vera
funzionalità transazionale: può succedere che per i motivi più disparati tali messaggi non
giungano all'esercente (problemi in rete internet, server temporaneamente fuori servizio, utente
che chiude il browser, crash di sistema), pur essendo previsto un meccanismo per effettuare
multipli tentativi di invio a front di un errore.
Per tale ragione è prevista una modalità "on demand," che si va a sommare alla possibilità dei
messaggi su richiesta ed è del tutto analoga da parte del merchant, per interrogare il sistema
gateway di pagamento al fine di reperire lo stato attuale di quegli ordini che siano rimasti per un
tempo ragionevolmente troppo lungo (e.g. più di 20 minuti) in stato "pendente" come per esempio
ordini richiesti o inseriti di cui non si è ricevuto un messaggio finale di
abbandono/approvazione/rifiuto, in attesa dell'esito finale del pagamento. Tale funzionalità è
illustrata nella sezione 10.3, sotto il nome di comando ORDER_STATE.
L'area di backoffice viene acceduta tramite maschera di login utilizzando userID e password; è
quindi possibile scegliere tra varie operazioni (e gestire eventuali stabilimenti multipli) tra cui
quelle per la gestione degli event listener e dei parametri aggiuntivi da spedire alle URL come
spiegazioni fornite in questo stesso capitolo.
12
PagOnline
Allegato Tecnico
7. Modalità e istruzioni per il calcolo del MAC
Al fine di esemplificare meglio quanto già verificabile tramite lettura ed osservazione degli esempi
in diversi linguaggi (presenti sulla pagina https://pagamenti.unicredito.it/backoffice/software.html),
si illustrano di seguito le modalità di calcolo della firma digitale nei diversi casi di comunicazione
ed invio dati tra il gateway di pagamento e il server del merchant e viceversa. Le seguenti istruzioni
si riveleranno particolarmente utili a coloro che utilizzano JAVA come linguaggio di
programmazione.
Il calcolo del MAC è un meccanismo che permette il reciproco riconoscimento tra due attori
durante lo scambio di informazioni in rete, tramite l'applicazione di un algoritmo di firma digitale
MD5 che sfrutta un'informazione conosciuta solamente dagli attori stessi.
Supponendo che l'attore A debba inviare alcuni dati all'attore B, nella forma 'Chiave=Valore', egli
unisce alla stringa creata tramite concatenazione di tali dati (separati come da standard RFC Web
dal carattere &, e mantenendo un preciso ordine dei dati stessi) una stringa di cinquanta caratteri
conosciuta solamente da esso e dalla sua controparte attore B (chiameremo questa stringa stringa
segreta). A tale stringa ottenuta è applicata una firma MD5, dalla quale si ottiene una nuova stringa
che rappresenta il MAC di tale transazione.
Il seguente esempio illustra l'invio di parametri secondo la procedura appena illustrata:
Illustrazione 2: Scambio di informazioni di tra due attori mediante l'invio di firma digitale
MAC
Ammettiamo che l'attore A debba spedire i due valori chiave1=valore1 e chiave2=valore2. Egli
creerà la stringa chiave1=valore1&chiave2=valore2 alla quale andrà ad aggiungere la stringa
segreta ottenendo il seguente risultato:
chiave1=valore1&chiave2=valore2&StringaSegreta
Su tale risultato applicherà la firma digitale da cui ottenere il risultato finale da spedire in rete
accodato ai valori.
Si noti che nulla impedisce di calcolare il MAC solamente su una parte dei dati spediti in rete, e che
l'attore potrebbe spedire i dati in rete in ordine diverso da quello usato per il calcolo del MAC, che è
pure un vincolo conosciuto solamente dalle due parti. Al momento della verifica, ovviamente, si
dovrà fare il calcolo del MAC con i parametri nell'ordine originale.
Per maggiore completezza si illustra di seguito un esempio di codice per calcolare la firma MD5
con linguaggio JAVA; in rete è possibile trovare librerie di calcolo MD5 per molti altri linguaggi e
le modalità da seguire saranno le stesse.
13
PagOnline
Allegato Tecnico
Ipotizzando di avere i seguenti parametri noti:
•
sInputString: una stringa da maccare
•
sSecretString: una stringa segreta di 50
caratteri conosciuta solo dalle due parti
allora il frammento di codice JAVA per il calcolo sarà:
import org.apache.commons.codec.digest.DigestUtils;
import org.apache.commons.codec.binary.Base64;
String sStringToDigest = InputString + "&" + sSecretString;
byte[] bMac = DigestUtils.md5 (sStringToDigest.getBytes());
String sMacEncoded = Base64.encodeBase64String (bMac);
sMacEncoded = sMacEncoded.substring (0,24);
Esaminato da un punto di vista teorico cosa si intenda per calcolo del MAC, veniamo ora ad
illustrare le modalità di inserimento di tale algoritmo all'interno dei protocolli di comunicazione del
servizio di gateway di pagamento.
7.1. Chiamata al gateway di pagamento per inserire una richiesta di pagamento
I parametri da inviare al gateway di pagamento (vedi cap. 5) con metodo GET per assicurarsi che
vengano inviati con il medesimo ordine di calcolo del MAC stesso, devono essere accodati uno
all'altro nell'ordine esatto riportato di seguito:
Parametri obbligatori:
numeroCommerciante, userID, password, numeroOrdine, totaleOrdine, valuta, flagDeposito,
urlOk, urlKo, tipoRispostaApv, flagRiciclaOrdine, stabilimento
Parametri facoltativi:
tipoPagamento, emailNotifica, langCompratore, causalePagamento
Durante l'invio verso PagOnline, i parametri facoltativi, eventualmente, devono essere accodati
dopo il parametro MAC. Per esempio se si dovesse inviare la richiesta con i seguenti dati:
numeroCommerciante=9999888
userID=9999888
password=9999888
numeroOrdine=VERXORDXPROD196
totaleOrdine=1
valuta=978
flagDeposito=Y
urlOk=http://www.dominio.it/ok.html
urlKo=http://www.dominio.it/ko.html
tipoRispostaApv=click
flagRiciclaOrdine=N
stabilimento=99888
osservando l'ordine dei parametri, si deve preparare la stringa:
14
PagOnline
Allegato Tecnico
numeroCommerciante=9999888&userID=9999888&password=9999888&numeroOrdine=VERXORDXPROD196
&totaleOrdine=1&valuta=978&flagDeposito=Y&urlOk=http://www.dominio.it/ok.html&urlKo=htt
p://www.dominio.it/ko.html&tipoRispostaApv=click&flagRiciclaOrdine=N&stabilimento=99888
a questa stringa preparata va aggiunta la secret string di 50 caratteri e su ciò che si ottiene va
calcolato il MAC, ovvero va calcolato su (ipotizzando una secret string del tipo “ b1“ x 25 ):
numeroCommerciante=9999888&userID=9999888&password=9999888&numeroOrdine=VERXORDXPROD196
&totaleOrdine=1&valuta=978&flagDeposito=Y&urlOk=http://www.dominio.it/ok.html&urlKo=htt
p://www.dominio.it/ko.html&tipoRispostaApv=click&flagRiciclaOrdine=N&stabilimento=99888
&b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1
ricavando un valore per il MAC. Finalmente è possibile inviare in GET quanto ottenuto, ovvero:
numeroCommerciante=9999888&userID=9999888&password=PASSWORD+FINTA&numeroOrdine=VERXORDX
PRO D196&totaleOrdine=1&valuta=978&flagDeposito=Y&urlOk=http%3A%2F%2Fwww.dominio.it
%2Fok.html& urlKo=http%3A%2F%2Fwww.dominio.it
%2Fko.html&tipoRispostaApv=click&flagRiciclaOrdine=N&stabilimento=99888&mac=8k2BZRtnVaM
qHAPx0CPUTQ%3D%3D
E' importante notare che i valori devono essere URL encoded prima di essere spediti verso
PagOnline.
Si osservi inoltre, fatto importante, come non sia necessario (anzi vivamente sconsigliato!) inviare il
valore esatto della password dell'utente (che verrà invece rimpiazzata dal sistema in ricezione, per la
verifica), evitando di inviare in rete dati sensibili dell'utente.
7.2. Chiamata del gateway di pagamento sulle URL dedicate all'event listening
Questi casi ricadono nella regola precedentemente menzionata: "tutto ciò che si trova a sinistra del
MAC è stato utilizzato per il calcolo del MAC stesso," per decidere quale stringa utilizzare.
Se ad esempio si ricevesse un messaggio al proprio url di stato ordini del tipo:
statoattuale=RO&tipomessaggio=PAYMENT_STATE&totaledepositato=indefinito&datacreazione=3
0.0 9.2003 11:21:16&stabilimento=99888&merchantNumber=9999888&descrizione=CAMBIO DI
STATO&valuta=978&importototale=100&mac=2fUXqBwCln1gtA8DZP/aqA==&importototale=1&statopr
ecedente=ON
Tutto ciò che è a sinistra del MAC, unito alla stringa segreta (su cui quindi calcolare il MAC da
verificare) sarebbe quindi:
statoattuale=RO&tipomessaggio=PAYMENT_STATE&totaledepositato=indefinito&datacreazione=3
0.0 9.2003 11:21:16&stabilimento=99888&merchantNumber=9999888&descrizione=CAMBIO DI
STATO&valuta=978&importototale=100&b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1b1
Su questa stringa si calcolerà il MAC.
15
PagOnline
Allegato Tecnico
8. Backoffice
Il backoffice è un applicativo gestionale via Web che consente al merchant di configurare, gestire,
monitorare il proprio gateway di pagamento.
Previa autenticazione, collegandosi all'URL: https://pagamenti.unicredito.it/backoffice/index.html,
il merchant potrà effettuare operazioni sotto elencate.
Per gli approfondimenti sulle funzionalità si rimanda all'help presente nelle pagine del backoffice.
8.1 Operazioni di gestione
•
Controllo Stato di un ordine
•
Conferma di un ordine (sfruttabile in caso di deposito differito)
•
Storno di un ordine
•
Rimborso di un ordine
8.2 Operazioni di monitoraggio
Ricerca ordini con vari filtri, tra cui:
•
Data ordine
•
Numero Ordine
•
Stato contabilizzazione
•
Ordinamento per data, totale, ragione sociale
•
Totali degli ordini con vari filtri, tra cui:
◦ Valuta
◦ Tipo Pagamento
◦ Intervallo totali (giornaliero, mensile, annuale, globale)
•
Visualizzazione delle carte di credito abilitate
8.3 Operazioni di configurazione
16
•
Gestione (lettura/modifica) stringa di firma digitale per il collegamento merchant/sistema di
pagamento
•
Cambio Password dell'utente
•
Gestione degli event listener di stato pagamenti (inserimento, modifica, cancellazione,
personalizzazione parametri)
•
Gestione logo azienda
PagOnline
Allegato Tecnico
•
Gestione di utenze aggiuntive a quella assegnata di default all'adesione al servizio, con
permessi solo su alcuni stabilimenti
•
Gestione anagrafica esercente/ISP (in fase di primo accesso obbligatoriamente verrà chiesto
il cambio password e –in via facoltativa– l'inserimento di dati anagrafici che verrà
riproposto ad ogni accesso fintantoché non verrà completato l'inserimento dati ritenuti di
una certa importanza)
9. Comandi eseguibili in modalità server to server (API)
Alcune funzionalità, oltre ad essere usufruibili da backoffice, possono essere utilizzate attraverso
comandi in modalità server to server. In altre parole, l'applicazione del merchant o dell'ISP potrà
interfacciarsi con PagOnline in modalità asincrona, automatizzando così il colloqui tra i due sistemi.
Le funzionalità eseguibili via API sono le seguenti:
Comando
Descrizione
CONFIRM
Conferma un ordine depositato
CANCEL
Storna un ordine depositato o in contabilizzazione
ORDER_STATE
Fornisce lo stato di un ordine
SEND_STATE
Richiede l'invio di un messaggio di stato sulle interfacce di listening
REFUND_CARD
Effettua un rimborso per un pagamento effettuato con carta di credito
DAILY_REPORT
Fornisce la lista di ordini contabilizzati o rimborsati per un dato giorno
Tabella 8: Comandi eseguibili server-side
9.1 Interfaccia di chiamata (API)
Le API sono chiamabili tramite delle richieste a URL presenti sul gateway di pagamento UniCredit.
in particolare sono accessibili su host tramite l'interfaccia:
https://pagamenti.unicredito.it/backoffice/servizi/execute_remote_command.do
La comunicazione tra il server del merchant e PagOnline deve avvenire attraverso protocollo sicuro
HTTPS. Oltre ai parametri che identificano il merchant, lo stabilimento e quelli funzionali al
comando, deve essere inviato il MAC che ha lo scopo di garantire l'integrità dei dati. Per il calcolo
del MAC si rimanda al capitolo 7.
Le specifiche sul formato dei parametri sono le seguenti:
17
•
valori dei parametri URL encoded
•
modalità di invio dei parametri GET
PagOnline
Allegato Tecnico
9.2 Parametri di input comuni
Ogni chiamata deve contenere obbligatoriamente i seguenti parametri di identificazione del
merchant:
Nome
Tipo
Descrizione
Valori consentiti
numeroCommerciante
Numerico
Codice identificativo del merchant
stabilimento
Numerico
Numero identificativo dello
stabilimento del merchant
userID
Alfanumerico
Nome utente per l'accesso al sistema di
pagamento
password
Alfanumerico
Password per l'accesso al sistema di
pagamento
tipoComando
Alfanumerico
Comando eseguibile
Vedi tab. 8
formatoRisposta
Alfanumerico
Tipo di formato della risposta
xml, plaintext
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
Tabella 9: Parametri comuni a tutti i comandi server to server
La risposta della chiamata alle API è del tipo xml o plaintext (simile ad una querystring http
chiave1=valore1&chiave2=valore2...) e consiste di informazioni riguardo l'andamento del comando
stesso.
Nel caso di un comando che preveda solo una conferma positiva o meno dell'esecuzione e non
richieda un ritorno di dati, un esempio potrebbe essere quello a seguire:
<?xml version="1.0" ?>
<remotecommand>
<commandname>CONFIRM</commandname>
<respcode>002</respcode>
<description>Comando fallito. Ordine in stato non depositabile</description>
</remotecommand>
oppure con formato plaintext, per un comando fallito:
DESCRIZIONE=Comando fallito. Ordine in stato non depositabile&SRC=002&PRC=002
Per alcuni comandi, di cui si renda necessaria una risposta di tipo ok o ko, verrà restituita in xml la
variabile respcode e SRC in formato plain text, con i seguenti valori:
•
000: esito positivo
•
<>000: esito negativo
Per alcuni comandi i record presenti nella risposta sono più d'uno indicando così una risposta
composta da più valori, come ad esempio il comando ORDER_STATE che torna i valori degli ordini
ricercati.
18
PagOnline
Allegato Tecnico
10. API comandi
10.1 Comando CONFIRM
Con questo comando è possibile eseguire l'operazione di deposito di un ordine precedentemente
autorizzato, ed è ammessa solo per gli ordini in stato approvato (OK), quindi inseriti con
flagDeposito=N ed entro il periodo di 30 giorni di calendario.
Una volta confermato, l'ordine passa da stato OK a stato IC. Nel caso invece non venga confermato
entro i 30 giorni, l'ordine viene messo in stato scaduto (EX). Durante il periodo in cui l'ordine è
approvato il plafond della carta resta bloccato .
Nome
Tipo
Descrizione
Valori consentiti
numeroCommerciante
Numerico
Codice identificativo del merchant
stabilimento
Numerico
Numero identificativo dello
stabilimento del merchant
userID
Alfanumerico
Nome utente per l'accesso al sistema di
pagamento
password
Alfanumerico
Password per l'accesso al sistema di
pagamento
tipoComando
Alfanumerico
Comandi eseguibili
CONFIRM
formatoRisposta
Alfanumerico
Tipo di formato della risposta
xml, plaintext
numeroOrdine
Alfanumerico
Numero dell'ordine di cui depositare il
pagamento
totaleOrdine
Numerico
Importo da depositare
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
Tabella 10: Parametri obbligatori per l'invio del comando CONFIRM
Risposta xml
<?xml version="1.0" ?>
<remotecommand>
<commandname>CONFIRM</commandname>
<respcode>0</respcode>
<description>Comando eseguito con successo</description>
</remotecommand>
Risposta plaintext
DESCRIZIONE=Comando eseguito con successo&SRC=000&PRC=000
19
Interi in formato
standard ISO
PagOnline
Allegato Tecnico
10.2 Comando CANCEL
Con questo comando è possibile stornare il pagamento di un ordine. Esistono due tipologie di
storno:
• storno di un ordine approvato e depositato
• storno di un ordine solo approvato
Limiti di tempo per le chiamate:
• storno di un ordine approvato e depositato (da effettuarsi entro le ore 23:59)
• annullo di un ordine solo approvato (da effettuarsi entro 30 giorni di calendario)
Nome
Tipo
Descrizione
Valori consentiti
numeroCommerciante
Numerico
Codice identificativo del merchant
stabilimento
Numerico
Numero identificativo dello
stabilimento del merchant
userID
Alfanumerico
Nome utente per l'accesso al sistema di
pagamento
password
Alfanumerico
Password per l'accesso al sistema di
pagamento
tipoComando
Alfanumerico
Comandi eseguibili
CANCEL
formatoRisposta
Alfanumerico
Tipo di formato della risposta
xml, plaintext
numeroOrdine
Alfanumerico
Numero dell'ordine di cui stornare il
pagamento
totaleOrdine
Numerico
Importo da stornare
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
Tabella 11: Parametri obbligatori per l'invio del comando CANCEL
Risposta xml
<?xml version="1.0" ?>
<remotecommand>
<commandname>CANCEL</commandname>
<respcode>0</respcode>
<description>Comando eseguito con successo</description>
</remotecommand>
Risposta plaintext
DESCRIZIONE=Comando eseguito con successo&SRC=000&PRC=000
20
Interi in formato
standard ISO
PagOnline
Allegato Tecnico
10.3 Comando ORDER_STATE
Con questo comando è possibile richiedere lo stato di uno solo ordine per volta. Come risposta a
questo comando si ottiene un tracciato xml o plaintext con lo stato dell'ordine.
Il comando è utile se si vuole conoscere la situazione di un ordine pendente in tempi
ragionevolmente brevi.
Importante: Per essere certi del consolidamento degli stati di un ordine, è necessario utilizzare
questa funzionalità riferendosi a ordini effettuati almeno 4 ore e 10 minuti prima.
Nome
Tipo
Descrizione
Valori consentiti
numeroCommerciante
Numerico
Codice identificativo del merchant
stabilimento
Numerico
Numero identificativo dello
stabilimento del merchant
userID
Alfanumerico
Nome utente per l'accesso al sistema di
pagamento
password
Alfanumerico
Password per l'accesso al sistema di
pagamento
tipoComando
Alfanumerico
Comandi eseguibili
ORDER_STATE
formatoRisposta
Alfanumerico
Tipo di formato della risposta
xml, plaintext
numeroOrdine
Alfanumerico
Numero dell'ordine di cui ricercare il
pagamento
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
Tabella 12: Parametri obbligatori per l'invio del comando ORDER_STATE
Risposta xml
<xml version="1.0" ?>
<remotecommand>
<commandname>ORDER_STATE</commandname>
<orderdata>
<orderid>1</orderid>
<datacreazione>2003-03-27 15:00:35.178884</datacreazione>
<datamodifica>2003-03-31 14:59:38.969971</datamodifica>
<totale>1000</totale>
<stato>KO</stato>
</orderdata>
</remotecommand>
Risposta plaintext
PAYMENTTYPE=CartCred&AMOUNT=100&DEPOSITAMOUNT=100&OBJECT=PAYMENT&TIMEMODIFIED=25.04.200
9+00%3A05&STATE=EX&ORDERNUMBER=1&CURRENCY=978&APPROVEAMOUNT=100&TIMECREATED=25.03.2009+
16%3A38&AMOUNTEXP10=-2
21
PagOnline
Allegato Tecnico
10.4 Comando SEND_STATE
Con questo comando è possibile richiedere l'invio alle proprie listener di tutti i dati di un
determinato ordine. Non si ottengono dati di risposta a questo comando, ma solo l'esito della
richiesta stessa (si riceve ovviamente anche l'evento).
La chiamata di invio del listener da remoto non genera nessuna risposta per il chiamante e non dà
nessuna garanzia di invio del listener in quanto non è un comando a risposta, ma una richiesta di
invio messaggio http, ed in quanto tale soggetto a problemi di rete e quant'altro; la risposta positiva
al comando indica solamente che la richiesta è stata correttamente recepita dal sistema, che
provvederà ad esaudirla.
La chiamata di invio del listener da backoffice genera invece anche una risposta xml con l'esito
dell'invio del listener all'esercente. Se l'esercente desidera chiamare un URL per avere come risposta
lo stato di un ordine e l'esito positivo o negativo della interrogazione, dovrebbe utilizzare la
chiamata all'API del comando ORDER_STATE (v. sez. 10.3).
Nome
Tipo
Descrizione
Valori consentiti
Parametri obbligatori
numeroCommerciante
Numerico
Codice identificativo del merchant
stabilimento
Numerico
Numero identificativo dello
stabilimento del merchant
userID
Alfanumerico
Nome utente per l'accesso al sistema di
pagamento
password
Alfanumerico
Password per l'accesso al sistema di
pagamento
tipoComando
Alfanumerico
Comandi eseguibili
SEND_STATE
formatoRisposta
Alfanumerico
Tipo di formato della risposta
xml, plaintext
numeroOrdine
Alfanumerico
Numero dell'ordine di cui ricercare il
pagamento
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
Alfanumerico
Motivo della richiesta
Parametri facoltativi
ragioneRichiesta
Tabella 13: Parametri obbligatori e facoltativi per l'invio del comando SEND_STATE
Risposta xml
<?xml version="1.0" ?>
<remotecommand>
<commandname>SEND_STATE</commandname>
<respcode>0</respcode>
<description>Comando eseguito con successo</description>
</remotecommand>
22
PagOnline
Allegato Tecnico
Risposta plaintext
DESCRIZIONE=Comando eseguito con successo&SRC=000&PRC=000
10.5 Comando REFUND_CARD
Si possono rimborsare solo ordini in stato CONTABILIZZATO (stato CO) o che sono già stati
rimborsati parzialmente (ordini di cui è stato rimborsato un importo minore di quello totale).
•
L'annullamento del rimborso dell'ordine è effettuabile tramite l'applicativo di backoffice
nella sezione Utilità → Rimborsi (entro le ore 23.00 del giorno stesso in cui è stato richiesto
il rimborso)
•
È possibile rimborsare un ordine in più fasi fino al raggiungimento dell'importo totale
Nome
Tipo
Descrizione
Valori consentiti
Parametri obbligatori
numeroCommerciante
Numerico
Codice identificativo del merchant
stabilimento
Numerico
Numero identificativo dello
stabilimento del merchant
userID
Alfanumerico
Nome utente per l'accesso al sistema di
pagamento
password
Alfanumerico
Password per l'accesso al sistema di
pagamento
tipoComando
Alfanumerico
Comandi eseguibili
REFUND_CARD
formatoRisposta
Alfanumerico
Tipo di formato della risposta
xml, plaintext
numeroOrdine
Alfanumerico
Numero dell'ordine di cui effettuare il
rimborso
totaleOrdine
Numerico
Importo dell'ordine da rimborsare
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
Alfanumerico
Motivo della richiesta
Interi in formato
standard ISO
Parametri facoltativi
ragioneRichiesta
Tabella 14: Parametri obbligatori e facoltativi per l'invio del comando REFUND_CARD
23
PagOnline
Allegato Tecnico
Risposta xml
<?xml version="1.0" ?>
<remotecommand>
<commandname>REFUND_CARD</commandname>
<respcode>0</respcode>
<description>Comando eseguito con successo</description>
</remotecommand>
Risposta plaintext
DESCRIZIONE=Comando eseguito con successo&SRC=000&PRC=000
10.7 Comando DAILY_REPORT
Il comando server to server permette di richiamare uno o tutti gli ordini in stato
CONTABILIZZATO (stato CO), in stato RIMBORSATO o PARZIALMENTE RIMBORSATO
(CT, CP) o TUTTI gli ordini e il relativo stato di un determinato giorno. La risposta in questo caso
viene data solo in formato xml.
Nome
Tipo
Descrizione
Valori consentiti
numeroCommerciante
Numerico
Codice identificativo del
merchant
stabilimento
Numerico
Numero identificativo dello
stabilimento del merchant
userID
Alfanumerico
Nome utente per l'accesso al
sistema di pagamento
password
Alfanumerico
Password per l'accesso al
sistema di pagamento
tipoComando
Alfanumerico
Comandi eseguibili
DAILY_REPORT
formatoRisposta
Alfanumerico
Tipo di formato della risposta
xml
numeroOrdine
Alfanumerico
Numero dell'ordine di cui
ricercare il pagamento
Inserendo il simbolo asterisco
* verranno estratti tutti gli
ordini del giorno selezionato
giornoReport
Alfanumerico
Data dell'ordine o della lista
degli ordini
yyyy-mm-dd (es. 2010-0225)
dailyStato
Alfanumerico
Stato dell'ordine
CONTABILIZZATI,
RIMBORSATI,
TUTTI
mac
Alfanumerico
Stringa crittografica a garanzia
dell'integrità dei dati
Tabella 15: Parametri obbligatori per l'invio del comando DAILY_REPORT
24
PagOnline
Allegato Tecnico
I valori ammessi per il parametro dailyStato sono:
•
CONTABILIZZATI: estrae un preciso ordine o tutti gli ordini ( numeroOrdine=*) di un
determinato giorno in stato contabilizzato (CO);
•
RIMBORSATI: estrae un preciso ordine o tutti gli ordini ( numeroOrdine=*) di un
determinato giorno per con stati stornati (IP, IT, CP, CT, RC);
•
TUTTI: estrae un preciso ordine o tutti gli ordini ( numeroOrdine=*) di un determinato
giorno.
Risposta xml
<remotecommand>
<commandname>DAILY_REPORT</commandname>
<orderdata>
<merchantid>9999888</merchantid>
<stabil>99888</stabil>
<orderid>11111111</orderid>
<stato_ordine>CO</stato_ordine>
<totale>1</totale>
<totaledepositato>1</totaledepositato>
<dataordine>2010-03-30 23:10:48</dataordine>
<datamodifica>2010-03-30 23:12:53</datamodifica>
<nomeuserins>9999888</nomeuserins>
<numerorefund>0</numerorefund>
<datarefund />
<importostornato />
<nomeuserstorno />
<stato />
<causale />
</orderdata>
</remotecommand>
Risposta xml vuota o errata
<?xml version="1.0" ?>
<remotecommand>
<commandname>DAILY_REPORT</commandname>
<respcode>1</respcode>
<description>Nessun ordine per il giorno specificato</description>
</remotecommand>
25