Consorzio Triveneto Payment Gateway (php Class)

Introduzione

La classe 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.

Le specifiche tecniche utilizzate per lo sviluppo sono quelle per l’Interfacciamento Merchant Release 1.4.4 (19/03/2009). Sulla base di queste specifiche la classe, al momento, gestisce i seguenti messaggi tra il Merchant e il Payment Gateway (di seguito denominato PG):

PaymentInit
Messaggio di inizializzazione della transazione inviato dal Merchant al PG. Segue comunicazione del PG che comunica URL della HPP (pagina in cui inserire i dati della carta di credito) e il PaymentID (univoco per ogni transazione).
NotificationMessage
Messaggio di comunicazione dell’esito della transazione inviato dal PG al Merchant. Segue comunicazione del Merchant per l’invio dell’URL su cui redirezionare il Cardholder (utente che acquista).
Payment (Da implementare!)

La classe prevede una gestione multi lingua.

Requisiti

La classe utilizza la libreria CURL PHP per effettuare le comunicazioni dal Merchant al Payment Gateway pertanto è necessario avere tale libreria installata sul proprio server.

Tutorial

Qui trovate un Tutorial sulla classe PG_ConsTriv per i messaggi del PaymentInit e NotificationMessage.
Qui altro Tutorial per l’utilizzo multilingua della classe PG_ConsTriv.

Download

La Classe è posizionata su SourceForge dove trovate l’ultima release aggiornata.

Documentazione

Nel file di configurazione PG_ConsTriv-Config.php è necessario impostare alcuni parametri in modo da configurare l’utilizzo della classe per il proprio dominio e account verso il Payment Gateway.

Configurazione della Classe

Ecco l’elenco dei parametri che devono obbligatoriamente essere configurati perchè la classe funzioni correttamente:

_PG_System_Environment
Può essere impostato sul valore Test o Production. A seconda del valore cambiano gli URL da utilizzare per collegarsi al PG.
_PG_ID_Merchant_Test e _PG_ID_Merchant_Production
Vengono rilasciati dal Consorzio. Uno per la fase di test e un secondo definitivo per quando si andrà in produzione.
_PG_Password_Test e _PG_Password_Production
Rilasciate insieme all’ID Merchant. Vedi sopra.
_PG_CurrencyCode
Imposta il codice ISO della valuta che verrà utilizzata. Nel caso del Consorzio Triveneto va impostato a 978 (Euro).
_PG_Default_LangId
Imposta la lingua utilizzata di default. Nel caso in cui di utilizzerà la classe in modalità multilingua questa potrà essere impostata nel momento in cui creiamo l’istanza della classe.
_PG_URL_base
E’ il dominio su cui risiederà la classe, quello del Merchant.
_PG_responseURL
E’ la pagina php che verrà richiamata dal PG per la comunicazione del NotificationMessage
_PG_errorURL
Pagina per l’esito negativo
_PG_goodURL
Pagina per l’esito positivo

Nel file di configurazione sono presenti anche altri parametri che riguardano gli URL del PG, sia ambiente di test che quello in produzione. Ad oggi (vedi sopra riferimenti alle Specifiche) quelli inseriti vanno bene. Nel caso dovessero cambiare vanno aggiornati.

Creare un’istanza della Classe

La classe può essere caricata passando il parametro $lingua (facoltativo, tra quelli contemplati nella documentazione, vedi sotto). Se non viene passato alcun parametro verrà considerata la lingua impostata di default nel file di configurazione (PG_ConsTriv-Config.php).

// init PG_Triveneto_Class for PaymentInit (action Purchase) $pg = new PG_ConsTriv_Class('ITA'); $pg->setAction('Purchase');

Le lingue dell’interfaccia del Payment Gateway attualmente gestite e configurabili sono:

USA = Inglese
FRA = Francese
DEU = Tedesco
ESP = Spagnolo
SLO = Sloveno

Il metodo setAction invece prevede le seguenti azioni:

Purchase
Authorization

Le uniche due possibili per il PaymentInit.
Altre azioni (Credit, Reversal, ecc.) possono essere gestite tramite messaggio Payment (attualmente non implementato).

Metodi della classe (PaymentInit)

Sono implementati sia i metodi necessari ad effettuare la chiamata, sia quelli per l’elaborazione dei dati ricevuti in risposta.

setSecurityCode_PI($sc)
Set Codice di sicurezza ($sc) che verrà inviato tramite campo udf4 (pertanto tale campo non risulta utilizzabile dal metodo seguente)
setCampoUdf_PI($n, $val)
Set Campi UDF (Campi a discrezione del Merchant)
- $n = numero campo udf (1,2,3 e 5 – il 4 è utilizzato per il SecurityCode – vedi sopra)
- $val = valore del campo (vedi documentazione per Valorizzazioni speciali)
sendVal_PI( $amt, $trackid)
Invio Messaggio PaymentInit ed elaborazione della risposta
- $amt = importo
- $trackid = id dell’ordine
hasError_PI()
Restituisce Bool per esistenza ERRORE sul PaymentInit
getError_PI()
Restituisce Messaggio di ERRORE del PaymentInit
getID_PI()
Restituisce PaymentID restituito dalla chiusura della transazione del PaymentInit
getPaymentURL_PI()
Restituisce l’URL verso cui redirezionare l’utente (Cardholder) dopo la conclusione della transazione PaymentInit

Metodi della classe (NorificationMessage)

Sono implementati sia i metodi necessari a ricevere la chiamata, sia quelli per l’elaborazione dei dati inviati dal server del Payment Gateway.

setVal_NM($post)
Set Variabili inviate dal NotificationMessage via POST
isValid_NM()
Verifica validità dei dati del NotificationMessage in base al SecurityCode impostato in udf4
isTransError_NM()
Restituisce Bool true se si è verificato un ERRORE durante la TRANSAZIONE
isTransGood_NM()
Restituisce Bool true se la TRANSAZIONE è stata elaborata con successo
getVal_NM($v)
Restituisce un valore ($v) se presente nell’array settato con setVal_NM($post)
In caso non esista restituisce un valore null
getPaymentID_NM()
Get PaymentID (In caso non sia settato restituisce false)
getURL_NM()
Restituisce l’URL verso cui redirezionare l’utente (Cardholder)
L’URL viene creato in base a:
- risposta fornita dal server: valore result settato tramite il metodo setVal_NM($post)
- action impostata con set_Action($a)