Contract

NOME

TITOLO

MPAY_INTEGRAZI ONEPAGAMENTIES TERNI_FUNZIONI_1

_LIVELLOEVOLUTO

_V3.0.0.DOCX

MANUALISTICA V.3.0.0

INTEGRAZIONE PORTALI ESTERNI DI LIVELLO EVOLUTO.

MPay

Integrazione Pagamenti Esterni con Funzioni 1° livello Evoluto

REVISIONI DEL DOCUMENTO
VER.	DESCRIZIONE DELLA REVISIONE	PREPARATO	APPROVATO	DATA
1.0.0	Primo rilascio documentazione	X.Xxxxxxx	X.Xxxxxxxx	23/06/2016
1.0.1	Secondo rilascio documentazione	X.Xxxxxxx	X.Xxxxxxxx	03/08/2016
2.0.0	Terzo rilascio documentazione – Marca da Bollo digitale	X.Xxxxxxx	X.Xxxxxxxx	02/11/2017
3.0.0	Quarto rilascio documentazione – Carrello Multibeneficiario	X.Xxxxxxx	X.Xxxxxxxx	03/08/2018

Sommario

1 INTRODUZIONE 3

2 SCENARIO APPLICATIVO 3

2.1 Schema architetturale 3

2.2 Schema funzionale 4

3 PROTOCOLLO APPLICATIVO 6

3.1 PROTOCOLLO DI COMUNICAZIONE 6

3.2 Struttura del buffer inviato Bi 7

3.3 Utilizzo del buffer in pagine HTML 8

4 CONTENUTO APPLICATIVO 8

4.1 Richiesta di pagamento (PaymentRequest) 8

4.2 Dati di pagamento (PaymentData) 12

4.3 Messaggio di riposta alla notifica (CommitMsg) 15

5 LIBRERIE DI INTERFACCIAMENTO 16

5.1 Richiesta di pagamento 16

5.2 Conclusione pagamento 19

1 Introduzione

Il documento descrive l'integrazione prevista per servizi esterni alla Piattaforma di Pagamento di MPay allo scopo di interfacciare le funzioni di pagamento online in modo integrato.

2 Scenario Applicativo

Di seguito viene descritta l'architettura della soluzione, analizzando in dettaglio le transazioni applicative previste nel colloquio tra i server partecipanti.

2.1 Schema architetturale

In figura sono rappresentati i sistemi che intervengono nel processo di attivazione di un pagamento: il portale esterno (PEXT), il portale di pagamento (MPay) ed il portale del gateway di pagamento (PGTW). Mentre il contribuente rappresenta l’attore.

Fig. 1

I server ospitanti i tre portali servizi possono essere geograficamente e logicamente distribuiti; il portale esterno sarà ospitato presso l'ente erogante il servizio di riferimento, mentre il portale del gateway sarà a carico dell’istituto bancario convenzionato con MPay.

La navigazione utente procede all'interno del portale esterno attraverso le pagine che costituiscono l'applicazione (a); alla richiesta di conferma del pagamento del servizio, il browser utente viene ri-diretto al MPay (b); MPay completerà la richiesta di pagamento ricevuta attraverso la selezione dello strumento di pagamento e del metodo di notifica di interesse da adottare con il gateway di pagamento e ri-dirigerà nuovamente la navigazione utente verso il portale del gateway di pagamento richiesto (c).

Durante questa fase, l'utente provvede a fornire tutti i dati riservati necessari per completare il pagamento in base allo strumento di pagamento disponibile nella convenzione di MPay (Carta di Credito, Rid OnLine, Home Banking, Mav online), comunicandoli direttamente al mondo bancario, secondo i canoni di sicurezza previsti. Il gateway di pagamento effettuerà le verifiche necessarie e ritornerà l'utente al MPay (d) con i dati relativi all'autorizzazione effettuata e il relativo esito; a sua volta MPay ri-dirigerà l'utente al portale esterno da cui ha avuto origine la richiesta di pagamento (e).

Nelle attività di passaggio dati tra i diversi sistemi coinvolti vengono adottate delle metodologie di comunicazione attraverso un interscambio diretto attuato ad esempio mediante soluzioni server-to-server. Nel caso in cui la navigazione utente non sia completa di tutte le fasi descritte in precedenza è possibile che venga a crearsi uno stato di incertezza (Pending) relativamente al pagamento effettuato.

Nei casi di pagamenti pending, MPay ed i sistemi del gateway attraverso logiche di controllo periodico, provvederanno a riallineare in modalità asincrona lo stato della transazione in MPay (f).

Nel momento in cui l’incertezza di un pagamento viene risolta, MPay provvederà a comunicarlo al portale esterno (g).

Quest'ultimo passaggio viene effettuato al solo fine di ottenere un allineamento on-line dei risultati ottenuti; come default, non viene adottato nessun meccanismo di garanzia di delivery del messaggio; su richiesta del servizio esterno è possibile attivare un meccanismo di retry del messaggio.

Le transazioni che hanno avuto esito positive sono comunque disponibili attraverso un flusso di rendicontazione prodotto periodicamente da MPay.

2.2 Schema funzionale

Quanto descritto in precedenza definisce le interazioni tra gli attori presenti, focalizzando lo schema di navigazione proposto all'utente; di seguito vengono descritte le interazioni applicative tra i diversi server. Gli scambi di dati sono di due tipi:

• dati associati alla ri-direzione: sono quelli inseriti tramite i metodi POST/GET all'interno dell'Header HTTP utilizzata per la navigazione utente;

• dati passati in colloquio server-to-server: sono quelli che i diversi server si scambiano, senza coinvolgere la navigazione utente.

In figura 2 sono riportati i particolari relativi all'operazione di pagamento completa.

Fig. 2

Inizialmente (punto 1), il Cittadino completa la navigazione all'interno del portale servizi esterno definendo l'insieme dei dati necessari per il pagamento. Il Cittadino dal portale servizi esterno (2) conferma la sua necessità di proseguire con il pagamento; il portale servizi esterno mediante un colloquio diretto server-to- server, invia tali dati al Server di Pagamento (2.1), ricevendo in ritorno un identificativo della richiesta effettuata RID (2.2). Tale identificativo viene inviato nuovamente al Server di MPay durante la fase di ri- direzione della navigazione utente (2.3).

In funzione del tipo di richiesta ricevuta e delle modalità di pagamento disponibili, il Server di MPay procederà a richiedere all'utente eventuali dati necessari per proseguire con l’attività di pagamento (3), (per esempio il tipo di strumento, come carta di credito, home-banking, ...) e alla conferma finale di pagamento (4) ri-dirigerà l'utente al sito di pagamento secondo i meccanismi definiti dal sito stesso (4.1). Una volta connesso al sito del gateway di pagamento, l'utente inserirà i dati necessari (5), per esempio il numero di carta di credito, e richiede di completare l'operazione (6). Al termine dell'operazione, supponendo un esito positivo dell'operazione, il sito di pagamento provvederà a rimandare la navigazione utente al Server di MPay (6) che potrà recuperare i dati di autorizzazione che saranno memorizzati nel proprio database (6.1).

Opzionalmente, il Server di MPay può non effettuare la trasmissione e la visualizzazione della quietanza di pagamento al Cittadino, qualora il portale servizi esterno ne presenti una propria (6.1.1 – 6.1.2).

Successivamente il Server di MPay procederà ad inviare, al portale servizi esterno, la notifica di pagamento completa dei dati di autorizzazione di pagamento tramite un colloquio server-to-server (61.3 – 6.1.4).

Infine, la ri-direzione dell'utente verso il portale servizi esterno (6.1.5), avviene corredandola con un identificativo di pagamento (PID) che viene inviato tramite protocollo GET o POST in funzione di come è stata fatta la richiesta.

La spedizione del messaggio di notifica verso il portale servizi esterno è configurabile durante la fase di richiesta di pagamento (2.1), ma non fornisce, di default, nessun tipo di meccanismo di retry per la gestione delle notifiche perse. Opzionalmente, tramite un parametro della richiesta di pagamento (2.1), è possibile attivare un meccanismo di ripetizione del messaggio fino a quando non viene ricevuta una risposta positiva da parte dell'applicazione esterna (l'invio del messaggio viene ripetuta per un numero limitato di tentativi definito).

Infine, anche i pagamenti richiesti da portali servizi esterni viene prevista la rendicontazione degli incassi mediante l’invio di flussi telematici. (vd. MPay-Specifica_Tecnica_Integrazione_Ente - Cap-5.2.1)

3 Protocollo Applicativo

Di seguito sono descritte le varie parti del protocollo, componenti logiche e fisiche atte a garantire gli aspetti della sicurezza:

 protocollo di comunicazione

 Struttura del Buffer inviato Bi

 Utilizzo del Buffer in pagine HTML

3.1 protocollo di comunicazione

I messaggi scambiati tra i due server devono godere di alcune caratteristiche:

1. non possono essere manipolati nel proprio contenuto

2. devono poter essere identificati univocamente, in modo che una eventuale intercettazione non possa essere riproposta per ricreare operazioni di pagamento o di autorizzazione

Il primo requisito è perseguibile aggiungendo una "firma" dei dati inviati, codificata mediante una chiave segreta (HMAC); in particolare, è possibile inserire un hash dei dati ai quali è stato giustapposto una stringa nota ad entrambi i partecipanti.

Il secondo requisito richiede l'inserimento nel buffer dei dati di un identificativo che permetta di definire una "scadenza" alla validità del buffer stesso; in questo caso potrebbe essere utilizzata una marcatura

temporale: questo sistema richiede una sincronizzazione oraria tra i partecipanti, anche se comunque deve essere prevista una certa finestra di tolleranza.

Opzionalmente sarà possibile cifrare il contenuto dati applicativo trasportato dal protocollo di comunicazione.

La struttura del buffer inviato Bi sarà la seguente:

Bi = T + C + ENCODED(BD) + H

dove T è la stringa contenente il tag orario, C è il codice identificativo del server emittente, BD sono i dati applicativi e H la stringa hash del buffer B ottenuto come derivazione di Bi con la chiave segreta del server emittente.

Al fine di rendere variabile la stringa segreta è inserita una parte time dependent. Alla ricezione di un buffer Bi verranno effettuati i seguenti passi applicativi:

1. estrazione del tag orario T dal buffer Bi

2. estrazione del buffer dati ENCODED(BD) dal buffer Bi

3. verifica della correttezza di T, ossia se rientra all'interno della finestra temporale definita (es. 3 minuti)

4. DECODE del buffer dati BD

5. calcolo del hash HC

6. estrazione del hash H dal buffer Bi

7. verifica della congruenza tra HC e H

3.2 Struttura del buffer inviato Bi

Il buffer Bi è strutturato in formato XML ed è descritto come segue:

</Buffer>

Il corrispondente DTD è:

<!ELEMENT Buffer(TagOrario, CodicePortale, BufferDati, Hash)>

