Tutorial per il Payment Gateway del Consorzio Triveneto SpA

e-commerce payment gateway

Lo sviluppo di un’applicativo e-commerce B2B per un cliente mi ha portato ad analizzare a fondo il Payment Gateway del Consorzio Triveneto S.p.A. Prima di iniziare mi complimento con il consorzio per aver redatto una documentazione molto precisa. Lo stesso gateway lo trovo veramente ben fatto ma su questo potrò darvi maggiori dettagli tra qualche mese, quando il cliente sarà in produzione.

Introduzione

In un’applicativo web-based di e-commerce solitamente le figure (sarebbe meglio parlare di macchine, PC, server, ecc.) con cui abbiamo a che fare sono tre:

  1. L’utente che acquista e che naviga il sito (definito Cardholder)
  2. Il negozio online: il server del sito di e-commerce (definito Merchant)
  3. Il Gateway per i pagamenti, in parole povere: il server che si occupa delle transazioni con carta di credito (denifito Payment Gateway, qui di seguito Gateway)

Dal punto di vista pratico quindi avremo il Cardholder che naviga il sito del Merchant ed esegue le sue operazioni di acquisto (ordini, carrello, ecc.). Una volta terminata la sessione di acquisti si dirige alla pagina del pagamento e qui entra in azione tutto quello che vedremo in questo Tutorial.

L’intero processo prevede comunicazioni tra le tre figure sopra elencate. Le comunicazioni tra Merchant e Gateway possono essere definite server-to-server, l’utente infatti non sempre interagisce con esse. I server si scambiano messaggi tra loro per ovvi motivi di sicurezza.

Sulla pagina del Merchant quindi deve essere predisposta una pagina che si occupa di inviare i dati (codice identificativo, importo da pagare, numero ordine, ecc.) al Gateway. Quando il Cardholder clicca sul famoso “Paga ora!” tali dati vengono inviati al server del Gateway che, dopo averli elaborati e controllati, restituisce una risposta al server del Merchant. In questo frangente il Cardholder resta in attesa davanti al pc!
Una volta ricevuta la risposta dal Gateway la nostra procedura (Merchant) elabora i dati ricevuti e decide se proseguire o meno. In caso di errori potrebbe visualizzare una pagina al Cardholder perchè qualcosa è andato storto, in caso sia tutto ok invece potrebbe direttamente redirezionare il Cardholder verso la HPP (pagina del Gateway su cui l’utente inserisce i dati della sua carta di credito).
Questa prima transazione (e relativo scambio di messaggi), nel modello predisposto dal Consorzio Triveneto, prende il nome di PaymentInit.

Il nostro utente (Cardholder) quindi, se i dati passati al Gateway sono congrui, viene redirezionato sulla HPP dove potrà inserire i dati della sua carta di credito. L’utente effettua quindi l’operazione compilando tutti i campi e poi dà l’invio.
Qui scattano nuovamente diverse comunicazioni prima di restituire l’esito al Cardholder.
Per prima cosa il Gateway deve interfacciarsi a sua volta ad altri server, quelli del Centro autorizzativo, e verificare la validità della carta, la disponibilità e quant’altro. Eseguita questa operazione ricontatta il Merchant riportando l’esito dell’operazione che, anche questa volta, può essere positivo o negativo. In base all’esito il server del Merchant restituisce un URL verso cui redirezionare il Cardholder. Il Gateway quindi si occupa poi di redirezionare il Cardholder sulla pagina dell’esito.
Questa seconda transazione (e relativo scambio di messaggi), nel modello predisposto dal Consorzio Triveneto, prende il nome di NotificationMessage.

Ora passiamo alla pratica, successivamente vedremo perchè il NotificationMessage è così importante dal punto di vista della sicurezza.

La Classe PgConsTriv

