Sei sulla pagina 1di 50

TVB_IPG_Manuale_ECom_MBMP_111.

doc
Release 1.1.1

INTERNET PAYMENT GATEWAY

e-Commerce
Specifiche di Interfacciamento Merchant

Gennaio 2017 Pagina 1 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Data Versione Autore Descrizione


01/02/2016 1.0.0 PM Prima release

16/08/2016 1.0.1 PM - Aggiornato livello minimo prot. TLS a 1.1


- par. 3.2.3.1 - corretto campo currencycode: non
obbligatorio
- par. 3.2.5.2 – eliminato result “REVERSED”

27/10/2016 1.1.0 PM - Aggiunta definizione e utilizzo dell’API


PaymentQuery.
- Esternalizzata Appendice D con la lista CA in doc
separato.

05/01/2017 1.1.1 PM - Indicato utilizzo esclusivo prot. TLS 1.1


- Aggiunta valorizzazione speciale in UDF2 per
l’indicazione dello strumento di pagamento
- aggiunto in Appendice C il cod. err. PY20087

Distribuzione
Il presente documento è di esclusiva proprietà di Consorzio Triveneto S.p.A. – Gruppo Bassilichi.
La riproduzione diffusione e/o la comunicazione a terzi del presente documento può avvenire
esclusivamente a seguito di esplicita richiesta scritta a Consorzio Triveneto S.p.A., unico soggetto
autorizzato in tal senso.

Gennaio 2017 Pagina 2 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

INDICE

1. Introduzione ............................................................................................................................................ 4
1.1. Internet Payment Gateway................................................................................................................ 4
1.2. Selection Payment Page (SPP)........................................................................................................... 4
1.3. Vantaggi dell’utilizzo della redirezione ............................................................................................ 5
2. Fasi di una transazione........................................................................................................................... 6
2.1. Introduzione ......................................................................................................................................... 6
2.1.1. Il punto di vista del Cliente........................................................................................................... 6
2.1.2. Il punto di vista del Merchant...................................................................................................... 6
2.1.3. Il punto di vista di IPG .................................................................................................................. 7
2.2. Schema del flusso di informazioni .................................................................................................... 8
2.3. Descrizione degli steps ...................................................................................................................... 9
3. Integrazione del Merchant .................................................................................................................. 11
3.1. Introduzione ....................................................................................................................................... 11
3.2. Messaggi tra il sito del Merchant e IPG ........................................................................................ 11
3.2.1. Messaggi on-line.......................................................................................................................... 11
3.2.2. Messaggi off-line ......................................................................................................................... 12
3.2.3. Messaggio PaymentInit ............................................................................................................... 13
3.2.4. Messaggio NotificationMessage ................................................................................................ 15
3.2.5. Messaggio Payment .................................................................................................................... 20
3.3. e24PaymentPipe - Descrizione ....................................................................................................... 21
3.4. Specifiche di interfacciamento diretto .......................................................................................... 22
3.5. Demo ................................................................................................................................................... 24
4. Ambiente di Test .................................................................................................................................. 26
4.1. Casi di test raccomandati ................................................................................................................ 26
5. Personalizzazione delle pagine di pagamento ................................................................................... 30
5.1. Personalizzazione su Smartphone e Tablet ................................................................................. 31
5.2. Esempio di Layout1 e Layout2 ....................................................................................................... 31
Appendice A Gestione contabile delle transazioni .................................................................... 32
Contabilizzazione Immediata ........................................................................................................................ 32
Contabilizzazione differita ............................................................................................................................. 33
Appendice B Installazione del Demo .............................................................................................. 35
Appendice C Lista dei Codici di Errore ......................................................................................... 37
Appendice D Decodifica campo responsecode ........................................................................... 43
Appendice E Elenco country codes .................................................................................................. 45
Documentazione di supporto .............................................................................................................. 50

Gennaio 2017 Pagina 3 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

1. Introduzione

1.1. Internet Payment Gateway


Il servizio di Commercio Elettronico si pone lo scopo di intermediare i flussi finanziari provenienti
dalle vendite su Internet.
Ai Merchants, che già dispongono di un proprio sito in Internet, viene fornita una piattaforma
unica per la gestione completa delle transazioni E-Commerce con carta di credito:
• Online: gestisce in modalità sicura di tutte le fasi della transazione economica.
• Offline: fornisce al Merchant un account per l’accesso via web all’interfaccia
amministrativa, nella quale è possibile verificare lo stato delle transazioni,
generare i report di operatività e procedere alle operazioni contabili necessarie.

1.2. Selection Payment Page (SPP)


Per finalizzare il pagamento di una transazione E-Commerce, il Merchant redireziona il browser
del Cliente sul sito di Internet Payment Gateway (di seguito IPG) per l’inserimento dei dati della
carta di credito, o l’utilizzo di altri strumenti di pagamento offerti dal Merchant, e completare così
l’acquisto.

La pagina inizialmente visualizzata da IPG al Cliente è chiamata Selection Payment Page (“SPP”).
Essa gestisce tutti gli Strumenti di Pagamento supportati dal Merchant. Dopo che il Cliente ha
selezionato lo strumento che intende usare per il pagamento, IPG presenta una pagina specifica
per quello strumento, in cui il Cliente inserisce i dati necessari.

Gennaio 2017 Pagina 4 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Una volta inseriti tutti i dati, il Cliente potrebbe essere redirezionato ad un sito esterno per
completare il pagamento, se la modalità di pagamento scelta lo prevede, oppure attende
semplicemente l’elaborazione e, al termine, viene redirezionato sul sito del Merchant per la
visualizzazione dell’esito del pagamento.

Per maggiori informazioni sugli strumenti di pagamento disponibili e le caratteristiche funzionali e


di sicurezza/garanzia di ognuno, consultare il documento allegato “Protocolli di sicurezza”.

Nota: se il Merchant supporta un solo strumento di pagamento, il Cliente viene redirezionato


direttamente sulla pagina specifica predisposta da IPG, anzichè visualizzare la SPP.

1.3. Vantaggi dell’utilizzo della redirezione


La gestione della fase di pagamento demandata a IPG permette al Merchant di raggiungere molti
obiettivi significativi:
• Non viene a conoscenza dei dati di pagamento utilizzati dal Cliente, eliminando
quindi l’onere di dover implementare tutti i requisiti di sicurezza, fisici e logici,
richiesti dalla gestione e memorizzazione di questo tipo di dati.
• Delega a IPG la gestione dei protocolli E-Commerce che intende supportare e
per i quali ha ottenuto, dalla propria banca, il convenzionamento (vedere il
documento allegato “Protocolli di sicurezza” per maggiori informazioni).
• Può personalizzare la pagina di pagamento presentata al Cliente, mantenendo lo
stesso look & feel del proprio sito e creando quindi una redirezione
trasparente per il Cliente, in modo da non intaccare il livello della shopping
experience.

Un ulteriore beneficio di questa soluzione è dato dal fatto che se in futuro dovessero verificarsi
delle evoluzioni di tali protocolli, o l’introduzione di nuovi, IPG li implementerà sulla SPP, evitando
al Merchant qualsiasi modifica al proprio sito.

Gennaio 2017 Pagina 5 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

2. Fasi di una transazione

2.1. Introduzione
Questo capitolo descrive tutti i passi di una transazione E-Commerce utilizzando la piattaforma
IPG e l’interfaccia web SPP, dapprima focalizzando sulle azioni effettuate da ognuno dei soggetti
coinvolti e poi integrandole in un flusso omogeneo e continuo di fasi successive.

2.1.1. Il punto di vista del Cliente


Il Cliente effettua un acquisto sul sito del Merchant:
• Sceglie i prodotti
• Inserisce i propri dati anagrafici per permettere la spedizione della merce, e clicca
sul pulsante “Acquista”
• Viene redirezionato sulla SPP.

N.B. Per un corretto funzionamento della SPP è necessario che il


browser abbia le impostazioni javascript attive e che supporti il
protocollo TLS 1.1

• Sceglie lo strumento di pagamento tra quelli supportati dal Merchant


• In base allo strumento selezionato, visualizza una pagina di pagamento dedicata di
IPG oppure viene redirezionato su un sito esterno, ad es.:
a. Nel caso di carta di credito, visualizza la pagina di inserimento dati carta.
Dopo aver fornito la propria carta, se questa risulta attiva al 3-D Secure,
viene redirezionato sul sito della propria banca dove è chiamato ad
inserire la password di sicurezza associata alla carta
b. Nel caso di MyBank, visualizza la pagina apposita in cui selezionare la
propria banca. Dopo tale scelta, viene redirezionato sul sito della propria
banca alla pagina di login del servizio di Internet Banking in cui dovrà
autenticarsi ed autorizzare il pagamento
c. Nel caso di MasterPass, viene redirezionato direttamente sul wallet
MasterPass per autenticarsi e scegliere la carta da usare per il pagamento
• Dopo l’attesa per l’elaborazione, viene redirezionato su una pagina specifica del
sito del Merchant la quale visualizza l’esito del pagamento
• Eventualmente riceve, se attivata l’impostazione da parte del Merchant, un
messaggio e-mail di notifica dell’avvenuto pagamento, da utilizzare come
scontrino virtuale

2.1.2. Il punto di vista del Merchant


Il Merchant riceve un ordine di acquisto dal Cliente:

Gennaio 2017 Pagina 6 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

• Invia un messaggio di inizializzazione al pagamento (PaymentInit) a IPG


• Riceve in risposta un codice univoco di pagamento (PaymentID) e l’URL al quale
redirezionare il Cliente
• Redireziona il Cliente all’URL ricevuto allegando l’informazione PaymentID (a
questo punto perde il controllo della sessione del Cliente)
• Riceve da IPG la notifica dell’esito della transazione
• Risponde con l’URL al quale desidera che il Cliente venga rediretto per la
presentazione dell’esito della transazione
• Riceve la chiamata del browser del Cliente all’URL impostato al punto
precedente (riprende il controllo della sessione del Cliente) e presenta, in
risposta, tutti i dati con l’esito del pagamento al Cliente
• Eventualmente riceve, se attiva l’impostazione, un messaggio e-mail di notifica
dell’avvenuto pagamento, da utilizzare come scontrino virtuale

2.1.3. Il punto di vista di IPG


IPG riceve un messaggio di inizializzazione (PaymentInit) dal Merchant.
• Risponde con l’URL della SPP e un codice univoco identificativo dell’ordine
(PaymentID) (*)
• Presenta la SPP al Cliente (*)
• Riceve la scelta dello strumento di pagamento selezionato dal Cliente (*)
• In base allo strumento selezionato, presenta la pagina di pagamento specifica dello
strumento oppure potrebbe redirezionare il Cliente su un sito esterno per
l’inserimento di informazioni supplementari. In questo caso attende il ritorno
del Cliente con le informazioni necessarie
• In base allo strumento selezionato, elabora la transazione o recupera l’esito del
pagamento dal sito esterno
• Invia al Merchant un messaggio di notifica dell’esito
• Riceve in ritorno l’URL su cui redirezionare il Cliente
• Redireziona il Cliente sull’URL ricevuto
• Eventualmente (se attivata l’impostazione da parte del Merchant) invia un
messaggio e-mail di notifica dell’avvenuto pagamento al Cardholder e/o al
Merchant, da utilizzare come scontrino virtuale

(*) Se il Merchant ha attivato un solo strumento di pagamento, IPG fornisce


direttamente l’URL della pagina di pagamento specifica per quello strumento.

Gennaio 2017 Pagina 7 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

2.2. Schema del flusso di informazioni