<!ELEMENT TagOrario (#PCDATA)>

<!ELEMENT CodicePortale (#PCDATA)>

<!ELEMENT BufferDati (Attivazione)>

<!ENTITY % Attiv SYSTEM “Attivazione.dtd”>

%Attiv;

<!ELEMENT Hash(#PCDATA)>

Il buffer dei dati applicativi BD potrà avere, a sua volta, una struttura XML.

Per il calcolo dell'Hash può essere utilizzato un algoritmo MD5: il valore risultante viene inviato dopo esser stato codificato come stringa esadecimale, cioè ciascun byte viene rappresentato mediante due caratteri.

3.3 Utilizzo del buffer in pagine HTML

Considerando il contenuto del buffer è consigliabile utilizzare una codifica HTML (HTML Encoding) prima di inserirlo all'interno di una pagina HTML.

4 Contenuto applicativo

Di seguito vengono specificati i contenuti applicativi (buffer dati BD) nella comunicazione tra i server nel caso di un'operazione di pagamento.

4.1 Richiesta di pagamento (PaymentRequest)

La richiesta di pagamento è rappresentata da una struttura XML che viene ad innestarsi all'interno della chiave BufferDati; i dati contenuti all'interno della richiesta devono consentire la corretta definizione dei parametri di pagamento e permettere il rientro al termine del processo di pagamento.

La struttura del buffer è la seguente:

</UserData>

</MarcaDaBolloDigitale>

</ServiceData>

<Ente>

</Ente>

<Ente>

</Ente>

………

</MultiEnte>

</ImportoContabile>

</ImportiContabili>

< CodiceEntePortaleEsterno></ CodiceEntePortaleEsterno>

< DescrEntePortaleEsterno></ DescrEntePortaleEsterno>

</EnteDestinatario>

</EntiDestinatari>

</AccountingData>

</ PaymentRequest>

Campo	Obblig.	Len	Descrizione
PaymentRequest
PortaleId	*		Identifica il sito dei servizi In accordo alla configurazione definita in MPay in fase di configurazione del portale
Funzione	*		Indica la funzione richiesta: "PAGAMENTO"
URLDiRitorno	*		Indica l'URL di ridirezione al termine del pagamento
URLDiNotifica	*		Indica l'URL di notifica dello stato del pagamento nel colloquio server-to-server
URLBack	*		Indica l'URL di navigazione back
CommitNotifica		1	Indica se (S) deve essere attesa la risposta al messaggio di notifica [default N].
UserData
EmailUtente			Indirizzo email dell'utente
IdentificativoUtente	*	16	Dato identificativo dell'utente (può essere valorizzato con il codice fiscale o la partita iva)
ServiceData			Non presente se presente MultiEnte
CodiceUtente	*	5	Identificativo del servizio che richiede il pagamento. Valorizzato con la seguente formattazione: Codice Utente - CodiceEnte () - TipoUfficio () - CodUfficio (*) - Tipologia Servizio In accordo alla configurazione definita in MPay in fase di convenzione dell’Ente
CodiceEnte	*	5
TipoUfficio	*	1
CodiceUfficio	*	6
TipologiaServizio	*	3
NumeroOperazione	*	128	Identificativo univoco dell'operazione all'interno del sito dei Servizi

NumeroDocumento	*	20	Estremo del documento pagato
AnnoDocumento			Anno del documento pagato
Valuta		3	"EUR"
Importo	*		Importo della transazione di pagamento espresso in centesimi. Se presente il campo MarcaDaBolloDigitale allora comprende anche l’importo indicato in ImportoMarcaDaBolloDigitale
MarcaDaBolloDigitale
ImportoMarcaDaBolloDigitale			Importo della marca da bollo espresso in centesimi
SegnaturaMarcaDaBolloDigitale		70	Contiene l’impronta informatica (digest), rappresentata in “base 64 binary”, del documento informatico o della segnatura di protocollo cui è associata la marca da bollo digitale. L’algoritmo di hash da utilizzare è SHA-256.
TipoBolloDaErogare		2	Valorizzare con 01 – Imposta di bollo
ProvinciaResidenza		2	Sigla automobilistica della provincia di residenza del soggetto pagatore, cioè di colui che presenta l'istanza o che richiede la documentazione in bollo
DatiSpecifici			Dati del servizio
MultiEnte			Non presente se presente ServiceData
Valuta		3	"EUR"
ImportoTotale	*		Importo totale della transazione di pagamento espresso in centesimi. Deve coincidere con la somma dei campi Importi presenti nelle sezioni Ente
NumeroOperazione	*	128	Identificativo univoco dell'operazione all'interno del sito dei Servizi
Ente			Occorrenze da 1..n
CodiceUtente	*	5	Identificativo del servizio che richiede il pagamento. Valorizzato con la seguente formattazione: Codice Utente - CodiceEnte () - TipoUfficio () - CodUfficio (*) - Tipologia Servizio In accordo alla configurazione definita in MPay in fase di convenzione dell’Ente
CodiceEnte	*	5
TipoUfficio	*	1
CodiceUfficio	*	6
TipologiaServizio	*	3
NumeroDocumento	*	20	Estremo del documento pagato
AnnoDocumento			Anno del documento pagato
Importo	*		Importo da pagare per l’Ente espresso in centesimi.
DatiSpecifici			Dati del servizio

AccountingData
ImportiContabili			Elenco di voci ImportoContabile
ImportoContabile			Indica la suddivisione dell'importo dell'ordine nei vari importi contabili per le operazioni di ragioneria
Identificativo			Identificativo dell'importo contabile: • IC1 = importo • IC2 = bollo • IC3 = spese • IC4 = commissioni • IC5 = spese invio quietanza
Valore			Importo associato
EntiDestinatari			Elenco di voci EnteDestinatario
EnteDestinatario			Indica la suddivisione dell'importo dell'ordine nei vari importi destinata ai diversi enti
CodiceEntePortaleEsterno	*	50	Identificativo dell’Ente destinatario definito dal Portale Esterno
DescrEntePortaleEsterno	*	256	Descrizione dell’Ente destinatario definito dal Portale Esterno
Valore	*		Importo associato espresso in centesimi
Causale		256	Causale del versamento
ImportoContabileIngresso			Identificativo dell'importo contabile di ingresso per l'ente incassante espresso in centesimi
ImportoContabileUscita			Identificativo dell'importo contabile di uscita per l'ente incassante espresso in centesimi

I dati non obbligatori possono essere omessi mantenendo il TAG all'interno del buffer XML: per esempio se non interessa la notifica si può inserire nel buffer il TAG:

(*) Il codice Ente, tipo e codice ufficio sono valorizzati attraverso il formulario disponibile dal portale dell’Agenzia delle Entrate:

xxx://xxx.xxxxxxx.xx/xxx/xxxxxxx/Xxxxxxxx_Xxxx_XxxxxxxxxXxxxxxxxxxx.xxx

4.2 Dati di pagamento (PaymentData)

I dati di autorizzazione al pagamento che MPay ritorna all'applicazione richiedente del portale esterno, sono costituiti da una struttura XML che viene ad innestarsi all'interno della chiave BufferDati.

La struttura del buffer è la seguente:

</PaymentData>

Campo	Obblig.	Descrizione
PaymentData
PortaleId	*	Identifica il sito dei servizi
NumeroOperazione	*	L'identificativo ricevuto all'atto della richiesta (campo NumeroOperazione)
CodiceUtente		Identificativo del servizio che richiede il pagamento. Valorizzato con la seguente formattazione: Codice Utente - CodiceEnte () - TipoUfficio () - CodUfficio (*) - Tipologia Servizio In accordo alla configurazione definita in MPay in fase di convenzione dell’Ente
CodiceEnte
TipoUfficio
CodiceUfficio
TipologiaServizio
NumeroDocumento		Estremo del documento pagato
IDOrdine		Identifica l'operazione sul Server di Pagamento

DataOraOrdine		Data e ora della creazione dell’ordine di pagamento
IDTransazione		Identifica la transazione sul sistema di pagamento
DataOraTransazione		Data e ora della transazione bancaria
SistemaPagamento		Indica il sistema di pagamento selezionato dall'utente
SistemaPagamentoD		Riporta la descrizione del sistema di pagamento selezionato dall'utente
CircuitoAutorizzativo		Indica il circuito che ha rilasciato l'autorizzazione
CircuitoAutorizzativoD		Riporta la descrizione del circuito che ha rilasciato l'autorizzazione
ImportoTransato		Importo proposto per il pagamento
ImportoCommissioni		Ritorna il valore delle commissioni applicate a carico del contribuente
ImportoCommissioniEnte		Ritorna il valore delle commissioni applicate a carico dell’ente
AllegatoMarcaDaBollo		Marca da Bollo digitale trasportato nella ricevuta telematica secondo la codifica in “base 64 binary”.
Esito	*	Esito dell'operazione
EsitoD	*	Esito dell'operazione (la descrizione)
Autorizzazione		Numero di autorizzazione rilasciata dal circuito
DatiSpecifici		Dati del servizio: restituiti se presenti nel PaymentRequest

I campi SistemaPagamento e SistemaPagamentoD sono valorizzati secondo la seguente tabella:

SistemaPagamento	SistemaPagamentoD
PY	MPAY

I campi CircuitoAutorizzativo e CircuitoAutorizzativoD sono valorizzati secondo la seguente tabella in funzione degli strumenti gestiti da MPay):

CircuitoAutorizzativo	CircuitoAutorizzativoD
CCRED	Carta di credito
HBANK	Home Banking
RID	RID On Line
MAV	MAV On Line

I campi Esito e EsitoD assumono i valori della seguente tabella:

Esito	Descrizione
OK	Successo nell'operazione
KO	Autorizzazione negata dal circuito
OP	Transazione pending

UK	Transazione non presente

Il sistema dopo 10 tentativi in cui il portale esterno risponde con NOK si blocca inviando mail agli operatori configurati nel sistema in modo che possano operare per verificare, anche con il fornitore del portale esterno, la problematica della non notifica.

E’ prevista la possibilità di rinotificare manualmente per altri 10 tentativi, utilizzando l’opportuna interfaccia che MPay mette a disposizione degli operatori. L’azione evidenziata permette la rinotifica.

4.3 Messaggio di riposta alla notifica (CommitMsg)

Questo messaggio viene utilizzato per segnalare al Server di MPay che il messaggio di notifica è stato correttamente ricevuto dall'applicazione esterna.

Il messaggio di notifica è costituito da un messaggio di tipo PaymentData. Di default il Server di MPay non prevede nessuna risposta sul messaggio di notifica (campo URLNotifica di PaymentRequest), viene invece atteso nel caso in cui il campo CommitNotifica di PaymentRequest sia valorizzato a 'S': in questo caso il messaggio di notifica viene ripetuto fino a quando l'applicazione esterna non ritorna un CommitMsg con Commit a 'OK'.

La struttura del buffer è la seguente:

</CommitMsg>

Campo	Obblig.	Descrizione
CommitMsg
PortaleID	*	Identifica il sito dei servizi (rispettivo campo di PaymentData
NumeroOperazione	*	L'identificativo ricevuto all'atto della richiesta (rispettivo campo di PaymentData)
IDOrdine	*	Identifica l'operazione sul Server di Pagamento (rispettivo campo di PaymentData)
Commit	*	Riporta il codice dell'avvenuto ricevimento della notifica

il campo Commit sarà valorizzato con i valori di ritorno secondo la seguente tabella:

Commit	Descrizione
OK	il messaggio di notifica è stato recepito
NOK	il messaggio di notifica NON è stato recepito

5 Librerie di interfacciamento

Il protocollo descritto nel presente documento permette lo scambio dati tra il MPay ed i portali esterni. Al fine di facilitare l'integrazione di applicazioni con il MPay, è disponibile una libreria per la gestione dei messaggi in accordo con il protocollo descritto. Tale libreria, realizzata in tecnologia JavaBean (requisito

minimo JDK 5) permette di creare e verificare i messaggi in modo da lasciare all'applicazione il solo compito di gestire i dati applicativi.

Le operazioni eseguite fanno riferimento all'utilizzo principalmente della classe com.seda.payer.ext.Client, di gestione delle chiavi segrete per il protocollo di comunicazione, per la generazione del corretto messaggio e per la verifica della correttezza di quanto ricevuto.

Per il corretto funzionamento della suddetta libreria è necessario l’utilizzo delle seguenti librerie esterne:

commons-codec-1.3.jar log4j-1.2.15.jar

5.1 Richiesta di pagamento

La parte iniziale dello script di creazione del messaggio di richiesta provvederà alla

creazione dell'oggetto e della sua configurazione:

String IV = “726838938”

String key = “1823763823929”; String portale = “PORTEXT1”;

Client client = new Client(IV, key, portale);

Se la propria applicazione ha già a disposizione per il logging un’istanza della classe Logger di Log4J, è possibile istanziare la classe Client nel seguente modo:

Client client = new Client(IV, key, portale, logger);

In alternativa è possibile configurare il logger proprietario della libreria andando a modificare manualmente il file /com.seda.payer.ext/src/com/seda/payer/ext/util/log4j.properties

Affinché la classe sia disponibile, è necessario inserire l'opportuna direttiva di import: import com.seda.payer.ext.Client

In seconda istanza, sarà necessario preparare il buffer XML con il contenuto applicativo della richiesta; in particolare sarà necessario riempire la struttura <PaymentRequest> che è costituita dai campi per l'indicazione della URL a cui ritornare l'utente al termine del pagamento in caso di successo o quella di errore. Di seguito viene riportato un esempio di costruzione senza l'utilizzo di particolari parametri di configurazione:

BufferData = "<PaymentRequest>" +

"<PortaleID> PORTEXT1</PortaleID>" + "<Funzione>PAGAMENTO</Funzione>" +

"<URLDiRitorno>xxxx://xxxxxxx/Xxxxxxx/xxxxxxxx_xxxxxxxxx.xxx</URLDiRitorno>" + "<URLDiNotifica>xxxx://xxxxxxx/Xxxxxxx/xxxxxxxx_xxxxxxxxx.xxx </URLDiNotifica>" + "<URLBack> xxxx://xxxxxxx/Xxxxxxx/xxxx.xxx</URLBack>" + "<CommitNotifica>S</CommitNotifica>" +

"<UserData>" +

"<EmailUtente>xxxxx@xxx.xx</EmailUtente>" + "<IdentificativoUtente> PPRPRN65R25A944J</IdentificativoUtente>" +

"</UserData>" + "<ServiceData>" +

"<CodiceUtente>AABBCC</CodiceUtente>" + "<CodiceEnte>12345</CodiceEnte>" + "<TipoUfficio></TipoUfficio>" + "<CodiceUfficio></CodiceUfficio>" + "<TipologiaServizio>TPS</TipologiaServizio>" +

"<NumeroOperazione>937264gi8841837Kppdf</NumeroOperazione>" + "<NumeroDocumento>123412348636242874</NumeroDocumento>" +

"<AnnoDocumento>2010</AnnoDocumento>" + "<Valuta>EUR</Valuta>" + "<Importo>5743</Importo>" +

"<DatiSpecifici />" + "</ServiceData>" +

"</PaymentRequest>";

A questo punto dovrà essere richiamato il metodo getBufferPaymentRequest per farsi restituire l’intero buffer criptato da passare al MPay nella prima richiesta S2S.

String buffer = client.getBufferPaymentRequest(BufferData);

il buffer ottenuto dovrà essere utilizzato per effettuare il primo scambio S2S verso il MPay, alla url URLSERVERMPAY/cart/xxxX0XXXX.xx, il quale risponderà con l’id della richiesta(RID). Tale buffer può essere passato nello scambio S2S sia tramite richiesta HTTP-GET che attraverso HTTP-POST all’interno di un parametro “buffer”.

Attenzione!! Affinché questo tipo di integrazione funzioni correttamente anche con canali di pagamento differenti (es: dispositivi mobile), è fondamentale che il portale esterno, già dalla prima chiamata S2S verso il MPay, passi nel request header lo "User-Agent" originale del dispositivo che sta inizializzando la procedura di pagamento. Questa informazione servirà al portale MPay per effettuare gli opportuni controlli di sicurezza e di verifica abilitazioni per lo specifico canale di pagamento (abilitazioni differenti in base al canale).

Di seguito viene riportato un estratto di codice utilizzando la libreria HttpClient per settare lo User-Agent originale del dispositivo che sta inizializzando la procedura.

HttpClient client = new HttpClient(); URL url = new URL(sUrlS2SRID);

PostMethod method = new PostMethod(url.getPath()); method.addParameter("buffer", buffer);

String userAgent = request.getHeader("User-Agent"); if (userAgent == null || userAgent.equals("")) userAgent = request.getHeader("user-agent");

if (userAgent == null) userAgent = "";

method.setRequestHeader("User-Agent", userAgent);

Il RID così ottenuto dalla prima chiamata S2S dovrà essere utilizzato per preparare il nuovo buffer con il RID criptato attraverso il seguente metodo:

String bufferRID = client.getBufferRID(rID);

Il bufferRID quindi dovrà essere utilizzato o per generare una pagina HTML autopostante di ridirezione verso il MPay:

<html>

</form>

</body>

</html>

O per effettuare un semplice redirect nel seguente modo: response.sendRedirect(“URLSERVERMPAY/cart/xxxXxxx.xx?buffer="+ bufferRID);

5.2 Conclusione pagamento

La fase di conclusione del pagamento può essere scomposta principalmente in due fasi:

1. Fase di notifica

2. Fase di conclusione

Notifica pagamento

Nella fase di notifica il MPay invierà tramite uno scambio S2S al portale esterno verso l’URL passato nel nodo <URLDiNotifica> del PaymentRequest, un ID di pagamento (PID) il quale dovrà essere utilizzato dal portale esterno per richiamare il metodo getBufferPID come descritto di seguito:

String IV = “726838938”

String key = “1823763823929”; String portale = “PORTEXT1”;

Client client = new Client(IV, key, portale);

String pID = “98239ddsad91247asdj12”; PID inviato dal MPay

String bufferPID= client. getBufferPID(pID);

Il bufferPID così ottenuto dovrà essere inviato nel parametro buffer all’URL del MPay URLSERVERMPAY/cart/xxxX0XXXX.xx

Il MPay controllerà la correttezza del buffer ricevuto e risponderà con il messaggio del PaymentData criptato.

Il portale esterno per poter leggere il PaymentData potrà utilizzare il seguente metodo:

int WINDOW_MINUTES=10;

String paymentData = client. getPaymentData(buffer, WINDOW_MINUTES);

Dove la variabile buffer rappresenta l’intero xml del buffer inviato dal MPay e la variabile WINDOW_MINUTES la definizione della finestra temporale di validità del messaggio espressa in minuti.

Dopo aver ricevuto e verificato il paymentData il portale esterno dovrà concludere la fase di notifica iniziata dal MPay inviando come risposta il CommitMsg

</CommitMsg>

In base all’esito il nodo <Commit> potrà assumere i valori OK o NOK.

Conclusione pagamento

La fase di conclusione permette di reindirizzare il contribuente al portale dei servizi dal quale era iniziata l’attività di pagamento. Il MPay effettuerà un redirect al portale esterno utilizzando l’URL passato nel nodo <URLDiRitorno> del PaymentRequest ed inviando in chiaro lo stesso PID trasmesso nella fase iniziale della notifica.

Anche in questo caso il portale esterno dovrà utilizzare il metodo getBufferPID come descritto di seguito:

String IV = “726838938”

String key = “1823763823929”; String portale = “PORTEXT1”;

Client client = new Client(IV, key, portale);

String pID = “98239ddsad91247asdj12”; ‘PID inviato dal MPay

String bufferPID= client. getBufferPID(pID);

Il bufferPID così ottenuto dovrà essere sempre inviato nel paremetro buffer all’URL del MPay URLSERVERMPAY/cart/xxxX0XXXX.xx

Il MPay controllerà la correttezza del buffer ricevuto e risponderà sempre con il messaggio del PaymentData criptato.

La lettura del PaymentData potrà essere fatta sempre utilizzando il metodo getPaymentData.

Document Metadata

Table of Contents

Contract

Document Metadata