Ho implementato questa classe e l’ho rilasciata sotto licenza GNU Lesser General Public License su SourceForge.
Questa la pagina che ho predisposto per la documentazione tecnica per la classe PgConsTriv e qui link per il download dell’ultima release (PgConsTriv.zip).
Insieme alla classe trovate una cartella example, in cui risiedono i file di esempio che vedremo insieme in questo Tutorial, e il file di configurazione. In dettaglio:

  • PgConsTriv.php (classe)
  • PgConsTriv.inc.php (file di configurazione)
  • example/
    • paynow.php
      Pagina per predisposizione e invio del PaymentInit
    • responseURL.php
      Pagina per ricezione ed elaborazione del NotificationMessage
    • errorURL.php
      Pagina per esito negativo
    • goodURL.php
      Pagina per esito positivo
    • test_PG.php
      Form che invia POST per testare la pagina del Response URL

Prima di iniziare dovete configurare i parametri della classe presenti nel file PgConsTriv.inc.php

Il PaymentInit e l’inizio della transazione

Come dicevamo sopra, tutto ha inizio con l’invio da parte del Merchant del PaymentInit. Da questo riceveremo una prima risposta che ci fornirà:

  • In caso di esito positivo: l’indirizzo verso cui redirezionare il Cardholder e il PaymentID
  • In caso di esito negativo: una stringa con !ERROR! e relativa descrizione

Analizziamo ora il file paynow.php in dettaglio.

N.B.: Preferisco creare una pagina separata alla quale passo via GET l’id dell’ordine. Tramite questo recupero dal database tutti i dati necessari dell’ordine e avvio la procedura. In questo modo si ha una maggiore sicurezza perchè se, ad esempio, invio tutti i dati via POST o GET direttamente alla pagina l’utente “furbetto” potrebbe intercettarli e variarli.

Al paynow.php quindi arriva il mio id ordine ($idp), poi recupero i dati dal database e li sistemo in un array ($arRp).
A questo punto verifico i dati e decido se procedere o meno:

