Michael Rogger (michael dot rogger at gmail dot com), basandosi sul codice sorgente della classe PgConsTriv, ha sviluppato il pluging per i pagamenti con carta di credito tramite il Payment gateway del Consorzio Triveneto sulla piattaforma xt:commerce.

Abbiamo creato un’area apposita per le release che verrano rilasciate su SourceForge.
Scarica il plugin ora.

Di seguito invece un breve Tutorial su come installare il plugin:

===
This plugin is tested with xt commerce 4.0.14.

INSTALL
1)    Edit xt_trivento/classes/PgConsTriv.inc.php to configure the gateway.
Compulsory: merchant data (_PG_ID_Merchant_Test,_PG_Password_Test,_PG_ID_Merchant_Production,_PG_Password_Production) and _PG_URL_base.

2)     Copy folder xt_triveneto to shop/plugins/
Note for debugging: make sure xt_triveneto/classes/debug.txt, xt_triveneto/classes/pgconstriv.txt and xt_triveneto/callback/debug.txt is writeable for webserver, these files are used for logging.

3)     Install the plugin using xt_commerce admin interface

4)     After successful testing you can change the mode from “Test” to “Production” in PgConsTriv.inc.php

Ho aggiornato la classe PgConsTriv che implementa una serie di metodi utili alla realizzazione di siti e-commerce che necessitano di interfacciarsi al Payment Gateway del Consorzio Triveneto S.p.A.

La gestione multi lingua era un po’ ostica e ho preferito metterci mano risolvendo il problema a monte. Dalla nuova versione (Rel. 1.3) in poi la lingua verrà passata direttamente secondo i codici standard della codifica ISO 639-1.

La piattaforma del Payment Gateway accetta un codice (langid) per impostare la lingua con cui verrà visualizzata la HPP al Cardholder. I codici consentiti (come da Documentazione) sono:

• ITA = Italiano
• USA = Inglese
• FRA = Francese
• DEU = Tedesco
• ESP = Spagnolo
• SLO = Sloveno

Io invece preferisco l’utilizzo dei codici standard secondo la codifica ISO 639-1. A questo punto le due cose cozzavano e quindi ho messo mano alla classe. Ora il parametro dovrà essere passato secondo la codifica standard (it, en, fr, de, es, sl) e non quella del PG qui sopra. La classe (tramite l’array $arLingue – proprietà della classe) converte poi il valore automaticamente quando deve essere passato al PG.

Già che c’ero ho rinominato i file (classe e file di configurazione). Mi sono trovato ad installarlo su Zend Framework e c’erano troppi underscore e meno di troppo!

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!