Integrazione dei pagamenti Banca Sella con WordPress
da Massimo Della Rovere · pubblicato il 24 Novembre, 2014 · modificato il 12 Luglio, 2016

Il sistema di pagamento elettronico messo a disposizione da Banca Sella è uno dei più utilizzati sul mercato italiano. Proprio per questo, molte volte ci troviamo di fronte la possibilità di valutarlo come sistema di pagamento da implementare per qualche nostro cliente. Il sistema è molto affidabile, è relativamente semplice da configurare ma per quanto riguarda la documentazione devo dire che è un pochino scadente.

Proprio per questo motivo ho deciso di riportarvi un’esperienza diretta che vi possa aiutare nel caso in cui anche voi dovete eseguire questa procedura. La documentazione consiste in un manuale di 46 pagine che forse sono troppe per spiegare l’intero meccanismo, questo è anche il motivo più comune per cui alcuni miei colleghi hanno desistito dopo i primi 15 minuti di lettura. Oltretutto non ci sono esempi pratici in linguaggio PHP, che per chi sviluppa in WordPress è sicuramente un grosso limite.

Introduzione

Se vogliamo implementare un sistema di pagamento al nostro carrello senza utilizzare dei plugin specifici, dobbiamo prima di tutto capire i passaggi che si verificano durante una transazione di pagamento elettronico. Una volta che abbiamo chiarito questo aspetto possiamo passare al codice e vedere come integrarlo in WordPress. Per prima cosa vi allego qui di seguito uno schema generale su cui analizzeremo i punti principali:

Pagamento con Gestpay

(1) Area eCommerce: questa è la fase gestita dal nostro applicativo che visualizzerà il catalogo prodotti all’utente, le offerte in vigore e tutti gli altri aspetti che sono legati ad una procedura di eCommerce standard come ad esempio l’aggiungi al carrello.

(2) Area Carrello: in questa sezione l’utente visiona il carrello con i prodotti inseriti su cui può fare eventuali modifiche o aggiunte, normalmente in fondo al carrello troviamo le note legali e le raccomandazioni seguite da un tasto per eseguire il pagamento. Salto il fatto che bisogna inserire anche i dati personali, l’indirizzo di spedizione, etc.

(3) Area Cashout: questa sarà la pagina che elaborerà la richiesta di pagamento, eseguirà il calcolo dell’ammontare, il numero dell’ordine, creerà una stringa cifrata e spedirà tutto al servizio GestPay tramite un redirect che porterà l’utente sul server della banca. Questa fase la vedremo nel dettaglio durante il proseguimento dell’articolo.

(4) GestPay Banca Sella: in questa fase l’utente ha lasciato il nostro server ed è atterrato su quello della Banca Sella, il quale gli chiederà gli estremi di pagamento, il numero di carta di credito, il codice segreto, un’eventuale PIN di conferma SMS etc. Come vedremo sarà anche possibile aggiungere dei componenti grafici personali che userà la Banca.

(5) Area Conferma: quando la banca concluderà la transazione, eseguirà lei questa volta un redirect dell’utente su una pagina del nostro sito (da noi indicata), questa pagina riceverà una stringa cifrata con tutti i dettagli della transazione. Noi una volta decifrata la stringa avviseremo l’utente con un messaggio che dipenderà dal risultato arrivato.

Back Office

Prima di procedere alla creazione dei nostri scripts abbiamo bisogno di un’ambiente di test su cui la Banca Sella ci dia le dovute autorizzazioni per fare le prove durante la fase di sviluppo. Per fortuna questa fase è molto semplice e poco burocratica, infatti basta andare nell’area sviluppatori di GestPay e richiedere dei codici di accesso.

Questi codice oltre ad essere rilasciati in maniera molto veloce ci permetteranno anche di entrare nel back office (test) e simulare tutte le opzioni di configurazione che abbiamo necessità di provare. Come ad esempio la configurazione della pagina che riceverà l’esito della transazione di pagamento da parte della banca stessa.

Gestpay backoffice

Le opzioni messe a disposizione sono molte, in questo articolo cerchiamo di vedere quelle che intessano solo la parte di programmazione. Prima di tutto si deve creare una pagina di pagamento, trovate il menu specifico. Sulla pagina trovate delle opzioni che ci permettono di sapere i parametri che passiamo noi alla banca (parametro), quelli che la banca chiederà al cliente (input) e quelli che riceveremo nella risposta (risposta).

Se analizziamo la schermata di esempio possiamo dedurre quanto segue: il nostro script passerà alla Banca Sella, l’ammontare, il nome del cliente, la mail e la valuta. La banca a sua volta chiederà al cliente la mail e il nome da modificare (altrimenti rimane quella che abbiamo passato noi), il numero di carta di credito (che noi non abbiamo chiesto) e altre cose come il PIN che trovate nel proseguimento. Una volta che la banca passa l’esito della transazione ci arriveranno i campi che abbiamo attivato sulla destra.

Adesso che sappiamo cosa passare e cosa ricevere, dobbiamo specificare a Banca Sella quali sono le nostre pagine di atterraggio per ricevere le conferme che riguardano l’esito delle transazioni effettuate dopo che l’utente ha lasciato il nostro sito. Nella schermata seguente vi riporto la pagina “Configurazione” che bisogna selezionare. In questa pagina al momento ci interessano le opzioni Indirizzi IP e Indirizzi Risposte.

Gestpay configurazione

Nel campo indirizzi IP mettiamo gli indirizzi permessi alle richieste di pagamento che la banca deve accettare. Quindi inserite l’indirizzo IP statico del server che ospita la vostra applicazione. Nella sezione Indirizzi Risposte possiamo indicare le email che riceveranno le comunicazioni degli esiti, ma cosa che a noi interessa di più, possiamo indicare le URL di risposta positiva e negativa. Anche se possono essere diverse io preferisco usarne una per entrambi i casi, la quale si adatterà al tipo di esito.

Creazione delle pagine

Come risultato dell’analisi appena fatta dovremmo essere d’accordo che le pagine da sviluppare sono solo due. La prima (cashout) viene richiamata dall’utente quando preme il bottone “Pagamento”, questa crea la stringa cifrata da mandare a Banca Sella ed esegue un redirect sul portale della banca stessa. La seconda (conferma) invece è in attesa di essere richiamata quando l’utente avrà finito la transazione e riceverà l’esito.

Pagina Cashout

Passiamo a creare la pagina (cashout) e vedere il codice PHP che eseguirà le funzioni che abbiamo descritto precedentemente. Per collegare il codice alla pagina di WordPress dobbiamo prima crearla nella sezione pagine, e poi legare lo script tramite un template dedicato o creare un file nel nostro tema chiamato page-cashout.php.

// Dal Carrello e dai dati inseriti dall'utente bisogna ricavare
// le seguenti informazioni (dipendono dal vostro applicativo)

$totaleOrdine    = (variabile);
$numeroOrdine    = (variabile);
$nomeAcquirente  = (variabile);
$emailAcquirente = (variabile);

// PREPARAZIONE PARAMETRI CON CUI CREARE LA CHIAVE
// CIFRATA ED ESEGUIRE IL REDIRECT A BANCA SELLA  

$parametri = new stdClass();

$parametri->shopLogin = 'GESPAY99999'; // Inserite il vostro
$parametri->uicCode = '242'; // EURO
$parametri->amount = number_format($totaleOrdine,2,'',',');
$parametri->shopTransactionId = $numeroOrdine;
$parametri->buyerName  = $nomeAcquirente;
$parametri->buyerEmail = $eamilAcquirente;

// ADESSO DEVO CRIPTARE LA VARIABILE $parametri, PER QUESTA
// OPERAZIONE USIAMO UN WEB SERVICES DELLA BANCA SELLA

$S='https://testecomm.sella.it/gestpay/gestpayws/WSCryptDecrypt.asmx?WSDL';
$L='https://testecomm.sella.it/gestpay/pagam.asp';

// In produzione la stringa URL è diversa da quella di TEST
// https://ecomms2s.sella.it/gestpay/gestpayws/WSCryptDecrypt.asmx?WSDL
// https://ecomms.sella.it/pagam/pagam.aspx

$client = new SoapClient($S);
$result = $client->Encrypt($parametri);
$simple = $result->EncryptResult;