// VERIFICO se può accedere all'ordine
if( count($arRp) > 0 &&
$idp > 0 &&
isset($arRp["stato"]) &&
($arRp["stato"] == "NEW" || $arRp["stato"] == "PAYMENT_INIT" )
) {

N.B.: Nel mio ordine gestisco un campo stato. E’ lo stesso che poi andrò ad aggiornare tramite risposte del server del Gateway in base ai vari esiti e passaggi. In questo modo avrò sempre sotto controllo l’andamento dell’ordine.
Qui sopra, infatti, verifico che lo stato sia consono a ciò che sto per effettuare: il PaymentInit. Il mio ordine quindi deve essere o in stato Nuovo (NEW) o in PaymentInit. Questo secondo caso lo lascio passare perchè ipotizzo la situazione in cui l’utente clicca su “Paga ora!” e, dopo aver visualizzato la HPP del Gateway, chiude il browser.

A questo punto siamo pronti per inviare il PaymentInit che altro non è che l’invio di una serie di dati via POST ad un indirizzo specifico. Creando un’istanza della classe andremo ad inserire i soli dati che potranno variare da ordine ad ordine mentre tutti gli altri dati saranno gestiti dalla classe stessa.
Vediamo ora l’istanza della classe e la preparazione del PaymentInit con l’invio dei dati al Gateway.

// init PgConsTriv Class
$pg = new PgConsTriv($lng);
$pg->setAction('Purchase');
$pg->setSecurityCode_PI( $secCode );
$pg->sendVal_PI($importo, $idp);

Per istanziare la classe devo passare il parametro della lingua ($lng). Tale parametro è opzionale e nel caso non venga passato la classe utilizzerà la lingua di default settata nel file di configurazione. Per maggiori dettagli leggi il Tutorial multi lingua.
Il metodo setAction imposta l’Action. Purchase si occupa di eseguire direttamente l’accredito dell’importo (vedi documentazione del Gateway, Appendice A).

Veniamo ora al discorso sicurezza e il parametro SecurityCode.

N.B.: Nella documentazione del Consorzio (pag. 23) si raccomanda di verificare sempre l’autenticità del NotificationMessage. Una delle soluzioni proposte è quella di inviare via PaymentInit un valore che il Cardholder non vede e non può conoscere. Lo stesso valore verrà poi restituito al Merchant successivamente attraverso il NotificationMessage. In questo modo potremo verificare il dato ricostruendolo e confrontandolo con quello passato dal NotificationMessage.

Impostiamo quindi il nostro SecurityCode ($secCode). Per generare un codice univoco potreste crearvi una stringa criptando in md5 alcuni dati presenti nel database (es: data ordine, idordine, importo, ecc.). In questo modo, successivamente, all’arrivo del NotificationMessage sarete in grado di ricostruirla con la stessa logica e verificarla con quella che vi verrà passata dal Gateway.

A questo punto punto siamo pronti per inviare il PaymentInit. Il metodo sendVal_PI riceve 2 valori:

  • $importo – Importo della transazione
  • $idp – Denominato trackid nella Documentazione del Gateway e deve essere un id univoco dell’ordine

Il metodo sendVal_PI invia i dati al Gateway e ne elabora la risposta.
Ora vediamo come gestire tale risposta:

// Verifico esito del PaymentInit
if( $pg->hasError_PI() )
{
// SEGNALAZIONE ERRORE!
echo "<h1>ERRORE: ".$pg->getError_PI()."</h1>";
} else {
// Registro il PaymentID nel database e invio l'utente alla HPP del Gateway
mysql_query("UPDATE ordini SET .... ....");
header("Location: " . $pg->getPaymentURL_PI() );
}

Il metodo hasError_PI ci restituisce true se si sono verificati errori, in tal caso l’errore lo possiamo recuperare con il metodo getError_PI.
In caso di esito positivo recuperiamo i dati con:

  • getID_PI – PaymentID generato dal Gateway
  • getPaymentURL_PI – URL della HPP

Redirezionando l’utente verso la HPP del Gateway abbiamo concluso le operazioni del PaymentInit. Il Cardholder (utente) caricherà tale pagina e potrà inserire i dati della sua carta di credito. Solo dopo che avrà dato l’invio sulla HPP il Gateway ci contatterà per inviarci il NotificationMessage.

Il NotificationMessage e la chiusura della transazione

Nel momento in cui l’utente invia i dati della sua carta di credito al Gateway questo, dopo averli controllati presso il Centro Autorizzativo, contatta il server del Merchant inviando il NotificationMessage. Il Merchant risponde con un stringa che include l’indirizzo verso cui redirezionare il Cardholder.
La pagina di esempio che si occupa di tutto ciò è responseURL.php.

La prima operazione è creare una nuova istanza della classe per poi passargli i dati ricevuti via POST.

// init PgConsTriv Class
$pg = new PgConsTriv($lng);
$pg->setAction('Purchase');
$pg->setVal_NM($_POST);

setVal_NM si occupa appunto di registrare tutti i dati nella classe.
A questo punto iniziamo i nostri controlli per verificare la validità dei dati ricevuti.

// get paymentid
$paymentid = $pg->getPaymentID_NM();
// Verifico se esiste il PaymentID
if( $paymentid !== false ){
// Recupero Ordine dal database in base al PaymentID settato in fase di PaymentInit

Nel caso in cui qualcosa fosse andato storto o il PaymentID non risulta correttamente impostato il valore restituito da getPaymentID_NM è false. Lo verifichiamo e proseguiamo.
A questo punto posso recuperare i dati dell’ordine agganciando il PaymentID che mi ero registrato nel database in fase di PaymentInit. Recuperando i dati dal DB posso generare nuovamente il SecurityCode e verificarlo:

// set Security Code per verifica validità del Notification Message
$pg->setSecurityCode_PI( $secCode );
// Verifico autenticità del NotificationMessage
if( $pg->isValid_NM() ) {

Il metodo isValid_NM si occupa della verifica del SecurityCode. Controlla quello passato dal metodo setSecurityCode_PI con quello appena ricevuto dai dati POST.
Una volta superata questa verifica i nostri dati sono stati validati e possiamo ora procedere alla verifica dell’esito della transazione.
Nel caso abbia avuto esisto positivo avremo:

# Transazione Elaborata
if( $pg->isTransGood_NM() &&
$arRp["stato"] == "PAYMENT_INIT" &&
$pg->getVal_NM("trackid") == $idp // Verifico idp
) {
// OK, Registro STATO e dati TRANSAZIONE nel DB
$stato = $pg->getVal_NM("result");
$TranID = $pg->getVal_NM("tranid");
$Auth = $pg->getVal_NM("auth");
mysql_query("UPDATE .... SET ....");
// Verifico se elaborare l'ordine o meno a seconda del campo result

Per prima cosa verifichiamo con isTransGood_NM l’esito positivo della transazione. Poi (vedi documentazione del Gateway a pag.18) controlliamo che effettivamente sia il primo NotificationMessage che riceviamo. Potrebbero verificarsi dei casi in cui ne vengono inviati anche più di uno. La documentazione a riguardo dice di considerare attendibile sempre e solo il primo. Noi quindi, verificando lo stato, ci assicuriamo di ciò (lo stato infatti viene poi modificato e il secondo eventuale NotificationMessage non passa). Superati questi controlli possiamo prelevare i dati con il metodo getVal_NM (vedi documentazione del Gateway per elenco dei campi disponibili).

Attenzione: fino ad ora abbiamo parlato di esito della transazione. Parliamo in termini di elaborazione effettuata e non di effettivo accredito dell’importo prelevato dalla carta di credito (esito dell’acquisto). Per questo esistono altri metodi che controllano il campo result dei dati inviati tramite NotificationMessage.
I metodi sono diversi in base al valore che il campo result può assumere:

  • isCaptured_NM()
  • isNotCaptured_NM()
  • isApproved_NM()
  • isNotApproved_NM()
  • isDeniedByRisk_NM()
  • isHostTimeout_NM()

Nel nostro caso (Action = Purchase) il valore che corrisponde all’effettivo accredito dell’importo è “CAPTURED”.

Nel caso in cui la transazione invece dovesse avere esito negativo la funzione isTransError_NM restituisce true e noi possiamo procedere alla registrazione dell’errore nel DB:

# Transazione NON Elaborata a causa di errori tecnici
if( $pg->isTransError_NM() ) {
// ERROR, Registro Errore nel DB

Anche in questo caso registro comunque lo stato ERROR nel campo del mio ordine (questo per quanto spiegato sopra sul discorso di un eventuale doppio NotificationMessage) e anche l’eventuale errore recuperato con getVal_NM(“ErrorText”).
A questo punto non resta che comunicare al Gateway l’URL verso cui deve redirezionare il Cardholder:

// Restituisco al Gateway l'URL su cui redirezionare il Cardholder
echo "REDIRECT=". $pg->getURL_NM();

Il metodo getURL_NM restituisce il goodURL o errorURL a seconda che l’esito della transazione sia positivo o negativo. Esso considera inoltre, in base all’action impostato, anche l’esito dell’acquisto (accredito importo).

A questo punto si concludono anche le operazioni del NotificationMessage.
Resta un’ultima considerazione da fare come ben rappresentanto nella documentazione del Gateway (pag. 23).

Se il NotificationMessage non viene eseguito regolarmente

Cosa accade se, ad esempio, il Gateway invia il messaggio ma per qualsiasi motivo il server del Merchant non lo riceve?
In questo caso, sia che la transazione abbia esito positivo, sia negativo, il Gateway reindirizza il Cardholder verso la pagina ErrorURL. In questo caso l’utente vede esisto negativo mentre la transazione magari è andata a buon fine e, ad esempio, anche l’esito dell’acquisto è positivo (con tanto di accredito dell’importo).
Come da documentazione:

E’ quindi importante che il Merchant prepari l’ErrorURL in modo tale da ricavare informazioni utili per poter investigare l’accaduto e informare successivamente il Cardholder sull’esito dell’acquisto.

– –

Bene, siamo giunti alla fine del Tutorial.
Spero di implementare presto anche la tipologia di messaggio Payment (per operazioni in differita tra Merchant e Gateway, es: storno, riaccredito, ecc.).

Nel frattempo spero che questo Tutorial sia risultato chiaro e utile.
Buon lavoro! 🙂

12 pensieri su “Tutorial per il Payment Gateway del Consorzio Triveneto SpA

  1. user

    salve,
    è da circa un mese che contatto il consorzio triveneto ho mandato 10 email ma non mi rispondono per cortesia mi potrebbe dare informazioni su come contattarli per attivare il servizio, ci sono degli esempi in tecnologia dotnet?

  2. Daniela

    Ho prenotato un tragetto Brindisi (Italia)-igoumenitsa (Grecia) il 02/08/2013, quando sono arrivata al punto di prenotare ho inserito tutti i dati della carta di credito, lo stato ERROR nel campo del mio ordine. Dopo aspettative ho dovuto prenotare a un’altra agenzia molto sicura.
    Vorrei che questa prenotazione viene annullata e vorrei rimborso del importo pagato. Datemi qualche informazioni. Grazie.

  3. Gennaro Di Sarno

    Non ho capito bene; per le piccole spese la mia carta prepagata funziona ma ora ho appena provato a fare un acquisto di 340 euro e più di una volta mi invia la mail seguente:
    ERRORE! – Transazione NON ELABORATA
    Ho provato più volte ma niente da fare,cosa posso fare? C’è un tetto oltre al quale non posso acquistare o altro?

  4. Riccardo

    Buongiorno,

    ho provato ad installarlo, ma non ci sono riuscito . Sicuramente ho sbagliato in qualche passaggio .
    Mi potrebbe aiutare ?

    Grazie

  5. Alessio Sormani

    Ciao a tutti,
    è possibile usare/installare questo plugin in WordPress? Dovrei implementare questa modalità di pagamento ma non so come fare.
    Grazie in anticipo.

  6. Michele Verde

    “qui link per il download dell’ultima release (PgConsTriv.zip).
    Insieme alla classe trovate una cartella example, in cui risiedono i file di esempio che vedremo insieme in questo Tutorial, e il file di configurazione”

    Scusi, ma nel file zip non trovo nessuna cartella example 🙁

  7. Lucio Crusca

    Ciao, scusa se approfitto per chiedere un aiuto, ma non so a chi altro chiedere. Sto cercando di implementare il pagamento triveneto in un sito WordPress, non sto usando questa classe perché mi serve capire come funziona la procedura e quindi preferisco implementarla io.
    Credo di aver fatto tutto come da istruzioni, ma il notification message non mi arriva proprio (ho riempito di log il codice della responseURL per esserne sicuro). Il client (io) fa tutta la procedura di pagamento, ma poi il browser viene rediretto alla errorURL. Io ricevo una mail con pagamento AUTORIZZATO ma non ancora eseguito (anche se ho specificato action=1 e non 4) ed alla errorURL non viene passato alcun parametro, nè in $_GET nè in $_POST.
    Secondo te cosa sto sbagliando?

  8. luca

    Buongiorno Davide, mi si verifica questo problema. Quando la banca mi ritorna la stringa di pagamento effettuato correttamente (o no), woocommerce non torna alla pagina corretta, ma va in errore evidenziando un loop di redirect. Come posso risolvere questo inconveniente?
    Grazie in anticipo.

  9. Jazzo Autore articolo

    ciao Luca, purtroppo non riesco ad aiutarti perchè non so come abbiano implementato il tutto in woocommerce. Io ho solo sviluppato la classe che vedi sopra.

  10. Ferretti Dino

    Buongiorno,
    in posta elettronica oggi ho ricevuto questo avviso.
    non mi ricordo avere effettuato questo pagamento al citato beneficiario il quale, da me interpellato, mi ha confermato di non averlo ricevuto.
    Potete controllare con cortese urgenza
    Grazie
    cell. 339 137 66 55

    Transazione AUTORIZZATA

    Sito Web Merchant: ANTONIANUM LIBR. ONLINE
    Codice Ordine: 2016-DP6542-243790
    ———————————————————–
    Data e Ora: 2016-03-16 12:41:22.559
    Codice Ordine Payment Gateway: 5980792381260760
    Codice Transazione Payment Gateway: 5178953411260760
    ———————————————————–
    Importo: EUR 9,99
    Carta utilizzata: MC
    Codice Autorizzazione: T06306

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *