Gestpay diventa Axerve Ecommerce Solutions

Come creare la tua pagina di pagamento personalizzata

La pagina iFrame di Axerve permette agli esercenti di processare le transazioni online con carta di credito con una pagina di pagamento nascosta attraverso un iFrame nella pagina di checkout.

L’adozione della pagina di pagamento iFrame di Axerve offre al merchant la possibilità di personalizzare il layout della pagina di checkout e, allo stesso tempo, i dati di carta vengono spediti dal form di checkout ad una pagina nascosta (residente sui server di Axerve) via javascript.

La soluzione richiede di validare la conformità PCI annualmente, compilando e restituendo all’acquirer il questionario SAQ A-EP.

Tokenization e iFrame sono disponibili per i clienti Professional ed Enterprise

Step 0: iscrizione ad Axerve Ecommerce Solutions

….probabilmente ti sei già registrato, oppure no? È possibile registrarsi e configurare il backoffice leggendo la guida veloce di Axerve Ecommerce Solutions.

Adesso possiamo iniziare davvero.

Step 1: crittografare la richiesta

Funziona più o meno come con le SOAP.

In pratica, è necessario crittografare le informazioni della transazione con lo shopLogin, uicCode (il codice valuta), amount, e uno shopTransactionId (un identificativo della transazione a scelta dell’esercente).

Axerve Ecommerce Solutions risponde con almeno due parametri:

Ecco un esempio. I server dell’esercente comunicano le informazioni della transazione, impostando i valori del metodoWSCryptDecrypt’s Encrypt in questo modo:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>1245.6</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
</Encrypt>

Axerve Ecommerce Solutions autentica il server chiamante e valida le informazioni che contraddistinguono la transazione. Se si superano i controlli, viene restituita una stringa criptata ad Axerve Ecommerce Solutions:

<EncryptResult>
  <GestPayCryptDecryptxmlns="">
  <TransactionType>ENCRYPT</TransactionType>
  <TransactionResult>OK</TransactionResult>
  <CryptDecryptString>30715CA8...</CryptDecryptString>
  <ErrorCode>0</ErrorCode>
  <ErrorDescription/>
  </GestPayCryptDecrypt>
</EncryptResult>

Step 2: configurare javascript e HTML

Dopo aver ottenuto la stringa di dati criptati (come descritto nel capitolo precedente), il browser del compratore viene indirizzato alla pagina di checkout dell’esercente che include un file javascript ricevuto dai server di Axerve:

<script src="https://ecomm.sella.it/pagam/JavaScript/js\_GestPay.js" type="text/javascript"></script>

Lo script effettua automaticamente una verifica di compatibilità del browser per accertarsi che la funzione HTML postmessage, che viene usata per lo scambio di dati, sia supportato.

Il risultato della verifica è il valore booleano della variabile BrowserEnabled:

if(BrowserEnabled){
  // The Browser is supported!
  // Proceed to create the payment page
}else{
  // the browser is NOT supported
  // Place here error handler code
}

Per caricare la pagina nascosta iFrame, la pagina di checkout deve chiamare la funzione Javascript passando il Merchant code , la stringa criptata e un oggetto callback necessario per leggere i risultati della verifica di sicurezza.

if(BrowserEnabled){
  // The Browser is supported!
  GestPay.CreatePaymentPage(
    MerchantCode,
    EncryptedString,
    paymentPageLoadedCallback);
}else{
  // the browser is NOT supported
}

La funzione crea un iFrame nascosto nel corpo dell’elemento e carica la pagina di pagamento passando il merchant code e la stringa criptata nella fase precedente.

<iframe
  src="https://ecomm.sella.it/Pagam/HiddeniFrame.aspx?a=MerchantCode&amp;b=EncryptedString"
  heigth="0"
  width="0"
  style="position:absolute;top:0;left:0;width:0;height:0;visibility:hidden">
</iframe>

Quando viene chiamata la pagina di pagamento, vengono eseguiti i controlli di sicurezza necessari e viene riportato il risultato nell’oggetto result.

varpaymentPageLoadedCallback=function(result){
  if(Result.ErrorCode!=10){// 10 means no security errors
    //An error has occurred
    //result.ErrorCode will return the Error occurred
    //Result.ErrorDescription will return the Error Description
    //.... place here error handle code...
  }else{
    //the iFrame is correctly created and the payment page is loaded;
    // the user can proceed to insert the credit card data.
  }
}

Se il controllo di compatibilità del browser fallisce, l’iFrame non viene creato e la pagina di pagamento non viene caricata.

È possibile verificare i browser supportati nella sezione Requisiti software.

Step 3: inviare i dati di carta

Per inviare i dati di carta all’iFrame nascosto, la pagina di checkout assegna una funzione all’evento OnSubmit del form della carta di credito. Questa funzionalità recupera i dati di carta e chiama la funzione GestPay.SendPayment, fornendo un array con il numero di carta (CC), il mese e l’anno di scadenza (EXPMM e EXPYY), il CVV (CVV2) se attivo, a una funzione di callBack.