// CONVERTO LA RISPOSTA XML IN OBJECT PER CONTROLLI
// DOVRESTE ANCHE CONTROLLARE SE LA CHIAMATA SOAP NON HA PROBLEMI

$objectXML = simplexml_load_string($simple->any);

// CONTROLLO IL RISULTATO DELLA CHIAMATA PER CIFRARE LA STRINGA E
// PREPARO I PARAMETRI A=Negozio e B=Chiave cifrata 

if ($objectXML->TransactionResult == "OK")
{
    // I parametri si devono chiamare proprio a & b non è
    // una questione di fantasia è proprio come li vuole la banca

    $a = $parametri->shopLogin;
    $b = $objectXML>CryptDecryptString;

    // Esecuzione redirect dell'utente sulla pagina
    // del pagamento presente nei server della banca sella

    header('Location: '.$L.'?a='.$a.'&b='.$b);
    exit();

} else {

    echo "La Banca non ha cifrato la chiave";
    echo $objectXML->ErrorDescription;
}

Ovviamente questo codice andrà adattato alle vostre esigenze e vanno aggiunti ulteriori controlli prima di eseguire il redirect. Quindi non fate copia e incolla, ma implementate le parti che vi servono nella vostra applicazione. Per quanto riguarda i nomi delle opzioni che trovate nella struttura ($parametri) non ho trovato una documentazione chiara, e per scoprirle ho dovuto girare diversi forum e vedere diversi esempi, molti riportavano anche nomi di opzioni errati in quanto forse versioni vecchie.

Pagina Conferma

Come già detto questa pagina sarà richiamata dal servizio della banca dopo l’esecuzione del pagamento, e il cliente sarà dirottato automaticamente su essa. Per creare la pagina in WordPress eseguite la stessa procedura indicata nel capitolo precedente. Vi allego qui di seguito anche il codice PHP (indicativo) per eseguire questa funzione.

// Se non esistono i parametri a e b non eseguo niente 
// o se volete potete dirottare su pagina principale

if (!isset($_GET['a']) or !isset($_GET['b'])) {
  header("HTTP/1.1 301 Moved Permanently");
  header("Location: https://mysite.com/shop/");
  exit();
}

// Assegnazione delle variabili a=negozio e b=stringa
// Dobbiamo decriptare la stringa usando sempre il web service

$shopLogin     = $_GET['a'];
$cryptedString = $_GET['b'];

// PREPARAZIONE VARIABILE DA PASSARE AL WEB SERVICE
// DI BANCA SELLA E OTTENERE LA STRINGA IN CHIARO

$parametri = new stdClass();
$parametri->shopLogin = $shopLogin;
$parametri->CryptedString = $cryptedString;

$S='https://testecomm.sella.it/gestpay/gestpayws/WSCryptDecrypt.asmx?WSDL';

// In produzione la stringa URL è diversa da quella di TEST
// https://ecomms2s.sella.it/gestpay/gestpayws/WSCryptDecrypt.asmx?WSDL

$client = new SoapClient($S);
$result = $client->Decrypt($parametri);
$simple = $result->DecryptResult;

// CONVERTO LA RISPOSTA XML IN OBJECT PER CONTROLLI
// DOVRESTE ANCHE CONTROLLARE SE LA CHIAMATA SOAP NON HA PROBLEMI

$objectXML = simplexml_load_string($simple->any);

if ($objectXML->TransactionResult == "OK") { 
    echo "TRANSAZIONE ESEGUITA CON SUCCESSO";
} else {
    echo "TRANSAZIONE NON AUTORIZZATA";
}

// SE VOLETE VEDERE ALCUNE INFORMAZIONI DI RITORNO
// UTILIZZATE I SEGUENTI NOMI (potete vederli nel backoffice)

echo "Numero Ordine " .$objectXML->ShopTransactionID;
echo "Ammontare "     .$objectXML->Amount;
echo "Valuta "        .$objectXML->Currency;
echo "Transazione "   .$objectXML->BankTransactionID;
echo "Autorizzazione ".$objectXML->AuthorizationCode;
echo "Nominativo "    .$objectXML->Buyer->BuyerName;
echo "EMAIL "         .$objectXML->Buyer->BuyerEmail;
echo "Esito OK/KO "   .$objectXML->TransactionResult;
echo "Descrizione "   .$objectXML->ErrorDescription;

Ricordatevi che i valori di ritorno sono personalizzabili dal servizio della Banca tramite il pannello di admin che abbiamo visto nei precedenti capitoli. Quindi sia i nomi che le informazioni necessarie le possiamo configurare in base alle nostre esigenze.

Utilizzo della Carta di Credito

È bene sapere che se eseguite delle prove di pagamento con una vostra Carta di Credito, fate sempre riferimento a piccoli importi, come ad esempio 0,50 centesimi o un euro. Infatti anche se state in ambiente di test, i controlli avvengono sul circuito reale, quindi la transazione sarà presente sulla vostra carta anche se a fine mese non addebitata. Però in ogni caso vi viene tolta la disponibilità mensile in quanto la transazione è reale.

8 Commenti

  1. Ciao Massimo e grazie per il tuo post. Non ho trovato info riguardo l'URL Server to server che mi dà molti problemi. Quello indicato nel plugin del tipo https://miodominio.it/?wc-api=WC_Gateway_Gestpay non funziona perché a quanto pare non restituisce un codice header http 200. Su altri forum ho trovato l'indicazione di mettere https://miodominio.it/shop/ ma anche in questo caso mi arriva la mail di Segnalazione Mancata Comunicazione Server to Server per impossibilità a comunicare con la pagina. Di conseguenza l'ordine Woocommerce viene sì creato, però con lo stato "in attesa di pagamento" (mentre il pagamento è avvenuto) e non viene mandata nessuna conferma via mail ne al cliente ne all'amministratore del negozio. È un problema che hai riscontrato anche tu? Se sì posso chiederti come lo hai risolto? Grazie mille

  2. Ciao Massimo e grazie per il tuo post. Non ho trovato info riguardo l'URL Server to server che mi dà molti problemi. Quello indicato nel plugin del tipo https://miodominio.it/?wc-api=WC_Gateway_Gestpay non funziona perché a quanto pare non restituisce un codice header http 200. Su altri forum ho trovato l'indicazione di mettere https://miodominio.it/shop/ ma anche in questo caso mi arriva la mail di Segnalazione Mancata Comunicazione Server to Server per impossibilità a comunicare con la pagina. Di conseguenza l'ordine Woocommerce viene sì creato, però con lo stato "in attesa di pagamento" (mentre il pagamento è avvenuto) e non viene mandata nessuna conferma via mail ne al cliente ne all'amministratore del negozio. È un problema che hai riscontrato anche tu? Se sì posso chiederti come lo hai risolto? Grazie mille

  3. Ciao Massimo, grazie della guida…
    sai dirmi se gestpay funziona anche con web application scritte in java?

  4. Ciao Tiziano, non ho mai usato la classe Java però a quanto pare esiste e ne parlano anche nel forum della banca sella.
    https://forum.sella.it/spazioaperto/posts/list/129402.page

  5. Ciao, grandissimo post. Sto rifacendo i mio sito wp e sto montando woocommerce. Nel backoffice di banca sella ho cominciato le configurazioni, e sono in attesa della risposta del mio host per capire se al mio IP ne sono associati altri per completare le configurazioni di sella e prevenire gli errori. Per l’integrazione nel mio wocommerce ho utilizzato il plugin, l’unico che c’è, perchè proprio non sono pratica di codici. Ora mi domandavo, ma esiste comunque un bottone di pagamento che posso, al di là dei carrelli e dell’ecommerce, integrare in un form e metterlo su una pagina?

  6. Ciao Giulia, ti conviene controllare nella documentazione ufficiale della banca sella dedicata agli sviluppatori. Dovresti trovare tutto il materiale disponibile. Guarda anche dentro i file PDF.
    https://www.gestpay.it/gestpay/specifiche-tecniche/index.jsp

  7. Gran post, molto utile. Grazie.

  8. A seguito di alcune prove e all’integrazione anche con MyBank ho modificato alcune righe del codice presentato in questo articolo, in quanto c’erano degli errori che andavano sistemati, ad esempio i numeri devo avere solo il separatore di virgola per i decimali e omettere il punto per la separazione delle migliaia.

condividi