Banca Sella web services for dummies – I web services di Banca Sella

This is all you need to know to implement payments using the web services of Banca Sella.

This is what the technical manual doesn’t tell plain and clearly.

Unless you have previous experience with payment systems, encryption, etc, you are likely to waste many hours trying to grasp the subject and get the job done, just as it happened to me.

There are already pages on the net (like this real good one), showing some implementation code: they’re helpful if you know the language and want to use it. But that’s not the aim of this page. What I present here is the bare-bone execution flow up to the tiniest detail, albeit regardless of the language you will chose to implement.

I am writing this page in Italian, actually I wrote it already: it was for a non-english-speaking colleague. But I guess most implementors will be Italian, so the language choice will be OK. If foreigners will show interest, I will translate it in english.

—————

Pagamenti tramite web services Banca Sella

Tutto quello che avreste voluto sapere sull’argomento, ma non avete mai osato chiedere….

Premesse e Pre-condizioni

Nel seguito della pagina (salvo se espressamente detto altro) si fa riferimento alla seguente situazione:

  • siamo degli sviluppatori indipendenti alle prese con un sito e-commerce
  • il sito usa delle URL che finiscono in ASPX, ma potrebbero finire in JSP, DO, PHP, whatever
  • il nostro sito presenta al browser dei clienti surfanti e paganti delle pagine contenenti javascript. Tale javascript sta usando jQuery per le comunicazioni ajax.
  • stiamo organizzando dei pagamenti per il nostro cliente, che si chiama OUR_CLIENT
  • stiamo lavorando nell’infrastruttura di test di Banca Sella (per l’ambiente di produzione Banca Sella occorre estrapolare e adattare questa informazione)

Nel seguito della pagina si usano le parole con significato:

  • cliente = il nostro cliente OUR_CLIENT
  • customer = l’individuo che acquista qualcosa col suo browser

Il tipo di servizio scelto dal nostro cliente è quello BASIC. Banca Sella offre anche altri tipi di servizio più complessi; il servizio basic limita i pagamenti a EURO (Currency 242)

Il nostro cliente deve essersi accreditato presso Banca Sella e deve fornirci TRE pezzi di informazione per consentirci di loggarci sui server BancaSella e configurare il servizio:

  • Codice Esercente (altrimenti detto shopLogin nelle chiamate SOAP)
  • Codice (altrimenti detto Codice Esercente!!! in alcune mail spedite dalla banca)
  • Chiave (PIN) – questa è la partita iva del cliente

L’ambiguità nella nomenclatura può costare ore di rompicapo. Si riporta qui l’esempio OUR_CLIENT sperando consenta di capire le cose nel caso di altri clienti:

Sample Banca Sella login page

Alcune mail di Banca Sella al cliente riportavano un certo Terminal id, ma non mi è mai servito ad alcunchè!!

Scenario

Si faccia riferimento al seguente file, scaricabile dal sito Banca Sella :

[*] “Gestpay – Security with encryption technical specifications – v.2.1, 12/1/2010”

Abbiamo 3 attori:

  • customer browser (chi surfa sul nostro sito e-commerce)
  • merchant server (il sito e-commerce che stiamo realizzando)
  • gestpay server (presso Banca Sella)

Noi (ossia il merchant server) e il gestpay server ci scambiamo request+response SOAP sulla base dei seguenti WSDL:

ATTENZIONE: il contratto WSDL è naturalmente soggetto a cambiamenti, quindi per ogni progetto è necessario procurarsene una copia fresca.

Configurazioni sul sito Banca Sella

L’url di login nel backend TEST di Banca Sella è:

L’url di login nel backend PRODUZIONE (in seguito non più rilevante per questo esempio) di Banca Sella è:

I settaggi indispensabili nel caso di servizio BASIC riguardano i seguenti punti:

  • indirizzo/i IP del nostro/i merchant server
  • 3 liste di indirizzi email cui inviare i vari tipi di comunicazioni
  • url sul merchant server per risposta positiva
  • url sul merchant server per risposta negativa (OUR_CLIENT usa la stessa pagina per ambedue i casi di risposta!!)

I settaggi facoltativi nel caso di servizio BASIC riguardano i seguenti punti:

  • url per comunicazioni server-to-server
  • email del customer care del cliente
  • telefono del customer care del cliente

Per le altri configurazioni, i default proposti sono sufficienti per cominciare.

Come testare i pagamenti sul sito Banca Sella

Le prove richiedono:

  1. l’utente creato al momento dell’iscrizione fatta dal nostro cliente (vedi primo paragrafo)
  2. una carta di credito VERA

Si tenga presente che l’autorizzazione al pagamento viene data da VISA/MASTERCARD in persona senza sapere nulla del fatto che stiamo testando, e quindi gli importi delle transazioni vengono automaticamente dedotti dal limite di spesa mensile della carta.

L’infrastruttura testecomm di Banca Sella dovrebbe offrirci abbastanza garanzie di non perdere soldi durante i test. Le precauzioni insite nel sistema sono (di default, ma modificabili secondo quanto detto al precedente paragrafo):

  • ogni transazione terminata con successo viene processata da Banca Sella dopo 25 giorni
  • come trattamento di default, la transazione viene cancellata senza procedere alla riscossione dell’importo

Ciononostante è bene dare SEMPRE valori piccolissimi al parametro amount (step 2), p.es. “0.10”. Ciò garantisce due cose:

  1. il limite di spesa della carta di credito non viene intaccato, se non in minima parte
  2. anche in caso di applicazione della legge di Murphy, perderemo solo 10 eurocent (che potremo comunque provare a farci rimborsare dal nostro cliente)

Però i test alla fine possono essere decine e decine, e quindi è meglio non lasciare troppi pagamenti completi in attesa del 25esimo giorno. A fine giornata è facile loggarsi sul backend Banca Sella e cancellare manualmente i pagamenti col semaforo verde.

Flusso di chiamate

Si fa qui riferimento a due cose:

  • gli step come definiti entro [*], illustrazione a pag.6, vedi img qui sotto
  • le pagine del sito OUR_CLIENT, ossia del merchant server, scritte da noi

NB – il documento [*] contiene numerose imprecisioni ed inoltre tratta molto brevemente la comunicazione webservice, dedicando la maggior parte dell’esposizione alla comunicazione stateful tramite un oggetto DOM dedicato.

Flusso Chiamate
Flusso Chiamate