Ecco un esempio:

<form name="myCCForm" action="" method="post" OnSubmit="return checkCC();">
  <fieldset>
    <legend>Insert Credit Card Data</legend>
    <label for="CC">Credit Card Number</label>
    <input type="text" name="CC" value="" autocomplete="off" id="CC"/>
    <label for="ExpMM">Expiry Month</label>
    <input type="text"name="ExpMM"id="ExpMM"value=""/>
    <label for="ExpYY">Expiry Year</label>
    <input type="text"name="ExpYY" id="ExpYY" value=""/>
    <label for="CVV2">CVV2 / 4DBC</label>
    <input type="text" name="CVV2" id="CVV2" value=""/>
    <label for="BuyerName">Buyer's name</label>
    <input type="text" name="BuyerName" id="BuyerName" value=""/>
    <label for="BuyerEmail">Buyer's email</label>
    <input type="text"name=" BuyerEmail" id="BuyerEmail" value=""/>
  </fieldset>
  <fieldset>
    <input type="submit" name="submit" value="Send Payment" id="submit"/>
  </fieldset>
</form>

E la funzione javascript checkCC:

function CheckCC(){
  document.getElementById('submit').disabled=true;
    GestPay.SendPayment({
    CC:document.getElementById('CC').value,
    EXPMM:document.getElementById('ExpMM').value,
    EXPYY:document.getElementById('ExpYY').value,
    CVV2:document.getElementById('CVV2').value,
    BuyerName:document.getElementById('BuyerName').value,
    BuyerEmail:document.getElementById('BuyerEmail').value
  },paymentCompletedCallback);
  returnfalse;
}

Per sollevare il sito Ecommerce dalla necessità di richiedere certificazioni PCI-DDS onerose ed eccessivamente elevate, l’evento OnSubmit deve evitare di passare i dati di carta alla pagina di checkout del merchant.

Step 4: risultati della transazione

Axerve Ecommerce Solutions invia il risultato della transazione come oggetto javascript e come notifica che viene inoltrata con una chiamata server-to-server alla pagina impostata sul server del merchant (la pagina di notifica può essere impostata sulla funzione Response URL Server to Server presente nella sezione del backoffice Configurazione > Ambiente.

Come gestire transazioni 3D (Verified by Visa, Mastercard SecureCode, ecc.)**

Le transazioni fatte con carte 3D richiedono l’autenticazione del titolare di carta. L’acquirente, reindirizzato verso l’Issuer, si deve autenticare secondo il sistema scelto dall’Issuer stesso. Avvenuta l’autenticazione, la transazione riceve un esito positivo o negativo dalla società che ha emesso la carta (Issuer).

Se la carta viene riconosciuta come 3D, il risultato della richiesta autorizzativa è un errore specifico (8006) che si può leggere alla proprietà ErrorCode dell’oggetto Result. La descrizione dell’errore (verified by Visa) si evince grazie alla proprietà ErrorDescription dell’oggetto Result.

In questa fase vengono mostrate informazioni addizionali che sono necessarie al processo di pagamento e specifiche delle transazioni 3D. In particolare, è necessario acquisire il transaction id attraverso la proprietà TransKey dell’oggetto Result e una stringa cifrata, visibile grazie alla proprietà VbVRisp dell’oggetto Result, che viene usata nella fase seguente.

var paymentCompletedCallback = function(Result){
  if(Result.ErrorCode!=0){
    if(Result.ErrorCode==8006){
      //3D Transaction - Card holder authorization required
      //Get the TransKey
      //NOTE: you have to store this value somewhere for further use
      // after the redirect, you'll need this.
      varTransKey=Result.TransKey;
      //Get the VBVRisp; we will need it soon !
      varVBVRisp=Result.VBVRisp;
      ...
      //place here the code to redirect the card holder to the authentication website
      ...
    } else {
      //Call failed for other errors
      //.... place here error handle code...
    }
  } else {
    //Call OK, proceed to decrypt the Result.EncryptedResponse property
  }
}

Autenticazione del titolare di carta

Se la carta di credito risulta abilitata ai protocolli 3D, il compratore deve autenticarsi; il suo browser viene indirizzato ad una pagina di Axerve Ecommerce Solutions che funziona come interfaccia per l’autenticazione che il buyer che viene reindirizzato sul sito dell’Issuer. Questo step di autenticazione viene generalmente chiamato 3D-Secure.

La pagina da chiamare è:

La pagina deve essere chiamata con questi parametri:

Parametro Descrizione
a shop_login
b una stringa cifrata acquisita nella fase precedente attraverso la proprietà Result.VbVRisp dell’oggetto Result
c URL del merchant verso il quale l’acquirente viene reindirizzato dopo l’autenticazione

Alla fine del processo di autenticazione, il buyer viene reindirizzato sulla URL che l’esercente ha specificato nel parametro c .

Dopodiché la pagina del merchant richiama la funzione Gestpay.SendPayment() con due parametri:

PaRes è una stringa cifrata contenente il risultato dell’autenticazione che deve essere acquisito dal merchant e inoltrato ad Axerve Ecommerce Solutions nella fase successiva.

È bene assicurarsi che PaRes non contenga caratteri a capo, come il carattere ASCII 10 (a capo) o 13 (ritorno a capo). Alcuni acquirer potrebbero inviare stringhe con a capo; questo può causare un troncamento nelle stringhe javascript e di conseguenza Axerve Ecommerce Solutions non accetterebbe la richiesta.

Conclusione della transazione

Una volta che il buyer ritorna sul sito del merchant dopo l’autenticazione, ci sono tutte le informazioni per concludere la transazione inviando una nuova richiesta autorizzativa tramite il metodo GestPay.SendPayment.

Prima però è necessario includere il javascript di Axerve e chiamare la funzione javascript GestPay.CreatePaymentPage passando il Merchant code e la stringa criptata creata antecedentemente alla prima chiamata autorizzativa.

Una volta creato l’iFrame nascosto è possibile inviare la nuova richiesta auth attraverso il metodo GestPay.SendPayment, passando un comando contenente il valore TransKey (TransKey), il valore PARes (PARes) e l’oggetto Callback per gestire la risposta asincrona e recuperare la stringa criptata con i risultati della transazione.

GestPay.SendPayment({
'TransKey':'//PLACE HERE THE TRANSKEY VALUE',
'PARes':'//PLACE HERE THE PARES VALUE'
},
LocalObj.CallBack);

LocalObj.CallBack=function(Result){
  if(Result.ErrorCode!=0){
  //Call failed an error has occurred
  //.... place here error handle code...
  } else {
    //Call went good
    //place here the code to retreive the encrypted string
    varresponseString=Result.EncryptedResponse;
  }
}

La risposta verso l’esercente

Una notifica viene inoltrata attraverso una chiamata server-to-server alla pagina configurata sul server del merchant (la URL della pagina di notifica è un’informazione configurabile all’interno del backoffice merchant). La sintassi della call è la seguente:

http://<url server to server>?a=<ShopLogin>&amp;b=<encrypted string>

La chiamata verso la pagina viene effettuata passando due parametri:

La pagina sul server del merchant deve contenere <HTML></HTML> nell’html del codice sorgente.

Se Axerve Ecommerce Solutions non riceve una risposta con un codice status 200 dal sito del merchant, riprova due volte nelle 24 ore successive, alle 6:00 e alle 18:00.

L’esercente riceve anche una notifica del risultato della transazione via email all’indirizzo configurato nel profilo.

Inoltre la transazione è consultabile dal backoffice di Axerve Ecommerce Solutions (dashboard myCommerce) all’interno della sezione Active Report.

Fallback alla pagina di pagamento di default

Axerve Ecommerce Solutions permette allo store online di indirizzare il titolare di carta alla pagina di pagamento di default come alternativa all’iFrame nel caso in cui il browser non la supporti.

La pagina risiede sui server di Axerve e dà la possibilità di inserire i dati di carta senza che il merchant possa vederli né archiviarli.

Dopo aver ottenuto la stringa criptata (come descritto nella pagina guida veloce), il browser dell’acquirente viene reindirizzato alla pagina di pagamento sui server di Axerve:

La call viene effettuata passando due parametri:

La pagina di pagamento acquisisce i parametri e verifica i controlli di identità (deve esserci un riferimento ad un merchant conosciuto) e i dati di sicurezza (il parametro b deve corrispondere alla stringa criptata comunicata dall’esercente durante la fase precedente).

Se i controlli hanno buon esito, la pagina di pagamento viene mostrata all’acquirente che può inserire i dati necessari a completare il pagamento.

Se i controlli falliscono, la pagina di pagamento non viene mostrata e il processo passa ad un’altra fase per comunicare l’esito negativo.

Comunicazione del risultato della transazione

Axerve Ecommerce Solutions notifica il risultato della transazione attraverso una stringa criptata (il parametro b della call alla url specificata dal merchant o la proprietà EncryptedResponse dell’oggetto javascript Result). La stringa, una volta decodificata, permette di aggiornare lo stat della transazione registrata del sistema informativo dell’esercente.

La pagina scelta dal merchant per ricevere il risultato della transazione (sia nel caso di comunicazione server-to-server sia attraverso l’oggetto javascript Result) deve chiamare i server di Axerve per richiedere il servizio di decodifica e ottenere il risultato della transazione nella forma decodificata.

La richiesta di decodifica della stringa ricevuta può essere fatta attraverso di webservice. Non richiede nessuna installazione sul server ma semplicemente un call al webservice usando il protocollo https. La risposta avviene nel formato XML.

Autenticazione server-to-server

L’autenticazione del merchant richiedendo i servizi di crittazione o decodfica viene fatta verificando:

Se i controlli dell’autenticazione non hanno esito positivo viene restituito un errore specifico per identificarne le cause.