Integrando tutte le attività precedentemente descritte, ne deriva il seguente schema delle
azioni/comunicazioni che avvengono durante una transazione tra i soggetti partecipanti:

Gennaio 2017 Pagina 8 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

2.3. Descrizione degli steps


La tabella seguente analizza in dettaglio il flusso completo delle attività presenti in una transazione.

Browser Cliente Sito Web Merchant IPG Ente Esterno


1. Completamento del 2. Prepara e ritorna la
Carrello. pagina di Check Out.
3. Compila i campi
necessari e preme il
pulsante “Paga”.
4. Prepara la richiesta 5. Verifica la validità
PaymentInit con tutti i della richiesta ricevuta,
dati della transazione e salva i dati della
la invia in HTTP POST transazione, vi associa
a IPG un PaymentID, ritorna
al Merchant l’URL su
cui redirezionare il
browser del Cliente e il
PaymentID da utilizzare
nella redirezione.
6b. Richiama 6a. Salva il PaymentID
automaticamente l’URL con gli altri dati della
ricevuto. Nessuna transazione, poi
azione richiesta al redireziona il browser
Cliente. del Cliente verso l’URL
fornito da IPG con
associato il PaymentID
della transazione.
7. Verifica il PaymentID
ricevuto, prepara la SPP
con gli strumenti di
pagamento supportati
dal Merchant e la
visualizza al browser.
8. Sceglie lo strumento
di pagamento tra quelli
disponibili
9. Visualizza la pagina di
pagamento specifica
per lo strumento
selezionato (HPP / MPP
/ altro)

Gennaio 2017 Pagina 9 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

10. Inserisce le
informazioni previste e
clicca “Paga”
12. Completa le attività 11. Se previsto dallo
di autenticazione / strumento di
autorizzazione pagamento, redireziona
necessarie e ritorna il Cliente su un sito
(tramite redirezione esterno per
effettuata dal sito completare le attività di
esterno) su IPG. autenticazione /
autorizzazione,
altrimenti passa allo
step 13.
13. Invia una richiesta 14. Riceve e processa la
di autorizzazione o richiesta, e ritorna la
esito all’ente esterno, risposta a IPG.
in base allo strumento
di pagamento usato.
16. Riceve il messaggio 15. Invia un messaggio
e aggiorna lo stato POST al Merchant
della transazione con comunicando l’esito
l’esito e lo strumento della transazione.
scelto dal Cliente. Poi Se attivata
ritorna l’URL su cui l’impostazione, invia
redirezionare il un’e-mail di notifica
browser per la dell’esito al Cliente e/o
presentazione della al Merchant.
risposta finale.
17b. Richiama 17a. Redireziona il
automaticamente l’URL browser del Cliente
del Merchant. Nessuna verso l’URL indicato
azione richiesta al dal Merchant.
Cliente.
18. Riceve la richiesta e
visualizza la pagina
finale, con i dettagli
della transazione e
l’esito del pagamento.

Gennaio 2017 Pagina 10 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

3. Integrazione del Merchant

3.1. Introduzione
IPG prevede la presenza di alcune comunicazioni dirette col server del Merchant per portare a
termine le transazioni. Questo scambio di messaggi può essere implementato in due modi:
• tramite l’installazione di un apposito plug-in
• creando una propria interfaccia di comunicazione
Il plug-in si chiama e24PaymentPipe: è di facile integrazione ed è compatibile con tutti i siti
sviluppati in Java, C/C++, ColdFusion, ActiveX/COM, VB, ASP, .NET.
Nel caso in cui non sia possibile o desiderabile utilizzare il plug-in (perchè, ad es., non compatibile
con la propria piattaforma tecnologica oppure il sito sia pubblicato tramite un provider esterno in
hosting condiviso) è sempre possibile, seguendo le specifiche fornite nel seguito, creare una
propria interfaccia di comunicazione.

3.2. Messaggi tra il sito del Merchant e IPG


I messaggi server-to-server tra Sito Merchant e IPG si distinguono in due categorie:
• on-line: avvengono nel corso della transazione (sono indicati con frecce
piene di colore blu nel flusso descritto nel par. 2.2) – la loro implementazione
è obbligatoria per portare a termine correttamente la transazione
• off-line: avvengono in un momento successivo rispetto all’elaborazione della
transazione e sono utilizzati dal Merchant per scopi specifici – la loro
implementazione è facoltativa

3.2.1. Messaggi on-line


• PaymentInit: Messaggio di inizializzazione della transazione inviato dal
Merchant a IPG, il quale risponde comunicando l’URL della SPP e il
PaymentID (steps 4-5 dello schema al par. 2.2)
• NotificationMessage: Messaggio di comunicazione dell’esito della
transazione che IPG invia al Merchant, il quale risponde con l’URL al quale
redirezionare il browser del Cliente (steps 15-16 dello schema al par. 2.2)
Il messaggio PaymentInit è originato dal Merchant: per l’implementazione è possibile utilizzare il
plug-in e24PaymentPipe oppure creare una propria interfaccia seguendo le specifiche fornite nel
seguito.
Il messaggio NotificationMessage è originato da IPG: il Merchant deve predisporre una pagina
dinamica in grado di ricevere i parametri presenti nel messaggio e restituire a IPG l’URL di
redirezione finale per il browser del Cliente.

Gennaio 2017 Pagina 11 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

3.2.2. Messaggi off-line

Messaggio Payment
Al termine del pagamento, il Merchant procede all’evasione dell’ordine. Successivamente possono
rendersi necessarie varie operazioni contabili dall’accredito in conto (se la transazione non
prevedeva l’accredito automatico) al rimborso del Cliente in caso di restituzione della merce e
così via.

Se il pagamento è avvenuto tramite carta di credito o MasterPass, IPG offre la possibilità di gestire
queste esigenze in modo veloce ed efficace. E’ possibile effettuare le operazioni in 2 modi:
• Collegandosi al sito di Back Office di IPG e utilizzare le funzioni ivi presenti
• Inviando direttamente la richiesta dal proprio sistema a IPG, utilizzando il
messaggio Payment, in cui vanno inseriti tutti i parametri della transazione
originaria e impostato il codice azione opportuno. In Appendice A viene
riportato l’elenco delle operazioni contabili disponibili e la corretta sequenza
permessa.
Il messaggio Payment è originato dal Merchant: per l’implementazione è possibile utilizzare il
plug-in e24PaymentPipe oppure creare una propria interfaccia seguendo le specifiche fornite nel
seguito.

Se, invece, il pagamento è avvenuto con MyBank il Merchant deve usare strumenti alternativi per il
rimborso al cliente, ad es. effettuando un bonifico a favore del cliente dal proprio servizio di
Internet Banking, in quanto MyBank non prevede strumenti automatizzati per eseguire tali
operazioni.

Messaggio PaymentQuery
L’interfaccia PaymentQuery permette al Merchant di interrogare da remoto IPG per conoscere
in tempo reale, in ogni momento, lo stato di elaborazione di una specifica transazione.

Il messaggio PaymentQuery è originato dal Merchant e per l’implementazione si può usare uno
specifico plug-in (disponibile solo in versione Java) chiamato PaymentQueryPlugin, oppure è
necessario creare una propria interfaccia di comunicazione.

Per la descrizione tecnica di questa funzionalità si rimanda al documento


“TVB_IPG_Manuale_PaymentQuery_MBMP_<x.y.z>.pdf”.

Gennaio 2017 Pagina 12 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

3.2.3. Messaggio PaymentInit

3.2.3.1. Request

Il messaggio di richiesta viene creato dal Merchant e inviato a IPG per dare il via ad una
transazione, e prevede i seguenti campi:

Lungh.
Nome Campo Obbligatorio Descrizione
max
Codice identificativo TranPortalID, assegnato in
id S 8
fase di attivazione del servizio
password S 8 Password associata al TranPortalID
Tipo di transazione:
1=Purchase
4=Authorization

N.B.: se il Cliente perfeziona l’acquisto tramite


action S 1
MyBank, l’Action viene forzato da IPG ad “1”,
indipendentemente dall’impostazione del
Merchant. Questo avviene perchè MyBank non
prevede un meccanismo di preautorizzazione e
contabilizzazione differita.
Importo dell’operazione
amt S 10.2 (formato NNNNNNNNNN.NN
Val. max. 9999999999.99).
currencycode N 3 Codice ISO valuta – Fisso a “978” (Euro).
Codice per impostare la lingua con cui verranno
visualizzate le pagine di pagamento al Cliente. Sono
supportate le seguenti lingue:
“ITA” = italiano
“USA” = inglese
“FRA” = francese
langid S 3
“DEU” = tedesco
“ESP” = spagnolo
“SLO” = sloveno
“SRB” = serbo
“POR” = portoghese
“RUS” = russo
URL utilizzato da IPG per inviare al Merchant il
NotificationMessage.

responseURL S 255 L’URL specificato:


• non può puntare a porte diverse dalla 80 e 443
• se punta a siti protetti da un certificato SSL, il
certificato deve essere emesso da una delle

Gennaio 2017 Pagina 13 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Certification Authority elencate nel documento


TVB_IPG_Elenco_CA_autorizzate_<x.y.z>.pdf. In caso
contrario il Merchant deve fornire al Supporto
Clienti il certificato della Certification
Authority che garantisce l’autenticità del
certificato del suo sito.
URL verso il quale IPG redireziona il Cliente nel
errorURL S 384 caso in cui dovessero verificarsi degli inconvenienti
nella comunicazione del NotificationMessage.
Codice identificativo dell’ordine impostato dal
Merchant. E’ consigliabile che questo codice:
- sia univoco per ogni transazione
trackid S 255
- non superi i 35 caratteri, perché alcuni strumenti
di pagamento potrebbero troncarlo oltre tale
soglia.
Campo a discrezione del Merchant per
informazioni che desidera inserire e che vengono
restituite inalterate nel NotificationMessage.

Valorizzazione speciale:
udf1 N 255 se impostato con “SHA1” permette di ricevere
nel campo UDF1 del Notification Message il codice
hash, calcolato con algoritmo SHA-1, della carta di
credito usata dall’acquirente per il pagamento (solo
se la transazione avviene con carta di credito o
MasterPass).
Campo a discrezione del Merchant per
informazioni che desidera inserire e che vengono
restituite inalterate nel NotificationMessage.

Valorizzazione speciale:
se inizia con “PYMNINST=”<XX> indica a IPG
di visualizzare direttamente la pagina di pagamento
di uno specifico strumento di pagamento al Cliente
udf2 N 255
il quale potrà, quindi, pagare solamente con quello
strumento. <XX> può assumere i seguenti valori:
CC – per vincolare l’utente a pagare con carta di
credito
MPASS – per vincolare l’utente a pagare con
MasterPass
MYBANK – per vincolare l’utente a pagare con
MyBank
Campo a discrezione del Merchant per
informazioni che desidera inserire e che vengono
udf3 N 255 restituite inalterate nel NotificationMessage.

Valorizzazione speciale:

Gennaio 2017 Pagina 14 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

se inizia con “EMAILADDR:” la parte seguente


del campo viene interpretata come l’indirizzo e-
mail del Cliente.
Permette di preimpostare il campo e-mail che il
Cliente può inserire sulla pagina di pagamento per
ricevere l’e-mail di ricevuta della transazione
(opzione possibile solo se il Merchant ha attivato,
tramite funzione back office, l’invio dell’e-mail al
Cliente).
Campo a discrezione del Merchant per
udf4 N 255 informazioni che desidera inserire e che vengono
restituite inalterate nel NotificationMessage.
Campo a discrezione del Merchant per
informazioni che desidera inserire e che vengono
restituite inalterate nel NotificationMessage.

Valorizzazione speciale:
udf5 N 255 se inizia con “HPP_TIMEOUT=”<XX> imposta
un timeout di <XX> minuti sulla transazione.
Se il Cliente non completa il processo di
pagamento entro questo periodo, IPG non elabora
la transazione, inviando al Merchant lo specifico
codice di errore CT0001.

3.2.3.2. Response

La risposta che IPG ritorna al Merchant dopo aver ricevuto il messaggio PaymentInit e averne
verificato la validità (ID e Password del Merchant) contiene i seguenti campi:

Lungh.
Nome Campo Descrizione
max
Codice univoco identificativo dell’ordine.
Il Merchant deve inserirlo nella redirezione del Cliente, in modo
PaymentID 20
da permettere a IPG di verificare la validità dell’utente che sta
accedendo al sistema di pagamento
URL a cui il Merchant deve redirezionare il Cliente per procedere
PaymentURL 255
al pagamento

Il Merchant crea l’URL di redirezione per il browser nel modo seguente:


<PaymentURL> + “?PaymentID=” + <PaymentID>

3.2.4. Messaggio NotificationMessage

3.2.4.1. Request

Gennaio 2017 Pagina 15 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

IPG invia questo messaggio per comunicare al Merchant l’esito della transazione (se è stata
elaborata) oppure il motivo di errore (se non è stata elaborata).
Il Merchant deve predisporre una pagina dinamica in grado di ricevere il messaggio e ne comunica
l’URL a IPG (messaggio PaymentInit, campo “responseURL”). IPG usa il metodo POST per l’invio
del messaggio.

I campi presenti nel messaggio sono diversi a seconda che la transazione sia stata elaborata o che
invece si sia verificato un problema tecnico.

Caso: transazione elaborata


In questo caso il NotificationMessage consiste dei seguenti campi:

Lungh.
Nome Campo Descrizione
max
paymentid 20 Codice univoco identificativo dell’ordine
tranid 20 Codice univoco identificativo della transazione assegnato da IPG
Esito dell’operazione:
“APPROVED” = Autorizzata
“NOT APPROVED” = Non Autorizzata
“CAPTURED” = Accreditata
“NOT CAPTURED” = Non Accreditata
“DENIED BY RISK” = Non elaborata per mancato
result 20 superamento di eventuali criteri di rischio imposti dalla banca
“HOST TIMEOUT” = Non elaborata per mancata risposta dal
sistema autorizzativo
“ISSUER UNAVAILABLE” = Non elaborata per mancato
collegamento col sistema autorizzativo
“PENDING” = (valore possibile solo per transazioni MyBank) - In
attesa di ricevere l’esito della transazione da parte della banca del
Cliente
Valorizzato se la transazione è andata a buon fine, indica il codice
di identificazione del pagamento e corrisponde a:
• Codice Autorizzazione rilasciato dalla compagnia carte di
auth 35 credito – nel caso di pagamento con carta di credito o
MasterPass
• Codice di Identificazione del bonifico rilasciato dalla banca –
nel caso di pagamento tramite MyBank
(Campo valorizzato solo per pagamenti con carta di credito o
postdate 4 MasterPass)
Data della transazione (in formato mmgg)
trackid 255 Codice identificativo dell’ordine, fornito dal Merchant
(Campo valorizzato solo per pagamenti con carta di credito o
MasterPass)
ref 20
Codice della transazione rilasciato dalla banca che convenziona il
Merchant

Gennaio 2017 Pagina 16 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Campi liberi impostati dal Merchant nel PaymentInit e che IPG


udf1 – udf5 255
restituisce inalterati
(Campo valorizzato solo per pagamenti con carta di credito o
MasterPass)
responsecode 2 Codice rilasciato dall’Issuer che identifica, in caso di esito
negativo, il motivo della mancata autorizzazione
Per i dettagli si rimanda all’Appendice D.
(Campo valorizzato solo per pagamenti con carta di credito o
MasterPass)
Tipo di carta utilizzata per l’acquisto. Valori possibili:
“VISA” = Visa
cardtype 10 “MC” = Mastercard
“MAES” = Maestro
“AMEX” = American Express
“DINERS” = Diners Club
“JCB” = JCB
Indica lo strumento di pagamento utilizzato dal Cliente per la
transazione:
“CC” = Carta di credito
“VPAS” = Carta di credito, con autenticazione 3-D Secure
“MPAS” = MasterPass
payinst 10
“MYBANK” = MyBank

Per i dettagli sulle caratteristiche funzionali e i livelli di sicurezza e


garanzia dei vari strumenti si rimanda al documento allegato
“Protocolli di sicurezza”.
(Campo valorizzato solo per pagamenti con carta di credito o
MasterPass.)
Può assumere i seguenti valori:
“Y” = Il Merchant è garantito: un eventuale chargeback sulla
transazione (per motivi di frode) non darà luogo ad un addebito
liability 1 sul conto del Merchant
“N” = Il Merchant NON è garantito: potrebbe subire un addebito
in conto in caso di richiesta di chargeback (per motivi di frode).

Vedere il documento allegato “Protocolli di sicurezza” per maggiori


informazioni.
(Campo valorizzato solo per pagamenti con carta di credito o
MasterPass.)
Nazionalità della carta inserita dal cliente. L’informazione è
cardcountry 2
disponibile solo per carte Visa, MasterCard o Maestro. In tutti gli
altri casi IPG ritorna “XX”.
Per l’elenco dei country codes si rimanda all’Appendice E.
Nazionalità dell’ip address utilizzato dal cliente. Nel caso il sistema
ipcountry 2
non riesca a determinare la nazionalità, viene restituito “XX”.

Gennaio 2017 Pagina 17 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Caso: Transazione non elaborata, a causa di errori tecnici


Questa risposta copre i casi in cui la transazione non ha luogo perché il processing viene impedito
da:
• errori (ad es. l’inserimento di un tipo di carta non gestito)
Questi ordini sono visualizzati in Back Office con lo stato “AUTH ERROR”
• l’utente ha deciso di annullare il pagamento premendo il pulsante “Annulla”
Questi ordini sono visualizzati in Back Office con lo stato “CANCELED”

In questo caso il NotificationMessage consiste dei seguenti campi:


Lungh.
Nome Campo Descrizione
max
paymentid 20 Codice univoco identificativo dell’ordine
Codice dell’errore riscontrato
Error 10 Nota: nel caso di abbandono da parte dell’utente il codice errore
è “PY20090”
Descrizione dell’errore riscontrato
ErrorText 256 Nota: nel caso di abbandono da parte dell’utente la descrizione è:
“Customer canceled transaction.”

3.2.4.2. Response

In risposta, il Merchant comunica l’URL a cui vuole che il Cliente venga rediretto per la
presentazione della pagina di risposta. La stringa di testo da ritornare a IPG, che deve costituire
l’unico output della pagina dinamica predisposta dal Merchant, deve avere la seguente struttura:

“REDIRECT=” + <URL da utilizzare per la redirezione del browser>


(esempio: REDIRECT=http://www.miosito.com/result.asp?paymentID=123456)

Se per cause tecniche il browser non dovesse raggiungere l’URL di visualizzazione dell’esito, si
verrebbe a creare una situazione di disallineamento in cui il Merchant conosce l’esito della
transazione mentre il Cliente no. Il Cliente potrebbe credere che la transazione non sia andata a
buon fine e procedere con un nuovo pagamento.

Per allineare comunque il Cliente, il Merchant può predisporre (utilizzando le funzioni presenti sul
sito di Back Office) l’invio dell’e-mail di notifica dell’esito della transazione verso il Cliente.

Si consiglia, inoltre, di verificare sempre che il browser visualizzi la pagina di esito. Se ciò non
avvenisse, si potrebbe decidere di procedere in uno dei seguenti modi:
• contattare direttamente il Cliente, magari inviandogli un messaggio e-mail nel
quale gli si comunica l’esito della transazione
• effettuare lo storno/annullo automatico on-line della transazione (vedi
“Messaggio Payment”)

Gennaio 2017 Pagina 18 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Verifica autenticità del NotificationMessage


Nella realizzazione dell’interfacciamento a IPG si raccomanda d’implementare un controllo per
verificare l’autenticità dei messaggi di notifica ricevuti, al fine di evitare l’elaborazione di falsi
NotificationMessage, trasmessi da un frodatore senza che la transazione di pagamento sia stata
effettivamente completata.
A titolo puramente esemplificativo e non esaustivo si propongono i seguenti metodi:
1. Verificare che i parametri ricevuti con il NotificationMessage, non noti
all’acquirente, coincidano con quelli inviati nel messaggio PaymentInit. A tale
scopo può essere utilizzato uno dei cinque campi liberi (UDF)
opportunamente valorizzato con informazioni diverse transazione per
transazione.
2. Inserire nel campo ResponseURL del messaggio PaymentInit un URL di
notifica con un parametro in GET, con valorizzazione diversa ad ogni
transazione. In questo modo con il NotificationMessage, oltre ai parametri in
POST, sarà ricevuto anche questo parametro che potrà essere elaborato per
verificare l’autenticità della notifica.
3. Nel caso venga impostata anche la notifica via e-mail, questa può essere
utilizzata per verificare l’autenticità del NotificationMessage ricevuto,
ovviamente previo controllo dell’autenticità del mittente dell’e-mail.

ErrorURL
Se per qualunque motivo lo scambio di messaggi NotificationMessage (Richiesta IPG + Risposta
Merchant) non va a buon fine, IPG redireziona il browser del Cliente sull’ErrorURL. La situazione
che si crea è la seguente:
• La transazione è stata elaborata e potrebbe essere andata a buon fine
• Il Merchant non ha ricevuto la notifica e quindi non è allineato
• Il Cliente viene rediretto sull’ErrorURL, che chiaramente presenta
un’informazione statica in quanto il Merchant non conosce l’esito. Il Cliente vede
una risposta negativa e potrebbe essere indotto a riprovare l’acquisto

E’ consigliabile che il Merchant prepari l’ErrorURL in modo tale da ricavare


informazioni utili per poter investigare l’accaduto e informare successivamente il
Cliente sull’esito dell’acquisto. Si consiglia, se possibile, di operare come segue:
• inserire un parametro identificativo della transazione in coda all’URL, ad
esempio il TrackID, già noto al Merchant in fase di inizializzazione del
pagamento
• se un utente richiama l’ErrorURL:
1) recuperare il parametro in coda all’URL
2) dal parametro, risalire al PaymentID associato
3) utilizzare l’API PaymentQuery (vedi par. 3.2.2) per ottenere l’esito della
transazione in tempo reale
4) visualizzare la pagina al Cliente con l’esito ricevuto

Gennaio 2017 Pagina 19 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

3.2.5. Messaggio Payment


Tramite un semplice scambio di messaggi server-to-server il Merchant può effettuare in modo
automatizzato operazioni contabili da remoto (solo per transazioni pagate con carta di credito o
MasterPass).

3.2.5.1. Request

I campi da inserire nel messaggio di richiesta sono:

Obbligatori Lungh.
Nome Campo Descrizione
o max
Codice identificativo del TranPortalID, assegnato
id S 8
in fase di attivazione del servizio
password S 8 Password associata al TranPortalID
Codice univoco identificativo dell’ordine originario
paymentid S 20
creato da IPG
Codice univoco identificativo della transazione
transid S 20 originaria, creato da IPG e comunicato al Merchant
nel NotificationMessage
Tipo di operazione richiesta:
2 = Credit
3 = Reversal
action S 1 5 = Capture
9 = Void
Si rimanda all’Appendice A per le operazioni
permesse e relativi ambiti di applicazione
Importo dell’operazione in formato
NNNNNNNNNN.NN (val. max. 9999999999.99)
amt S 10.2
Si rimanda all’Appendice A per gli importi permessi
sui vari tipi di operazione
Codice identificativo dell’ordine associato dal
Merchant.
Solitamente è il codice identificativo dell’ordine di
trackid S 255
acquisto presso il sito del Merchant.
E’ consigliabile che questo codice sia univoco per
ogni transazione
Campi valorizzati a discrezione del Merchant e che
udf1 – udf5 N 255
IPG ritorna inalterati

3.2.5.2. Response

La risposta che IPG ritorna al Merchant, dopo aver validato la richiesta ed elaborato l’operazione,
contiene i seguenti campi:

Nome Campo Lungh. Descrizione

Gennaio 2017 Pagina 20 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

max
Esito dell’operazione:
“CAPTURED” = Accreditata (se Action=5)
“CAPTURED” = Riaccreditata (se Action=2)
“NOT CAPTURED” = Non Accreditata/Riaccreditata
“VOIDED” = Annullata (Action=9)
“REVERSED” = Stornata (Action =3)
Result 20
“DENIED BY RISK” = Negata per superamento limiti imposti
dalla banca
“HOST TIMEOUT” = Non elaborata per mancata risposta dal
sistema autorizzativo
“ISSUER UNAVAILABLE” = Non elaborata per mancato
collegamento col sistema autorizzativo
Codice di Autorizzazione rilasciato dalla compagnia, relativo alla
Auth 35
transazione originaria
Ref 20 Codice di Riferimento banca per l’operazione
Codice rilasciato dall’Issuer che identifica, in caso di esito
Responsecode 2 negativo, il motivo della mancata autorizzazione
Per i dettagli si rimanda all’Appendice D.
postdate 4 Data dell’operazione (formato mmgg)
tranid 20 Codice univoco identificativo dell’operazione assegnato da IPG
trackid 255 Codice identificativo della operazione associato dal Merchant
Campi valorizzati a discrezione del Merchant e che IPG ritorna
udf1 – udf5 255
inalterati

3.3. e24PaymentPipe - Descrizione


Ai merchants è fornito un pacchetto software comprendente il plug-in e24PaymentPipe, che può
essere utilizzato per la gestione dei messaggi PaymentInit e Payment descritti in precedenza. Il
plugin è disponibile in varie versioni, che coprono una vasta gamma di piattaforme utilizzate per le
applicazioni Internet, tra cui:
• Java
• ASP
• ActiveX/COM
• ColdFusion
• .NET
Il software viene fornito assieme a questo manuale, all’interno dell’e-mail di attivazione in ambiente
di test. La release più recente, sia del manuale che del software, è comunque sempre disponibile
per il download collegandosi al sito di Back Office, accedendo al menu “Sviluppatori” e
selezionando la voce “Downloads”. L’accesso al Back Office viene fornito solo in ambiente di
produzione, al momento dell’attivazione del servizio
Riportiamo qui di seguito le caratteristiche principali delle diverse versioni di e24PaymentPipe.

Gennaio 2017 Pagina 21 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

ActiveX/COM
L’oggetto ActiveX/COM e24PaymentPipe.dll fornito è provvisto di un insieme di metodi e
proprietà per effettuare transazioni in tempo reale in Internet in modo sicuro. L’oggetto può
essere utilizzato in applicazioni desktop, CGI, web server API, ASP e altre.
L’elenco completo delle proprietà supportate dal componente è presente nella documentazione
presente nella cartella “docs\dll” dello zip.
Occorre tener presente che le proprietà con accesso in sola lettura acquistano significato solo
dopo che una transazione è stata portata a termine con successo.
Nella cartella “docs\vb-example”dello zip è riportato anche un semplice esempio di utilizzo del
componente all’interno di un programma Visual Basic.

Active Server Pages


Lo stesso oggetto visto al punto precedente può essere utilizzato, con un’altra interfaccia, in
ambiente ASP tenendo presente che, poiché i progetti ASP non supportano la comunicazione ed
elaborazione asincrona, il componente e24PaymentPipe non ritornerà messaggi di stato.
Nella cartella “docs\asp-example” dello zip è riportato un semplice esempio di creazione e utilizzo
del componente da uno script in ambiente ASP.

ColdFusion
Lo stesso oggetto può ancora essere utilizzato con i progetti creati con tecnologia ColdFusion.
Nella cartella “docs\coldfusion” dello zip è presente un documento con le indicazioni per
referenziare il componente dall’interno di script ColdFusion, comprensivo di un semplice esempio.

Java
La classe Java e24PaymentPipe può essere usata in una grande varietà di ambienti di sviluppo per
realizzare applicazioni che vanno dal desktop al web e che sono platform independent. L’oggetto
e24PaymentPipe è un componente che ogni sviluppatore può utilizzare per abilitare alle transazioni
e-commerce il proprio sito web.
Il plug-in viene reso disponibile come package jar (cartella “java-package” all’interno dello zip). La
classe “e24PaymentPipeTester” contiene un metodo main e può essere utilizzata per lanciare
manualmente, impostando opportunamente i parametri, il plug-in.
Nella cartella “docs\java” dello zip si trova la documentazione in cui vengono descritte le classi e
dettagliati tutti i campi e i metodi gestiti dal plug-in.

3.4. Specifiche di interfacciamento diretto


Nel caso in cui non si disponga di una piattaforma adatta all’utilizzo del plug-in e24PaymentPipe o
si desideri creare una propria interfaccia, vengono elencate qui di seguito tutte le informazioni
relative al protocollo di comunicazione, al formato di trasmissione e ricezione dei messaggi, delle
loro variabili e dei messaggi di errore.
Il plug-in e24PaymentPipe è stato sviluppato su queste specifiche, e fornisce un’interfaccia di alto
livello già pronta per l’utilizzo.

Gennaio 2017 Pagina 22 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Specifiche del protocollo di comunicazione


• Protocollo:
https
• Encryption Level:
TLS 1.1 o superiore
• Target (action):
in ambiente di test
https://ipg-test4.constriv.com/IPGWeb/servlet/PaymentInitHTTPServlet
per il messaggio PaymentInit

https://ipg-test4.constriv.com/IPGWeb/servlet/PaymentTranHTTPServlet
per il messaggio Payment

in ambiente di produzione
https://ipg.constriv.com/IPGWeb/servlet/PaymentInitHTTPServlet
per il messaggio PaymentInit

https://ipg.constriv.com/IPGWeb/servlet/PaymentTranHTTPServlet
per il messaggio Payment
• Porta:
443
• Method: POST
• Content-Type: “application/x-www-form-urlencoded”
• Formato Trasmissione Dati:Url Encoded
• Formato Ricezione Dati:Singola stringa di testo formata dai valori dei campi,
separati da “:”

Formato Trasmissione Dati


I messaggi devono essere inviati in modalità http post come form html con coppie nome-valore, in
cui i valori sono stati predisposti in formato URL encoded. Esempi:

Messaggio PaymentInit
id=1001&password=qwerty&action=1&langid=ITA&currencycode=978&amt=1.00&responseURL=
http%3A%2F%2Fwww.merchant.com%2Fresponse&errorURL=http%3A%2F%2Fwww.merchant.co
m%2Ferror&trackid=ABC123&udf1=aa&udf2=bb&udf3=cc&udf4=dd&udf5=ee

Messaggio Payment:
id=1001&password=qwerty&action=5&currencycode=978&amt=0.50&paymentid=1122334455667
788&transid=8877665544332211&trackid=UVZ789&udf1=aa&udf2=bb&udf3=cc&udf4=dd&udf5=e
e

Gennaio 2017 Pagina 23 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Formato Ricezione Dati


La risposta di IPG ha sempre il formato di una stringa di testo in cui sono presenti i valori delle
variabili (non i nomi), separati dal carattere “:” e sempre posizionati in un ordine prestabilito; è
compito del Merchant recuperare i dati dalla stringa:

PaymentInit Response:
PaymentId:PaymentURL

Payment Response:
Result:Auth:Ref:ResponseCode:Date:TransId:TrackId:UDF1:UDF2:UDF3:UDF4:UDF5

Messaggi di risposta in condizioni di errore


Se si verifica un errore durante l’elaborazione di un messaggio inviato a IPG (PaymentInit o
Payment), il messaggio di risposta di IPG ha una formattazione speciale. La stringa inizia con
l’identificatore:
“!ERROR!”
al quale segue il codice d’errore e la descrizione dello stesso. E’ perciò fondamentale per prima
cosa, quando si riceve una risposta, verificare che la stringa inizi o meno con l’identificatore
“!ERROR!” per capire se si è verificato un errore.
In Appendice C è riportata la lista dei codici di errore di IPG.

3.5. Demo
In e24PaymentPipe.zip è stato incluso un semplice sito e-Commerce di esempio, chiamato “Colors
of Success”, che implementa le funzioni base del meccanismo di interfacciamento al servizio
Payment Gateway. Il negozio demo è disponibile in 3 tecnologie differenti:
• ASP – realizzato sia in modalità interfacciamento diretto sia agganciandosi al
plug-in e24PaymentPipe versione .dll
• PHP – realizzato in modalità interfacciamento diretto, dato che non è
disponibile un plug-in per php
• JSP – realizzato agganciandosi al plug-in e24PaymentPipe versione classe java.

Il negozio, in ciascuna delle versioni sviluppate, comprende le seguenti pagine:


• “Index”: una prima pagina che rappresenta la scelta di un prodotto a catalogo e
l’impostazione della quantità desiderata
• “Details”: la pagina di checkout, nella quale l’utente controlla gli articoli presenti
nel carrello e i prezzi, fornisce i propri dati necessari per l’evasione dell’ordine
e clicca sul pulsante “Paga” per procedere al pagamento
• “Buy”: (solo versioni ASP e JSP) attivato dal pulsante “Paga”, richiama il plug-in
fornendogli i dati dell’ordine. Il plug-in prepara ed invia a IPG il messaggio
PaymentInit. IPG e restituisce i dati per la redirezione, e questa pagina redireziona
il browser sull’URL di IPG

Gennaio 2017 Pagina 24 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

• “Pure-Buy”: (solo versioni ASP e PHP) in alternativa alla pagina precedente, questa
pagina effettua le stesse azioni senza bisogno di installare il plug-in sul proprio
server. Per utilizzarla, modificare “Details” per puntare a questa pagina (nella
action del form).
• “Receipt”: corrisponde al ResponseURL impostato nel PaymentInit. Dopo che la
transazione è stata elaborata IPG manda il NotificationMessage a questa pagina, la
quale ritorna a IPG l’URL della pagina di visualizzazione dell’esito (punto
successivo). IPG redireziona il browser all’URL ricevuto.
• “Result”: l’URL finale del Merchant che visualizza l’esito al browser.
• “Error”: in caso di errore nell’invio del NotificationMessage, il browser viene
redirezionato su questa pagina.

Per l’installazione delle demo si rimanda all’Appendice B.

Gennaio 2017 Pagina 25 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

4. Ambiente di Test

IPG mette a disposizione un ambiente di test dove il Merchant può effettuare liberamente
transazioni per predisporre correttamente l’interfacciamento in vista del passaggio in produzione.
L’ambiente di test è sempre disponibile, anche se non può esserne garantita la disponibilità H24, a
causa d’interventi di manutenzione correttiva o evolutiva che potrebbero renderlo
temporaneamente inutilizzabile, senza preavviso.