L’elenco sequenziale delle varie chiamate INDISPENSABILI è il seguente:

  • step 1 – il customer browser fa una chiamata ajax e passa al nostro merchant server (pagina CrittaDecritta.aspx) i dati sull’articolo da acquistare
  • step 2 – CrittaDecritta.aspx invoca il web service di Banca Sella tramite il metodo Encrypt dell’oggetto WSCryptDecrypt (vedi paragrafo sulla preparazione del web service client, inviando la SOAP request step2request.soap. Questa request contiene come minimo: importo (amount – e.g. 100.00) codice cliente (shopLogin) e un identificativo della transazione (ShopTransactionId). Il codice della transazione è una stringa composita (max 50 char!! e.g. ZXY00123_133_RC) che deve consentire alla fine di capire quale acquisto è stato effettuato (si tenga presente che la transazione è completamente stateless per il merchant server!!!)
  • step 3 – il Gestpay server verifica che la chiamata sia arrivata proprio dal nostro merchant server, cripta i valori amount, shopLogin e ShopTransactionId e ritorna (sempre nell’ambito dell’esecuzione della CrittaDecritta.aspx) una response SOAP al merchant server (esempio step3response.soap). Essa contiene una stringa XML, a sua volta contenente i due famosi parametri shopLogin e CryptDecryptString. Questa viene d’ora in avanti indicata come la PRIMA stringa criptata
  • step 4 – alla fine della propria esecuzione CrittaDecritta.aspx invia nella response al browser la stringa XML di cui allo step 3. La pagina potrebbe anche convertire l’XML in una stringa JSON.
  • step 5 – il javascript sul browser del customer (scritto da noi) riceve la stringa XML come data alla fine dell’ajaxata, converte l’XML in un oggetto javascript, ne controlla l’attributo GestPayCryptDecrypt.TransactionResult = “OK” e modifica window.location.href per accedere in GET alla url di pagamento di Banca Sella, fornendo i due parametri a (shopLogin) e b (la famosa PRIMA stringa criptata). Il Gestpay server riceve la chiamata, legge la PRIMA stringa criptata, capisce cosa vuole pagare il customer e gestisce tutta la comunicazione col customer browser fino al completamento (successo, fallimento o abbandono) delle operazioni di pagamento da parte del customer browser(*).
  • step 7b – alla fine delle operazioni il gestpay server dirige il customer browser a una delle due url (risposta positiva o risposta negativa – vedi paragrafo su configurazione lato Banca Sella). Il gestpay server ha fornito al customer browser la famosa SECONDA stringa criptata.
  • step 8b – nel caso di OUR_CLIENT la url finale è una sola, ossia Bancasella.aspx. Il customer browser la invoca fornendo in GET i due parametri a/shopLogin e b/CryptDecryptString – NOTA BENE che la stringa criptata ha gli stessi nomi b/CryptDecryptString che ai passi 3/4, ma ora qui abbiamo la SECONDA stringa criptata!!!
  • step 9b – Bancasella.aspx recupera i parametri della GET e invoca il web service di Banca Sella tramite il metodo Decrypt dell’oggetto WSCryptDecrypt (vedi paragrafo sulla preparazione del web service client), inviando la SOAP request step9brequest.soap.
  • step 10b – il Gestpay server verifica che la chiamata sia arrivata dal nostro merchant server, decripta la SECONDA stringa criptata e ritorna una response SOAP al merchant server (esempio step10bresponse.soap). Essa contiene una stringa XML con tutti i dati in chiaro sull’avvenuto (o non avvenuto) pagamento. Tuttora in esecuzione, Bancasella.aspx agisce sulla base dei dati ricevuti: nel caso di OUR_CLIENT, la pagina comunica ai server nel backend amministrativo i dati del pagamento e poi ordina un redirect del customer browser sulla pagina da cui egli/ella aveva iniziato tutta l’operazione.

(*) Nel frattempo il merchant server ha perso qualunque riferimento alla transazione che si sta svolgendo. Beninteso il merchant server potrebbe aver annotato sul db qualcosa allo step1/2, ma ciò non è assolutamente necessario!

Ricapitolando:

  • la PRIMA stringa criptata contiene i dati forniti da noi al gestpay server per consentirgli di preparare le operazioni di pagamento
  • la SECONDA stringa criptata contiene i dati forniti dal gestpay server a noi e riassume l’esito del pagamento
  • Ciò che le due stringhe hanno in comune è che contengono ambedue lo stesso ShopTransactionId. Però noi non siamo obbligati a tenere nota sul merchant server (nel db oppure – AAAAAARGH!! –  in sessione) dei pagamenti in corso di svolgimento: basta che creiamo lo ShoptransactionId in modo smart, così da capire alla fine che cosa è stato pagato.

A fianco di questi step INDISPENSABILI, [*] pag. 6 riporta altri passi, ovviamente NON indispensabili. In particolare, è prevista una comunicazione server-to-server da gestpay al merchant server PRIMA che il customer browser arrivi a comunicare i risultati del pagamento.

Tali passi non indispensabili possono essere implementati per potenziare le capacità di controllo e riconciliazione delle operazioni da parte del merchant server, oppure più umilmente per loggare due volte le stesse informazioni: nel caso di OUR_CLIENT, abbiamo una chiamata allo step 6 che (dopo decrittazione agli step 7a/8a) consente alla pagina Service2Service.aspx di scrivere un paio di righe nel log della webapp sul merchant server. Questo potrebbe essere utile come double check dei log fatti da Bancasella.aspx in caso di rimostranze da parte del customer.

Esempi request e responses

Tutte le url di Banca Sella sono relative all’infrastruttura di test. Usando quella di produzione, i riferimenti passano da testecomm a ecomm.

step2.request.soap
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ecom="https://ecomm.sella.it/">
   <soapenv:Header/>
   <soapenv:Body>
      <ecom:Encrypt>
         <ecom:shopLogin>GESPAY12345</ecom:shopLogin>
         <ecom:uicCode>242</ecom:uicCode>
         <ecom:amount>99</ecom:amount>
         <ecom:shopTransactionId>ZXY00012345_144_234PI</ecom:shopTransactionId>
         <ecom:cardNumber></ecom:cardNumber>
         <ecom:expiryMonth></ecom:expiryMonth>
         <ecom:expiryYear></ecom:expiryYear>
         <ecom:buyerName></ecom:buyerName>
         <ecom:buyerEmail></ecom:buyerEmail>
         <ecom:languageId></ecom:languageId>
         <ecom:cvv></ecom:cvv>
         <ecom:customInfo></ecom:customInfo>
      </ecom:Encrypt>
   </soapenv:Body>
</soapenv:Envelope>
step3.response.soap
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <EncryptResponse xmlns="https://ecomm.sella.it/">
         <EncryptResult>
            <GestPayCryptDecrypt xmlns="">
               <TransactionType>ENCRYPT</TransactionType>
               <TransactionResult>OK</TransactionResult>
               <CryptDecryptString>PRIMA_STRINGA_CRIPTATA</CryptDecryptString>
               <ErrorCode>0</ErrorCode>
               <ErrorDescription/>
            </GestPayCryptDecrypt>
         </EncryptResult>
      </EncryptResponse>
   </soap:Body>
</soap:Envelope>
step5.request.http
NB - questa url va usata per far fare il redirect al customer browser.
**Gli va passata da noi allo step 4**
https://testecomm.sella.it/gestpay/pagam.asp?a=GESPAY12345&b=PRIMA_STRINGA_CRIPTATA
step6.request.http
NB - questa url viene composta dal server gestpay, non da noi!!!
E' qui solo come riferimento!!
http://merchant-server.our-client.com/web/service2service.aspx?
a=GESPAY12345&b=SECONDA_STRINGA_CRIPTATA
step8b.request.http
NB - questa url viene composta dal server gestpay e passata allo
step 7b come redirect al customer browser.
E' qui solo come riferimento!!
http://merchant-server.our-client.com/bancasella.aspx?
a=GESPAY12345&b=SECONDA_STRINGA_CRIPTATA
step9b.request.soap
NB - vale anche quale step7a.request.soap, in quanto può essere inviata
(ma non è obbligatorio) anche in seguito alla
chiamata 6 da parte del server gestpay
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ecom="https://ecomm.sella.it/">
   <soapenv:Header/>
   <soapenv:Body>
      <ecom:Encrypt>
         <ecom:shopLogin>GESPAY12345</ecom:shopLogin>
         <ecom:CryptedString>SECONDA_STRINGA_CRIPTATA</ecom:CryptedString>
      </ecom:Encrypt>
   </soapenv:Body>
</soapenv:Envelope>
step10b.response.soap
NB - questa vale per un caso si avvenuto pagamento, altrimenti alcuni parametri cambiano.
Vale anche quale step8a.response.soap, in quanto viene ritornata
anche alla richiesta non obbligatoria 7a da parte del merchant server.
Vedere in particolare [*] pag 39 per una lista dei codici di errore.
<?xml version="1.0" encoding="utf-8"?>
<GestPayCryptDecrypt xmlns="">
  <TransactionType>DECRYPT</TransactionType>
  <TransactionResult>OK</TransactionResult>
  <ShopTransactionID>ZXY00012345_144_234PI</ShopTransactionID>
  <BankTransactionID>2</BankTransactionID>
  <AuthorizationCode>005611</AuthorizationCode>
  <Currency>242</Currency>
  <Amount>0.10</Amount>
  <Country></Country>
  <CustomInfo></CustomInfo>
  <Buyer>
    <BuyerName>ABRAMO LINCOLN</BuyerName>
    <BuyerEmail>abramo@lincoln.com</BuyerEmail>
  </Buyer>
  <TDLevel></TDLevel>
  <ErrorCode>0</ErrorCode>
  <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
  <AlertCode></AlertCode>
  <AlertDescription></AlertDescription>
  <VbVRisp></VbVRisp>
  <VbVBuyer></VbVBuyer>
  <VbV></VbV>
</GestPayCryptDecrypt>

Preparazione web service client sul merchant server

Il WSDL va dato in pasto alla vostra IDE preferita, la quale crea una DLL, un JAR, whatever. Tale DLL va linkata nel codice della CrittaDecritta.aspx e della Bancasella.aspx.

Il servizio è rappresentato dall’oggetto WSCryptDecrypt, i cui metodi rilevanti sono:

Encrypt

    ' Public Function Encrypt(ByVal shopLogin As String,
    ' ByVal uicCode As String, ByVal amount As String,
    ' ByVal shopTransactionId As String, ByVal cardNumber As String,
    ' ByVal expiryMonth As String, ByVal expiryYear As String,
    ' ByVal buyerName As String, ByVal buyerEmail As String,
    ' ByVal languageId As String, ByVal cvv As String,
    ' ByVal customInfo As String) As System.Xml.XmlNode

NB – i parametri dopo shopTransactionId sono facoltativi (mettere ””).

Decrypt

    ' Public Function Decrypt(ByVal shopLogin As String,
    ' ByVal cryptedString As String) As System.Xml.XmlNode

Advertisements

6 thoughts on “Banca Sella web services for dummies – I web services di Banca Sella

  1. Jan says:

    Hello!
    You wrote “But I guess most implementors will be Italian”.
    I’m afraid I am the first exception. Unfortunately I don’t speak italian and I have already wasted a lot of time trying to get the Webservice to work. So I would be happy for a translation.

      1. Jan says:

        Thank you for your offer but meanwhile I found out that the basic version of banca sella is not able to fit our needs anyway – after I have already put a lot of work into it. So I don’t have any deadline any more.

  2. Francesco says:

    Molto utile, grazie. La documentazione ufficiale del webservice gestpay è a dir poco criptica.

    Un’unica nota, credo che allo step9 vada sostituito ecom:Encrypt -> ecom:Decrypt

  3. faustinelli says:

    Grazie a te. Però è passato così tanto tempo che non sono in grado di valutare nel merito la tua correzione. Ti riferisci all’allegato step9b.request.soap, giusto? Ai tempi avevo fatto copia-incolla ma posso essermi confuso. Lascio qui la tua segnalazione come warning per altri eventuali lettori.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s