Variabili da impostare per la creazione del messaggio PaymentInit


Se si utilizza il plug-in, per la connessione a IPG di test usare i valori seguenti:
• address: ipg-test4.constriv.com
• context: /IPGWeb
• port: 443
• SSL: 1 (usato solo dal plug-in java)

Se invece si utilizza l’interfacciamento diretto l’indirizzo completo per creare la connessione è il


seguente:
• https://ipg-test4.constriv.com/IPGWeb/servlet/PaymentInitHTTPServlet

Le variabili da impostare in modo fisso sono le seguenti:


• id: comunicato tramite e-mail assieme a questo documento
• password: comunicato tramite e-mail assieme a questo documento

Gli altri parametri possono essere definiti liberamente.

4.1. Casi di test raccomandati


Si raccomanda di effettuare almeno i seguenti test, che rappresentano le casistiche reali più
frequenti, prima di inviare al Supporto Clienti la conferma di fine test per richiedere il passaggio in
produzione.

Test n° C1 – Transazione con carta di credito – esito positivo


Una volta visualizzata la SPP, selezionare “carta di credito” e di seguito utilizzare la seguente carta
Numero Scadenza CVV2
4539990000000012 qualsiasi data futura qualsiasi numero di 3 o 4 cifre
Verificare che:

Gennaio 2017 Pagina 26 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

• il NotificationMessage sia stato ricevuto correttamente con tutti i campi


previsti (PaymentID, TransID, TrackID, postdate, resultcode, auth, ref,
responsecode, udf1, udf2, udf3, udf4, udf5, cardtype, payinst, liability).
• il NotificationMessage sia autentico, utilizzando uno dei metodi specificati nel
paragrafo “Verifica autenticità del NotificationMessage”.
• la transazione abbia esito positivo (resultcode=“APPROVED” se si è usato
Action=4, “CAPTURED” se si è usato Action=1)
• il browser sia stato re-direzionato correttamente all’indirizzo fornito in
risposta al NotificationMessage precedente.

Test n° C2 – Transazione con carta di credito – esito negativo


Una volta visualizzata la HPP, utilizzare la seguente carta
Numero Scadenza CVV2
4539990000000020 qualsiasi data futura qualsiasi numero di 3 o 4 cifre
Verificare che:
• il NotificationMessage sia stato ricevuto correttamente con tutti i campi
previsti (PaymentID, TransID, TrackID, postdate, resultcode, auth, ref,
responsecode, udf1, udf2, udf3, udf4, udf5, cardtype, payinst, liability)
• la transazione abbia esito negativo (resultcode=“NOT APPROVED” se si è
usato Action=4, “NOT CAPTURED” se si è usato Action=1)
• il browser sia stato re-direzionato correttamente all’indirizzo fornito in
risposta al NotificationMessage precedente

Test n° C3 – Transazione con carta di credito – non elaborata per dati non corretti
Una volta visualizzata la HPP, utilizzare la seguente carta:

Numero Scadenza CVV2


4999000055550000 qualsiasi data futura qualsiasi numero di 3 o 4 cifre
Verificare che:
• il NotificationMessage sia stato ricevuto correttamente con tutti i campi
previsti (PaymentID, Error, ErrorText)
• il campo “Error” abbia valore “GW00853” e che il campo “ErrorText”
contenga la descrizione dell’errore “GW00853-Numero Carta non valido.”
• il browser sia stato re-direzionato correttamente all’indirizzo fornito in
risposta al NotificationMessage precedente

Test n°4 – Transazione annullata dall’utente


Una volta visualizzata la HPP, premere il pulsante “Annulla”.

Verificare che:

Gennaio 2017 Pagina 27 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

• il NotificationMessage sia stato ricevuto correttamente con tutti i campi previsti


(PaymentID, Error, ErrorText)
• il campo “Error” contenga il valore “PY20090” e che il campo “ErrorText”
contenga la descrizione dell’errore “Customer canceled transaction.”
• il browser sia stato re-direzionato correttamente all’indirizzo fornito in risposta
al NotificationMessage precedente

Test n° C5 (opzionale) – Transazione con carta di credito – Operazioni Contabili


E’ possibile testare l’effettuazione di operazioni contabili post-transazionali in modo automatizzato
da remoto (messaggio “Payment”), usando le seguenti impostazioni.
Connessione: se si utilizza il plug-in non vi sono modifiche ai parametri, mentre con
l’interfacciamento diretto l’indirizzo cui puntare è il seguente:
• https://ipg-test4.constriv.com/IPGWeb/servlet/PaymentTranHTTPServlet
Principali parametri: dopo aver effettuato un test di tipo C1 con esito positivo, riutilizzare alcuni
parametri per l’invio della richiesta:
• trackID: lo stesso trackID utilizzato per la transazione originaria
• transID: il transID fornito da IPG per la transazione originaria
• paymentID: il paymentID fornito da IPG per la transazione originaria
Per impostare il tipo di richiesta desiderato (Capture, Credit, Void, Reversal) utilizzare il campo:
• action: vedere in Appendice A le operazioni contabili consentite in base al tipo di
transazione orginaria.
Verificare che:
• la risposta sia stata ricevuta correttamente e riporti tutti i campi descritti al par.
3.2.5.2

Test n° MB1 – Transazione MyBank – esito positivo


Una volta visualizzata la SPP, selezionare l’opzione MyBank. Nella pagina successiva selezionare una
banca qualunque dalla combo box e premere OK. Arrivati sul sito di Internet Banking fittizio
cliccare in sequenza “Login”, “Confirm”, e “OK”.

Al termine dell’elaborazione, verificare che:


• il NotificationMessage sia stato ricevuto correttamente con tutti i campi
previsti (paymentid, tranid, trackid, result, auth, udf1, udf2, udf3, udf4, udf5,
payinst).
• il NotificationMessage sia autentico, utilizzando uno dei metodi specificati nel
paragrafo “Verifica autenticità del NotificationMessage”.
• i dati riportino:
a. payinst = “MYBANK”
b. result = “CAPTURED”
c. auth = “STATUS”

Gennaio 2017 Pagina 28 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

• il browser sia stato redirezionato correttamente all’indirizzo fornito in risposta


al NotificationMessage precedente.

Test n° MP1 – Transazione MasterPass – esito positivo


Una volta visualizzata la SPP, selezionare l’opzione MasterPass. Arrivati su MasterPass:
Alla Login Page inserire le credenziali:
- Email address: joe.test@email.com
- Password: abc123
Alla domanda di sicurezza rispondere con “fido”.
Nella pagina successiva lasciare selezionati i valori di carta e shipping address selezionati e premere
“finish shopping”.

Al termine dell’elaborazione, verificare che:


• il NotificationMessage sia stato ricevuto correttamente con tutti i campi
previsti (PaymentID, TransID, TrackID, postdate, resultcode, auth, ref,
responsecode, udf1, udf2, udf3, udf4, udf5, cardtype, payinst, liability) con
a. payinst = “MPASS”
• il NotificationMessage sia autentico, utilizzando uno dei metodi specificati nel
paragrafo “Verifica autenticità del NotificationMessage”.
• il browser sia stato redirezionato correttamente all’indirizzo fornito in risposta
al NotificationMessage precedente.

Gennaio 2017 Pagina 29 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

5. Personalizzazione delle pagine di pagamento

La Selection Payment Page (e pagine successive HPP, MPP, …) presentata da IPG ai buyers può
essere personalizzata dal Merchant.

Nota Importante: la disponibilità di questa funzione varia in funzione della banca proponente il
servizio.

In assenza di personalizzazione, la SPP viene proposta con il Layout e la grafica standard


predisposti dalla banca.

Il Merchant può applicare la personalizzazione in totale autonomia utilizzando apposite funzionalità


presenti nel sito di Back Office che permettono di:

• Selezionare per l’utilizzo uno dei due template grafici a disposizione, uno
sviluppato principalmente in senso verticale (“Layout1”), l’altro in orizzontale
(“Layout2”)
• Variare numerose impostazioni grafiche (colori di sfondo, del testo, e dei pulsanti;
tipo di font; bordi e sfondo dei campi di input; spessore, colore e curvatura del
bordo della form; spessore e curvatura dei pulsanti, ecc)
• Caricare un’immagine (banner, logo ecc..), e specificarne il posizionamento (solo
su template #1)
• Impostare una linea di testo con i dati di riferimento aziendali o altro messaggio
per gli utenti (solo su template #1)
• Caricare un’immagine di sfondo, specificandone la posizione nello schermo e
l’eventuale ripetizione, e impostare il grado di trasparenza della form per far
intravvedere lo sfondo sottostante

Ogni modifica apportata viene visualizzata in tempo reale in una HPP di esempio (“sample page”)
attiva durante l’utilizzo delle funzionalità di personalizzazione, mentre nessun effetto si ha sulla
pagina reale di produzione.

Un pulsante “Salva”, se premuto, fa in modo che le modifiche apportate vengano propagate


immediatamente alla SPP di produzione, a meno che la banca non preveda un processo di
approvazione. In quest’ultimo caso:
• il pulsante “Salva” implica solamente il salvataggio delle modifiche apportate alla
Sample Page (per una ripresa dei lavori in un momento successivo)
• compare un nuovo pulsante “Invia per approvazione” che, se premuto, pone la
personalizzazione in stato Pending fino al momento dell’approvazione da parte
della banca. In questo stato, la personalizzazione è “congelata”, cioè non può
essere ulteriormente modificata fino alla decisione della banca
• Al momento della decisione:

Gennaio 2017 Pagina 30 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

a. il Merchant riceve una notifica in Home Page del Back Office riguardo la
decisione presa. In caso di rifiuto, viene visualizzato il motivo dello
stesso. Il Merchant riceve anche la stessa notifica tramite messaggio e-
mail
b. se la decisione è positiva, la personalizzazione diviene automaticamente
operativa senza nessun intervento da parte del Merchant
c. in ogni caso, la personalizzazione viene sbloccata e può essere
modificata

Il Merchant può aggiornare la propria personalizzazione ogniqualvolta lo ritenga opportuno senza


alcuna limitazione. Questo permette di applicare personalizzazioni temporanee in corrispondenza
di specifiche campagne promozionali o per altre esigenze di business.

E’ altresì possibile annullare la personalizzazione realizzata (tasto “Revert”). In questo caso ai


Cardholders viene presentata la SPP con la veste grafica standard impostata dalla banca.

Per tutti i dettagli sulle funzioni di personalizzazione disponibili e il loro funzionamento si rimanda
al Manuale Utente per l’utilizzo del Back Office, che viene fornito al momento dell’attivazione del
servizio.

5.1. Personalizzazione su Smartphone e Tablet

La SPP è realizzata con tecnologia responsive. Questo significa che la visualizzazione della pagina
avviene in modo ottimale anche per gli utenti che effettuano pagamenti utilizzando lo smartphone
o il tablet. La personalizzazione applicata viene fedelmente riportata anche su questi dispositivi
senza nessuna attività addizionale.

Per quanto riguarda in particolare gli smartphones, è necessario precisare che IPG visualizzerà
sempre il Layout1 (quello a sviluppo verticale) indipendentemente dal layout scelto dal Merchant
(scelta che ha valore, quindi, per gli utenti che utilizzano dispositivi desktop o tablet). Si
raccomanda, pertanto, di procedere sempre alla personalizzazione di entrambi i layout.

5.2. Esempio di Layout1 e Layout2

Gennaio 2017 Pagina 31 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Appendice A
Gestione contabile delle transazioni

In una transazione con carta di credito su Internet, il movimento di denaro dall’acquirente


(Cardholder) verso il venditore (Merchant) può avvenire nel momento stesso della transazione o
in un momento successivo.
IPG permette al Merchant di stabilire a livello di singola transazione quale dovrà essere il sistema
di contabilizzazione da seguire.
IPG permette altresì di effettuare tutta una serie di operazioni successive alla transazione, come
l’annullo o il rimborso dell’importo al Cardholder. Ogni operazione descritta può essere effettuata
in due modi distinti, a seconda delle esigenze e della propria struttura:
• Modalità automatizzata: l’operazione si concretizza da remoto con un messaggio
server-to-server (messaggio “Payment”) dal sistema del Merchant a IPG. Si può
utilizzare indifferentemente allo scopo il Plugin e24PaymentPipe o
l’interfacciamento diretto.
• Modalità Manuale: l’operazione si concretizza collegandosi al sito di Back Office di
IPG, selezionando la transazione di interesse e richiedendo l’operazione.

Contabilizzazione Immediata
Questa modalità viene attivata se nel messaggio PaymentInit il Merchant imposta il parametro
Action=1. La transazione prende in questo caso il nome di “Purchase”.
Se la transazione ha esito positivo il Merchant viene accreditato con data contabile pari alla data
della transazione.
La modalità immediata dovrebbe essere adottata esclusivamente nel caso di vendita di servizi di cui
l’acquirente comincia ad usufruire immediatamente.
Successivamente alla transazione originaria, in caso di reso della merce o altri fattori, è possibile:
• Stornare (“Reversal”) la transazione: l’intero importo viene rimborsato al
Cardholder e il Merchant viene addebitato per lo stesso importo. Se l’operazione
avviene nella stessa giornata dell’acquisto è possibile (a discrezione dell’ente
emittente della carta) ripristinare la disponibilità di spesa mensile della carta.
L’operazione di Reversal si ottiene impostando il paramentro Action=3.
• Riaccreditare (“Credit”) totalmente o parzialmente la transazione: e’ possibile
effettuare più riaccrediti successivi su una stessa transazione; ma l’importo totale
dei riaccrediti non può comunque superare l’importo contabilizzato. L’operazione
di Credit si ottiene impostando il parametro Action=2.

Gennaio 2017 Pagina 32 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Lo schema temporale completo comprendente tutte le azioni possibili è il seguente:

Contabilizzazione differita
Questa modalità viene attivata se nel messaggio PaymentInit il Merchant imposta il parametro
Action=4. La transazione prende in questo caso il nome di “Authorization”.
Se la transazione ha esito positivo il plafond della carta di credito del Cardholder viene bloccato
per l’importo della transazione.
• Con la modalità differita il Merchant deve richiedere espressamente l’accredito
(detto “Capture”) della transazione, che di solito avviene al momento
dell’evasione dell’ordine. Pertanto l’importo da accreditare può essere impostato
sulla base della merce effettivamente inviata (comunque non superiore
all’importo inizialmente bloccato). L’operazione di Capture si ottiene impostando
il paramentro Action=5.
• Se si verificano dei problemi il Merchant, anziché richiedere l’accredito, può
annullare (detto “Void”) la transazione. Se la richiesta è effettuata nella stessa
giornata della transazione iniziale, il plafond della carta di credito utilizzata può (a
discrezione dell’ente emittente) essere ripristinato immediatamente).
L’operazione di Void si ottiene impostando il parametro Action=9.
• In un momento successivo all’ accredito l’acquirente potrebbe restituire tutte o
parte delle merci acquistate al Merchant. In questo caso il Merchant procede al
riaccredito (detto “Credit”), totale o parziale, dell’importo precedentemente
accreditato. E’ possibile effettuare più riaccrediti su una stessa transazione; ma
l’importo totale dei riaccrediti non può comunque superare l’importo
accreditato. L’operazione di Credit si ottiene impostando il parametro Action=2.

Gennaio 2017 Pagina 33 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Lo schema temporale completo comprendente le possibili azioni è il seguente:

Gennaio 2017 Pagina 34 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Appendice B
Installazione del Demo

VERSIONE ASP

Registrazione dll
• Estrarre i files forniti nel package e24PaymentPipe.zip in una nuova directory, ad
es. “c:\e24plugin”
• Aprire una finestra DOS e andare alla directory “c:\e24plugin\DLL\Release”
• Digitare il seguente comando: “regsvr32 e24PaymentPipe.dll”
• Dovrebbe comparire una finestrella che segnala il successo dell’operazione.
Cliccare allora su “OK” per chiuder la finestra.
• Se la finestra segnala un errore, chiuderla. Tornare poi alla finestra DOS, puntare
alla directory “ c:\e24plugin\DLL\Debug”, e ritentare il comando: “regsvr32
e24PaymentPipe.dll”

Installazione sito demo


• Installare Microsoft IIS, se non presente.
• Copiare i files forniti nella cartella c:\e24plugin\demo-asp in una nuova directory,
“c:\inetpub\wwwroot\demo”
• Tramite la Console di IIS creare un nuovo sito “MerchantDemo”:
• Nella finestra “Properties->Home Directory” impostare nel Local Path il
percorso della directory “demo”
• In Execute Permissions impostare “Scripts only”
• Riavviare IIS
• Aprire un browser e puntare all’URL: http://localhost:port/demo/index.asp (dove
port è la porta TCP configurata per IIS)

Versione jsp
• Copiare il file “demo-jsp.war” presente nella cartella c:\e24plugin\demo-jsp sotto
la cartella “webapps” (o equivalente cartella base in cui inserire le web
application) del proprio application server.
• Riavviare l’application server
• Aprire un browser e puntare all’URL:
• http://localhost:port/demo-jsp/index.jsp (dove port è la porta TCP configurata
per l’application server)

Gennaio 2017 Pagina 35 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Versione php
• Copiare i files forniti nella cartella c:\e24plugin\demo-php sotto la cartella
configurata per le applicazioni php.
• Creare un website “demo-php” sul web server utilizzato in collegamento con il
motore php.
• Riavviare il web server utilizzato in collegamento con php.
• Aprire un browser e puntare all’URL: http://localhost:port/demo-php/index.php
(dove port è la porta TCP configurata sul web server per il sito demo-php)

Gennaio 2017 Pagina 36 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Appendice C
Lista dei Codici di Errore

PY10000=Internal error PY20087-User tried to use an unauthor. payment instr.


PY20000=Missing required data. PY20090=Customer canceled transaction.
PY20001=Invalid Action Type. GV00001=Unknown 3-D Secure version
PY20002=Invalid amount. GV00002=Cardholder not enrolled
PY20003=Invalid Order Status. GV00003=Not a 3-D Secure Card
PY20004=Non Numeric Card Number. GV00004=PARes status not successful
PY20005=Missing Card Number. GV00005=Certificate chain validation failed
PY20006=Invalid Brand. GV00006=Certificate chain validation error
PY20007=Invalid Order Status. GV00007=Signature validation failed
PY20008=Invalid Currency Code. GV00008=Signature validation error
PY20009=Transaction Not Found. GV00009=Invalid root certificate
PY20010=Invalid Merchant URL. GV00010=Missing data type
PY20011=Invalid Merchant Error URL. GV00011=Invalid expiration date
PY20012=Invalid Track ID. GV00012=Invalid action type
PY20013=Invalid Language Code. GV00013=Invalid Payment ID
PY20014=Invalid User Defined Field. GV00014=Merchant not enabled to SafeKey
PY20015=Invalid Card Name. GV00100=Invalid action type
PY20016=Invalid Card Address. GV00101=Missing data type
PY20017=Invalid Zip Code. GV00102=Invalid Amount
PY20018=Invalid Card Verification Code. GV00103=Invalid Brand
PY20019=Invalid Transaction ID. GV00104=Payment ID not numeric
PY20020=Invalid Payment Tokens for Account.
PY20021=Invalid Customer EMail Address. CM00001=External message timeout.
PY20022=The Acceptance of the Privacy Statement is CM00002=External message system error.
Mandatory
PY20023=Missing language code CM00026=External connection ID required.
PY20024=Inactive Terminal CM00027=External connection description required.
PY20049=Transaction failed with a PARes Error CM00028=External connection Protocol code required.
PY20050=Card Number Encryption Failure. CM00029=External connection Formatter class name
invalid.
PY20060=Card Number Decryption Failure. CM00030=External connection Protocol not supported.
PY20080=Invalid Payment Page Style File. CM00050=Institution has Merchants.
PY20081=Invalid Payment Page Header File. CM00051=Institution ID required.
PY20082=Invalid Payment Page Footer File. CM00052=Invalid Institution Data Encryption Key Name.
PY20083=Invalid Payer Authentication Response CM00053=Missing Institution Data Encryption Key.
Message.
PY20084=Invalid Payment ID. CM00054=Institution Data Encryption Key does not
exist.
PY20085=Invalid Payment Status. CM00055=Missing Institution Data Encryption Key.
PY20086= Invalid Payment Instrument. CM00056=Institution Data Encr. Key does not exist.

Gennaio 2017 Pagina 37 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

CM00057=Institution User Security Admin class error. GW00170=Terminal ID mismatch.


CM90000=Database error. GW00171=Payment Instrument mismatch
CM90001=Database configuration error. GW00172=Card Verification Code Mismatch.
CM90003=No Records Found. GW00173=Currency Code mismatch.
CM90004=Duplicate found error. GW00174=Card Number mismatch.
CM90005=TimeStamp Mismatch error. GW00175=Invalid Result Code.
CM90100=Message formatter class failure. GW00176=Failed Previous Captures check.
GW00100=Institution ID required. GW00177=Failed Capture Greater Than Auth check.
GW00101=Brand ID required. GW00178=Failed Void Greater Than Original Amount
check.
GW00102=Brand Description required. GW00179=Failed Previous Voids check.
GW00103=BIN range overlaps an existing brand. GW00180=Failed Previous Credits check.
GW00104=Start BIN required. GW00181=Failed Credit Greater Than Debit check.
GW00105=BIN length too long. GW00182=Failed to Load Merchant Record for
Validation.
GW00106=Start and end BIN lengths differ. GW00183=Card Verification Digit Required.
GW00107=End BIN not greater then Start BIN. GW00184=Failed to Load Terminal Record for
Validation.
GW00108=Invalid Brand ID. GW00185=Invalid Authentication Token.
GW00109=Invalid Description. GW00186=Invalid Transaction Identifier (XID).
GW00110=Invalid Payment Intrument List. GW00187=Invalid Electronic Commerce Indicator.
GW00111=Invalid Start Bin. GW00188=Missing Electronic Commerce Indicator.
GW00112=Invalid End Bin. GW00189=Missing Authentication Token.
GW00113=Terminal exists for this Brand. GW00190=Missing Transaction Identifier (XID).
GW00150=Missing required data. GW00191=Void After Capture Not Allowed
GW00151=Invalid Action type GW00200=Address verification failed.
GW00152=Invalid Transaction Amount. GW00201=Transaction not found.
GW00153=Invalid Transaction ID. GW00202=Hack attempt detected.
GW00154=Invalid Terminal ID. GW00203=Invalid access: Must use POST method.
GW00155=Invalid Batch Track ID. GW00204=Invalid Original Transaction ID.
GW00156=Batch track ID not unique. GW00205=Invalid Subsequent Transaction.
GW00157=Invalid Payment Instrument. GW00250=Transaction denied: Negative Card
GW00158=Card Number Not Numeric. GW00251=Maximum transaction count exceeded.
GW00159=Card Number Missing. GW00252=Maximun transaction volume exceeded.
GW00160=Invalid Brand. GW00253=Maximum credit volume exceeded.
GW00161=Invalid Card/Member Name data. GW00254=Maximum card debit volume exceeded.
GW00162=Invalid User Defined data. GW00255=Maximum card credit volume exceeded.
GW00163=Invalid Address data. GW00256=Maximum card transaction count exceeded.
GW00164=Invalid Zip Code data. GW00257=Maximum transaction amount exceeded.
GW00165=Invalid Track ID data. GW00258=Transaction denied: Negative BIN
GW00166=Invalid Card Number data. GW00259=Transaction denied: Declined Card
GW00167=Invalid Currency Code data. GW00260=Transaction denied: Credits exceed
Captures
GW00168=Institution ID mismatch. GW00261=Transaction denied: Captures exceed
Authorizations
GW00169=Merchant ID mismatch. GW00300=Institution ID required.

Gennaio 2017 Pagina 38 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

GW00301=Risk Profile ID required. GW00378=Currency Code is invalid.


GW00302=Currency code required. GW00379=View Tran Detail is invalid.
GW00303=Risk Profile in use. GW00380=Merchant ID not numeric.
GW00304=Invalid Risk Profile ID. GW00381=Merchant Password data invalid.
GW00305=Invalid Currency Code. GW00382=Merchant Category Description invalid.
GW00306=Invalid Risk Profile setting. GW00383=Merchant Password Confirmation invalid.
GW00307=Invalid Max floor limit/$ amount. GW00384=Merchant New Password invalid.
GW00308=Invalid Max floor limit transaction count. GW00385=Merchant New Password is required.
GW00309=Invalid Max daily processing amount. GW00386=Merchant New Confirm Password is
required.
GW00310=Invalid Max credit processing amount. GW00387=Merchant User Password is expired.
GW00311=Invalid Max 24hr debit amount. GW00388=Merchant User Name is required.
GW00312=Invalid Max 24hr credit amount. GW00389=Merchant User Password Confirmation is
required.
GW00313=Invalid Max transaction count daily. GW00390=Password and confirmation password do not
match.
GW00350=Merchant has terminals. GW00391=Merchant User password length is too short.
GW00351=Merchant ID required. GW00392=Merchant User Status is required.
GW00352=Institution ID required. GW00393=Merchant User Status is invalid.
GW00353=Invalid Login. GW00394=Merchant User Password is required.
GW00354=Invalid Login. GW00395=Password and confirmation password do not
match.
GW00355=New password mismatch. GW00396=Merchant User new password same as old.
GW00356=New password same as old. GW00397=Merchant User inactive.
GW00357=Console password required. GW00398=Merchant User Password length too long.
GW00358=Invalid Login. GW00399=Merchant User ID is invalid.
GW00359=ISO Country code is invalid. GW00400=Merchant User Password is invalid.
GW00360=Website address in invalid. GW00401=Merchant New Password is invalid.
GW00361=Console Password Confirmation required. GW00402=Merchant User Name is invalid.
GW00362=Console Password Confirmation invalid. GW00403=Merchant Password Expire Code is invalid.
GW00363=Password Confirmation mismatch. GW00404=Merchant Password Expires Date is invalid.
GW00364=Name is invalid. GW00405=Merchant exists with this Merchanat
Category.
GW00365=Institution ID is invalid. GW00407=Category code must be numeric.
GW00366=Merchant ID is invalid. GW00408=Category code must be four digits.
GW00367=Category Code is invalid. GW00420=Currency Code data in not available.
GW00368=Address is invalid. GW00421=Currency Code minor digits is invalid.
GW00369=City is invalid. GW00422=Error Packing Message to Host.
GW00370=State is invalid. GW00450=Institution ID required.
GW00371=Country is invalid. GW00451=Merchant ID required.
GW00372=Web Site is invalid. GW00452=Terminal ID required.
GW00373=Zip Code is invalid. GW00453=TranPortal ID required.
GW00374=Phone is invalid. GW00454=TranPortal password required.
GW00375=FAX is invalid. GW00455=TranPortal ID not unique.
GW00376=Email is invalid. GW00456=Invalid TranPortal ID.
GW00377=Contact is invalid. GW00457=Terminal Action not supported.

Gennaio 2017 Pagina 39 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

GW00458=Invalid Transaction Attempt. GW00610=Invalid Card Number.


GW00459=Terminal not active. GW00611=Invalid Negative Reason.
GW00460=TranPortal ID required. GW00612=Invalid Card Bin.
GW00461=Invalid Transaction amount. GW00613=Invalid Negative Reason.
GW00462=Invalid Tranportal Password. GW00614=Please click correct button or tab to move
focus to correct button and press enter.
GW00463=Invalid Terminal Institution ID. GW00700=No processes available.
GW00464=Invalid Terminal Merchant ID. GW00701=Batch not processed.
GW00465=Invalid Terminal Termainl ID. GW00702=Batch could not be started.
GW00466=Invalid Terminal Description. GW00703=Institution ID required.
GW00467=Invalid Terminal External Connection ID. GW00704=Batch ID not numeric.
GW00468=Invalid Terminal Risk Profile. GW00705=Batch ID required.
GW00469=Invalid Terminal Currency Code List. GW00706=Invalid Batch Response File Name
GW00470=Invalid Terminal Action Code List. GW00750=Error hashing card number.
GW00471=Invalid Terminal Payment Instrument List. GW00751=Search results greater than maximum
number of records allowed. Increase search granularity
and re-submit.
GW00472=Invalid Terminal Brand List. GW00850=Missing required data.
GW00473=Invalid Terminal Option Code List. GW00851=Invalid Action Type.
GW00474=Invalid Terminal Risk Flag. GW00852=Invalid Card Number.
GW00475=Invalid Terminal Address Verification List. GW00853=Invalid Card Number.
GW00476=Invalid Terminal Tranportal ID. GW00854=Invalid Expiration Date.
GW00477=Invalid Terminal Status. GW00856=Invalid Card Verification Code.
GW00478=Invalid Terminal Card Acceptor ID. GW00857=Invalid Electronic Commerce Indicator.
GW00479=Invalid Terminal Card Acceptor Terminal ID. GW00858=Missing required data - CVV
GW00480=Invalid Terminal Acquirer Institution. GW00859=Missing required data - Expiry Year
GW00481=Invalid Terminal Base24 Terminal Data. GW00860=Missing required data - Expiry Month
GW00482=Invalid Terminal Retailer ID. GW00861=Missing required data - Cardholder Name
GW00483=Invalid Terminal Retailer Group ID. GW00862=Missing required data - Card Address
GW00484=Invalid Terminal Retailer Region ID. GW00863=Missing required data - Card Postal Code
GW00485=Invalid Terminal Cutover Hour. GW00870=Missing required data.
GW00486=Invalid Terminal Cutover Minute. GW00871=Invalid Action Type.
GW00489=Type of payment is not included in Terminal GW00872=Invalid Card Number.
payment instruments list.
GW00550=Category Code missing or invalid. GW00873=Invalid Card Number.
GW00600=Card number required. GW00874=Invalid Expiration Date.
GW00601=Card BIN required. GW00875=Missing required data.
GW00602=Invalid BIN length. GW00876=Invalid Card Verification Code.
GW00603=Institution ID required. GW00877=Invalid Electronic Commerce Indicator.
GW00604=Merchant ID required. GW00878=Missing required data - CVV
GW00605=Terminal ID required. GW00879=Missing required data - Expiry Year
GW00606=Card number required. GW00880=Missing required data - Expiry Month
GW00607=Invalid Card Number. GW00881=Missing required data - Cardholder Name
GW00608=Invalid Currency Code. GW00882=Missing required data - Card Address
GW00609=Invalid Decline Reason. GW00883=Missing required data - Card Postal Code

Gennaio 2017 Pagina 40 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

GW00884=Missing required data - PIN GW01062=Ivalid Minor Digits Range.


GW00950=Batch Upload Directory Required. GW01063=Currency Code Not Numeric.
GW00951=Batch Download Directory Required. GW01064=Currency Code Not Valid ISO Code.
GW00952=Batch Archive Directory Required. GW01065=Invalid Minor Digits.
GW00953=Access Log Retention Days Required. GW01066=Invalid Amount.
GW00954=Transaction Log Retention Days Required. GW01067=Invalid Currency Code Data.
GW00955=Declined Card Retention Minutes Required. GW01068=Invalid Currency Description Data.
GW00956=Declined Card Maximum Count Required. GW01069=Invalid Minor Digits Data.
GW00957=Access Log Retention Days Invalid. GW01070=Invalid Currency Symbol Data.
GW00958=Transaction Log Retention Days Invalid. GW01071=Terminal exists with this Currency Code.
GW00959=Declined Card Retention Minutes Invalid. GW01072=Merchant exists with this Currency Code.
GW00960=Declined Card Maximum Count Invalid. GW01100=Option Invalid Attempt Lockout is invalid.
GW00961=Multiple Capture Flag Invalid. GW01101=Option Maximum Password Days is invalid.
GW00962=Multiple Capture Amount Flag Invalid. GW01102=Option Minimum Password Length is invalid.
GW00963=Multiple Void Flag Invalid. GW01103=Option Maximum Password Length is invalid.
GW00964=Compare Void Amount Flag Invalid. GW01104=Option Min Password Length is greater than
the Max length.
GW00965=Multiple Credit Debit Flag Invalid. GW01180=Hex required.
GW00966=Compare Credit Debit Amount Flag Invalid. GW01181=Invalid Key length.
GW00967=Batch Upload Directory Invalid. GW01182=Key encryption failed.
GW00968=Batch Download Directory Invalid. GW01190=-TranPortal Password required.
GW00969=Batch Archive Directory Invalid. GW01191=-TranPortal Password invalid.
GW00970=Invalid Terminal Cutover Hour. GW01192=-Password encryption failed.
GW00971=Invalid Terminal Cutover Minute. GW01193=-Terminal Alias invalid.
GW00972=Card Number Mask Required. GW01194=Error Generating Merchant Resource.
GW00973=Card Number Mask Invalid. GW01195=Terminal Alias required.
GW00975=FAQ Question ID required. GW01220=Institution ID Required.
GW00976=Invalid Language ID. GW01221=Transaction ID Required.
GW00977=Invalid Question ID. GW01222=Transaction Amount Required.
GW00978=Invalid Question content. GW01230=No Rows Selected
GW00979=Invalid Answer content. GW01240=Transaction denied: Merchant not allowed to
capture greater then authorized amount
GW00990=Card Number Encryption Failure. GW01241=Transaction denied: Merchant trying to
capture greater then authorized percentage over
authorization
GW00997=Batch Action invalid.
GW01000=Secure Context retrieval error. CW00000=Invalid date (use format AAAA-MM-GG).
GW01020=Invalid Languange ID. CW00001=Unavailable date.
GW01021=Invalid System News Header. CW00002=I/O error.
GW01022=Invalid System News Body.
GW01040=Invalid Languange ID. CT00001=Expired Session
GW01041=Invalid Merchant Guideline Header. CT00002=Session Timeout format error
GW01042=Invalid Merchant Guideline Body. CT00100=Supplier TermId not linked to MKP TermId
GW01060=Currency Code Required. CT00101=SUP tot amount not equal to MKP amount
GW01061=Institution ID Required. CT00102=MD5 UserId is Null

Gennaio 2017 Pagina 41 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

CT00103=MD5 UserId is Not valid


CT00105=TermId has zero preauth days
CT00106=USER-PAN pair not valid MPI0001=Root element invalid
CT00111=Order denied due to invalid LIDL card MPI0002=Message element not a defined message
number
CT99999=constriv.com invalid IP Address. Please use MPI0003=Required element missing
the domain name and refresh your system DNS cache.
MPI0004=Critical element not recognized
SM00001=CliNumber required. MPI0005=Format/Value of one or more elements is
invalid according to the specification
SM00002=Invalid CliNumber. MPI0006=Invalid Protocol version
SM00003=Keyword required. MPI0007=Invalid message
SM00004=Invalid Keyword.
SM00005=Amount required. CGW000074=CGW000074-Merchant ID Invalid
SM00006=Invalid Amount. CGW000160=CGW000160-Terminal ID Invalid
SM00007=CliID required. CGW000161=CGW000161-Terminal ID Missing
SM00008=Invalid CliID. CGW000185=CGW000185-Track ID Invalid
SM00009=Invalid CliParam1. CGW000191=CGW000191-Batch ID Invalid
SM00010=Invalid CliParam2. CGW000241=CGW000241-Batch Action Invalid
SM00011=Invalid CliParam3. CGW000242=CGW000242-Track ID In Use
SM00012=Invalid CliParam4. CGW000296=CGW000296-Batch ID Missing
SM00013=Invalid CliParam5. CGW000297=CGW000297-Batch Status Missing
SM00014=Keyword not owned by Merchant. CGW000313=CGW000313-Merchant Exists for
Category
SM00015=CliNumber already active. CGW000359=CGW000359-Unable to Parse Input
Record
SM00016=CliNumber already active. Payment Reversed. CGW001000=CGW001000-Batch Track ID Invalid
SM00017=CliNumber already active. Payment Could CGW001001=CGW001001-Batch Received Time
NOT be Reversed. Invalid
SM00018=CliNumber not present in DB. CGW001002=CGW001002-Batch Input File Invalid
SM00019=Merchant-Keyword not present in DB. CGW001003=CGW001003-Batch Output File Invalid
SM00020=CliID not present. CGW001004=CGW001004-Batch Status Invalid
SM00021=Invalid notification response from merchant. CGW001005=CGW001005-Total Transaction Count
Invalid
CGW001006=CGW001006-Processing Start Time
Invalid
GV00200=Invalid Merchant Acceptor (Length) CGW001007=CGW001007-Processing Completion
Time Invalid
GV00201=Invalid Merchant Acceptor CGW001008=CGW001008-Processed Transaction
Count Invalid
GV00202=Invalid Merchant Acceptor Terminal (Length) CGW001012=CGW001012-Start Range Invalid
GV00203=Invalid Merchant Acceptor Terminal CGW001013=CGW001013-Start Range Missing
GV00204=Invalid Merchant Password (Length) CGW001014=CGW001014-Processing Transaction
Count Invalid
GV00205=Invalid Merchant Password CGW001015=CGW001015-Suspend Command Invalid
GV00206=Invalid Merchant Certificate Alias (Length) CGW000367=CGW000367-Batch In Use
GV00207=Invalid Merchant Certificate Alias CGW000074=CGW000074-Merchant ID Invalid

Gennaio 2017 Pagina 42 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Appendice D
Decodifica campo responsecode

Segue la lista di dettaglio dei possibili codici di risposta trasmessi dagli Issuers.

00 Approved or completed successfully (if balances are available)


00 Approved or completed successfully (if balances are not present)
01 Refer to card issuer
02 Refer to special conditions for card issuer
03 Invalid merchant
04 Pick-up card
05 Do not honor
06 Error
07 Pick-up card, special condition
08 Honor with identification
09 Request in progress
11 Approved (VIP)
12 Invalid transaction
13 Invalid amount
14 Invalid card number (no such number)
15 No such issuer
30 Format error
31 Bank not supported by switch
33 Expired card
34 Suspected fraud
35 Card acceptor contact acquirer
36 Restricted card
37 Card acceptor call acquirer security
38 Allowable PIN tries exceeded
39 No credit account
41 Lost card
43 Stolen card, pick-up

Gennaio 2017 Pagina 43 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

51 Not sufficient funds


54 Expired card
55 Incorrect personal identification number
56 No card record
57 Transaction not permitted to cardholder
58 Transaction not permitted to terminal
61 Exceeds withdrawal amount limit
62 Restricted card
65 Exceeds withdrawal frequency limit
68 Response received too late
75 Allowable number of PIN tries exceeded
da 76 Reserved for private use
a 89
90 Cut-off is in process, a switch is ending business for a day and
starting the next (transaction can be sent again in a few minutes)
91 Issuer or switch is inoperative
92 Financial institution or intermediate network facility cannot be
found for routing
94 Duplicate transmission
96 System malfunction
da Reserved for private use
N0 a
R8
S4 PTLF full
da S5 Reserved for private use
a T7

Gennaio 2017 Pagina 44 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Appendice E
Elenco country codes

Afghanistan AF
Aland Islands AX
Albania AL
Algeria DZ
American Samoa AS
Andorra AD
Angola AO
Anguilla AI
Antarctica AQ
Antigua and Barbuda AG
Argentina AR
Armenia AM
Aruba AW
Australia AU
Austria AT
Azerbaijan AZ
Bahamas BS
Bahrain BH
Bangladesh BD
Barbados BB
Belarus BY
Belgium BE
Belize BZ
Benin BJ
Bermuda BM
Bhutan BT
Bolivia, Plurinational State of BO
Bosnia and Herzegovina BA
Botswana BW
Bouvet Island BV
Brazil BR
British Indian Ocean Territory IO
Brunei Darussalam BN
Bulgaria BG
Burkina Faso BF
Burundi BI
Cambodia KH
Cameroon CM
Canada CA
Cape Verde CV
Cayman Islands KY
Central African Republic CF
Chad TD
Chile CL
China CN

Gennaio 2017 Pagina 45 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Christmas Island CX
Cocos (Keeling) Islands CC
Colombia CO
Comoros KM
Congo CG
Congo, the Democratic Republic of the CD
Cook Islands CK
Costa Rica CR
Cote d'Ivoire CI
Croatia HR
Cuba CU
Cyprus CY
Czech Republic CZ
Denmark DK
Djibouti DJ
Dominica DM
Dominican Republic DO
Ecuador EC
Egypt EG
El Salvador SV
Equatorial Guinea GQ
Eritrea ER
Estonia EE
Ethiopia ET
Falkland Islands (Malvinas) FK
Faroe Islands FO
Fiji FJ
Finland FI
France FR
French Guiana GF
French Polynesia PF
French Southern Territories TF
Gabon GA
Gambia GM
Georgia GE
Germany DE
Ghana GH
Gibraltar GI
Greece GR
Greenland GL
Grenada GD
Guadeloupe GP
Guam GU
Guatemala GT
Guernsey GG
Guinea GN
Guinea-Bissau GW
Guyana GY
Haiti HT
Heard Island and McDonald Islands HM
Holy See (Vatican City State) VA

Gennaio 2017 Pagina 46 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Honduras HN
Hong Kong HK
Hungary HU
Iceland IS
India IN
Indonesia ID
Iran, Islamic Republic of IR
Iraq IQ
Ireland IE
Isle of Man IM
Israel IL
Italy IT
Jamaica JM
Japan JP
Jersey JE
Jordan JO
Kazakhstan KZ
Kenya KE
Kiribati KI
Korea, Democratic People's Republic of KP
Korea, Republic of KR
Kuwait KW
Kyrgyzstan KG
Lao People's Democratic Republic LA
Latvia LV
Lebanon LB
Lesotho LS
Liberia LR
Libyan Arab Jamahiriya LY
Liechtenstein LI
Lithuania LT
Luxembourg LU
Macao MO
Macedonia, the former Yugoslav Republic of MK
Madagascar MG
Malawi MW
Malaysia MY
Maldives MV
Mali ML
Malta MT
Marshall Islands MH
Martinique MQ
Mauritania MR
Mauritius MU
Mayotte YT
Mexico MX
Micronesia, Federated States of FM
Moldova, Republic of MD
Monaco MC
Mongolia MN
Montenegro ME

Gennaio 2017 Pagina 47 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Montserrat MS
Morocco MA
Mozambique MZ
Myanmar MM
Namibia NA
Nauru NR
Nepal NP
Netherlands NL
Netherlands Antilles AN
New Caledonia NC
New Zealand NZ
Nicaragua NI
Niger NE
Nigeria NG
Niue NU
Norfolk Island NF
Northern Mariana Islands MP
Norway NO
Oman OM
Pakistan PK
Palau PW
Palestinian Territory, Occupied PS
Panama PA
Papua New Guinea PG
Paraguay PY
Peru PE
Philippines PH
Pitcairn PN
Poland PL
Portugal PT
Puerto Rico PR
Qatar QA
Reunion RE
Romania RO
Russian Federation RU
Rwanda RW
Saint Barthélemy BL
Saint Helena SH
Saint Kitts and Nevis KN
Saint Lucia LC
Saint Martin (French part) MF
Saint Pierre and Miquelon PM
Saint Vincent and the Grenadines VC
Samoa WS
San Marino SM
Sao Tome and Principe ST
Saudi Arabia SA
Senegal SN
Serbia RS
Seychelles SC
Sierra Leone SL

Gennaio 2017 Pagina 48 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Singapore SG
Slovakia SK
Slovenia SI
Solomon Islands SB
Somalia SO
South Africa ZA
South Georgia and the South Sandwich Islands GS
Spain ES
Sri Lanka LK
Sudan SD
Suriname SR
Svalbard and Jan Mayen SJ
Swaziland SZ
Sweden SE
Switzerland CH
Syrian Arab Republic SY
Taiwan, Province of China TW
Tajikistan TJ
Tanzania, United Republic of TZ
Thailand TH
Timor-Leste TL
Togo TG
Tokelau TK
Tonga TO
Trinidad and Tobago TT
Tunisia TN
Turkey TR
Turkmenistan TM
Turks and Caicos Islands TC
Tuvalu TV
Uganda UG
Ukraine UA
United Arab Emirates AE
United Kingdom GB
United States US
United States Minor Outlying Islands UM
Uruguay UY
User Defined Territories QZ
Uzbekistan UZ
Vanuatu VU
Venezuela, Bolivarian Republic of VE
Viet Nam VN
Virgin Islands, British VG
Virgin Islands, U.S. VI
Wallis and Futuna WF
Western Sahara EH
Yemen YE
Zaire ZR
Zambia ZM
Zimbabwe ZW

Gennaio 2017 Pagina 49 di 50


TVB_IPG_Manuale_ECom_MBMP_111.doc
Release 1.1.1

Documentazione di supporto

Nome file Descrizione


Documento che descrive le
caratteristiche funzionali, di
TVB_IPG_Protocolli_di_Sicurezza_MBMP_<x.y.z>.pdf sicurezza e le garanzie offerte dagli
strumenti di pagamento gestiti da
IPG.
Documento tecnico con le
TVB_IPG_Manuale_PaymentQuery_MBMP_<x.y.z>.pdf specifiche di implementazione
dell’API PaymentQuery.
Documento che riporta l’elenco
delle CA ritenute attendibili da IPG
TVB_IPG_Elenco_CA_autorizzate_<x.y.z>.pdf per l’invio dei Notification Messages
ai siti dei Merchants protetti da
certificato SSL.

n.b.: <x.y.z> indica la versione del documento.

Gennaio 2017 Pagina 50 di 50