Gestpay diventa Axerve Ecommerce Solutions

Come iniziare

Questa guida ha lo scopo di fornire una semplice e rapida introduzione su come integrare Axerve Ecommerce Solutions nei tuoi applicativi.

Guida veloce

Axerve Ecommerce Solutions è il gateway online che permette di accettare pagamenti su qualsiasi piattaforma Ecommerce.

Axerve Ecommerce Solutions può essere integrato in due modi:

Step 0 – Registrazione al servizio

Prima di tutto è necessario registrarsi al backoffice del gateway. La registrazione è gratuita ed è fondamentale per poter accedere alla pagina di login.

In questa fase è possibile provare l’ambiente di test della piattaforma in tutte le sue parti e funzionalità in completa sicurezza e senza conseguenze.

Di seguito un tutorial con la URL ipotetica yourshop.com

Step 1 – Configurazione dell’account Axerve

Una volta effettuato l’accesso, è necessario specificare:

Nel caso in cui i server fossero in cloud, è possibile inserire un * per specificare indirizzi multipli.

Step 2 - SOAP

Prima di reindirizzare il cliente verso Axerve Ecommerce Solutions è necessario fare una chiamata SOAP verso il metodo WsCryptDecrypt.Encrypt per avviare la comunicazione. Cliccando sul link si accede alle API di riferimento.

Ci sono due endpoint disponibili:

https://sandbox.gestpay.net/gestpay/GestPayWS/WsCryptDecrypt.asmx?wsdl

https://ecommS2S.sella.it/gestpay/GestPayWS/WsCryptDecrypt.asmx?wsdl

Occorre iniziare con una chiamata SOAP ad Encrypt in cui si richiede ad Axerve Ecommerce Solutions di processare un pagamento con questi dati:

<Encrypt>
   <shopLogin>GESPAY12345</shopLogin><!-- Assigned by Axerve Ecommerce Solutions backend --> 
   <uicCode>242</uicCode> <!-- code for Euro --> 
   <amount>1245.6</amount> <!-- the money you want to receive -->
   <shopTransactionId>34az85ord19</shopTransactionId> <!-- an ID generated by you -->
</Encrypt>

Axerve Ecommerce Solutions risponde come segue:

<EncryptResult>
   <GestPayCryptDecrypt xmlns="">
   <TransactionType>ENCRYPT</TransactionType>
   <TransactionResult>OK</TransactionResult><!-- everything ok! -->
   <CryptDecryptString>2C53F1B5...</CryptDecryptString><!-- crypted string with sent info -->
   <ErrorCode>0</ErrorCode><!-- ...another way to say Ok! -->
   <ErrorDescription/>
   </GestPayCryptDecrypt>
</EncryptResult>

Con la stringa criptata (2C53F1B5...) e lo shopLogin è possibile reindirizzare l’utente verso la pagina di pagamento.

Arrivati a questo punto, è necessario scegliere il tipo di pagina di pagamento. Seguono le istruzioni per integrare la pagina di pagamento standard, per quelle relative alla pagina personalizzata basta cliccare su questo link.

Integrare la pagina di pagamento standard

Integrare la pagina di pagamento è semplice e non richiede particolari competenze di sviluppo, è sufficiente reindirizzare gli utenti verso il checkout:

Un esempio della pagina di scelta del pagamento. Se si è selezionato un solo pagamento disponibile, questa pagina non è visibile.
La pagina di pagamento con carta di credito.

Step 3: Reindirizzare il cliente su Axerve Ecommerce Solutions

Ora è possibile reindirizzare l’acquirente ad uno di questi due indirizzi:

https://sandbox.gestpay.net/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string>

https://ecomm.sella.it/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string>

Nell’esempio l’acquirente deve essere reindirizzato verso:

https://sandbox.gestpay.net/pagam/pagam.aspx?a=GESPAY12345&b=2C53F1B5...

Pagina nella quale vanno inseriti I dati della carta di pagamento.

Step 4: dopo il pagamento

Se sono stati seguiti tutti i passaggi correttamente, Axerve Ecommerce Solutions comunica l’esito all’acquirente e all’esercente.

Si possono configurare le URL di risposta all’interno del backoffice:

Cliccando su Configurazione -> Ambiente -> Indirizzi Risposte


Quando un pagamento viene completato senza errori, il gateway mostra l’esito positivo al cliente e all’esercente.

Esito del pagamento per l’esercente

Axerve Ecommerce Solutions comunica al server dell’esercente una stringa criptata con l’esito della transazione. La URL del server va inserita in URL Server to Server (opzionale).

Dato che la stringa è criptata, il server del merchant deve chiamare WsCryptDecrypt.Decrypt per decriptare la risposta e visualizzare l’output del gateway.

Su yourshop.com è stata configurata la pagina server-response.php che accetta due parametri: a (shopLogin) and b (stringa criptata). Così, Axerve Ecommerce Solutions invia un richiesta GET a Yourshop.com:

GET http://www.yourshop.com/server-response.php?a=GESPAY12345&b=2C53F1B5...

Ricevuti a e b, è possibile inviare la chiamata Decrypt (dal webservice WsCryptDecrypt) per conoscere l’esito della transazione ed aggiornare un database, inviare l’email di conferma al cliente ecc. ecc.

Maggiori informazioni sono disponibili su Pagina di pagamento standard – comunicazione dell’esito della transazione.

Esito del pagamento per l’acquirente

Una volta concluso un pagamento senza errori, Axerve Ecommerce Solutions ridireziona l’utente alla URL configurata in caso di risposta di successo. In caso contrario, verrà reindirizzato alla URL specificata per la risposta negativa.

Il reindirizzamento avviene con due parametri:

A questo punto il server del merchant deve effettuare la chiamata WsCryptDecrypt.Decrypt di nuovo per decriptare la risposta del gateway e mostrare il messaggio corretto al cliente.

Su Yourshop.com è stata configurata la stessa risposta sia per esito positivo sia per esito negativo. Naturalmente è possibile differenziare le due risposte. L’acquirente viene reindirizzato verso:

http://www.yourshop.com/response.php?a=GESPAY12345&b=2C53F1B5...

response.php occorre che sia una pagina che:

  • possa ricevere due argomenti, a e b.
  • decripti b
  • Mostri all’acquirente l’esito (ricevute, e-mail, …)

In conclusione

Questa guida contiene tutte le informazioni necessarie ad integrare il gateway Axerve Ecommerce Solutions. All’interno del backoffice è possibile verificare i pagamenti in entrata.

È possibile approfondire su Integrare la pagina di pagamento standard o continuare a leggere Cosa può fare per te Axerve Ecommerce Solutions

Integrare la pagina di pagamento personalizzata

Grazie alla pagina di pagamento personalizzata di Axerve Ecommerce Solutions, è possibile offrire un’esperienza personalizzata anche in fase di pagamento disegnando la pagina di checkout secondo le proprie preferenze.

Una rappresentazione grafica del flusso di pagamento. Se non viene richiesta l’autenticazione 3D, si può fare riferimento al flusso colorato di verde, in caso contrario il percorso a cui fare riferimento è quello in blu. Lo step 1 è il punto di partenza dalla pagina di checkout e lo step 2 è stato ampiamente descritto in precedenza. Vediamo insieme il resto del flusso.

Step 3: Importare script e check di sicurezza di Axerve Ecommerce Solutions

È sufficiente aggiungere:

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

Ed è già possibile scrivere Javascript per eseguire i check di sicurezza:

// BrowserEnabled is true if everything is OK 
if ( ! BrowserEnabled ) {
  // the browser is NOT supported
  alert('browser not supported!');
  return; 
}
// The Browser is supported!
// shopLogin and encryptedString come from Step 2... 
GestPay.CreatePaymentPage(shopLogin, encryptedString, pageLoadedCallback);

CreatePaymentPage crea un iframe nascosto che invia in sicurezza le credenziali ad Axerve Ecommerce Solutions.

pageLoadedCallback è una funzione che viene eseguita dopo la creazione dell’iframe nascosto. Vediamo di seguito:

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

  // SPOILER -- we'll talk later about this. 
  if (PARes) {
    var transKey = getCookie('transkey'); // use your preferred method to get cookies 
    handle3Dsecurity(PARes, transkey);
  }
}

Step 4: creare il form HTML

Creare il markup HTML per mostrare il form in cui vengono inseriti i dati di carta:

<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=""/>
  </fieldset> 
  <fieldset>
    <input type="submit" name="submit" value="Send Payment" id="submit" />
  </fieldset>
</form>

Come si vede in grafica, l’azione di submit non deve mandare dati al server. Questo è cruciale per essere compliant con i requisiti PCI: i dati di carta non devono mai essere visibili ai sistemi dell’esercente con questa configurazione.

Step 5 – Inviare la richiesta di pagamento

Dopo che l’acquirente ha compilato il form, viene chiamata la funzione checkCC(). Vediamo come implementarla:

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
  }, paymentCompletedCallback); 
  return false;
}

Gestire i protocolli 3D Secure

Nel caso in cui la carta di pagamento inserita e l’Ecommerce abbiano i protocolli 3D Secure attivi, al cliente potrebbe essere richiesta l’autenticazione Verified By Visa, Mastercard Identity Check (soluzione che ha sostituito Mastercard SecureCode) or Amex SafeKey.

Per determinare se è necessaria l’autenticazione è bene analizzare il campo ErrorCode:

ErrorCode descrizione
0 Pagamento completato con errori !
8006 È necessario gestire i protocolli 3D; l’utente deve autenticarsi. Questo accade solamente quando il sistema ritiene sia necessario.
Altri valori Si è verificato un altro tipo di errore e non è possibile proseguire con il pagamento.

In riferimento al diagramma di flusso, consideriamo lo step 6.

Cosa succede quando l’ErrorCode è 8006? In questa fase occorre reindirizzare il cliente verso la pagina di check dei protocolli 3D di Axerve Ecommerce Solutions, che è:

Il rendirizzare il cliente inviando lo shopLogin, la VBVRisp, e la url di atterraggio.

Qualcosa di simile a quanto sotto:

var paymentCompletedCallback = function(Result) { 
  if (Result.ErrorCode != 0) {
    if (Result.ErrorCode == 8006) { // 8006 : Card holder authorization required
      
      //Get the TransKey 
      //NOTE: you have to store this value somewhere (for example, in a cookie) 
      //for further use. After the redirect, you'll need this. 
      var TransKey = document.cookie = "transkey="+Result.TransKey;
      //Get the VBVRisp; we will need it soon ! 
      var VBVRisp = Result.VBVRisp;
      ...
      //place here the code to redirect the card holder to the authentication website
      redirect(shopLogin, VBVRisp, your_url);

      ...
    } else {
      //Call failed for other errors  
      //.... place here error handle code...
    } 
  } else {
    //Call went good. proceed to decrypt the Result.EncryptedResponse property
  }
}

Dopo aver effettuato correttamente l’autenticazione 3D, Axerve Ecommerce Solutions reindirizza il cliente alla pagina specificata. Ora è possibile verificare l’autenticazione attraverso il parametro PARES. Di seguito (Una recall di quanto presente allo step 2):

function pageLoadedCallback(result) {
  if(Result.ErrorCode != 10){  
    // An error has occurred
    return; 
  }
  ...
  //if 3d auth is successful, a parameter PaRes will be passed 
  // to this page (via POST). You can get it in some way 

  // e.g. in php: 
  var PaRes = <?= $_REQUEST["PaRes"]; ?>

  if (PaRes) {
    var transKey = getCookie('transkey'); // use your preferred method to get cookies 
    handle3Dsecurity(PaRes, transkey);
  }
}

Se le due variabili PARES e transKey sono state definite, è possibile completare il pagamento:

function handle3Dsecurity(PaRes, transkey) {

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

function paymentSuccededCallback(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
    var responseString = Result.EncryptedResponse;
  } 
}

Ottenuta la responseString, è possibile fare la chiamata WSCryptDecrypt’s Decrypt e verificare che tutto sia andato a buon fine. Lo stesso risultato viene spedito anche al server del merchant.

Per ulteriori informazioni sulla pagina di pagamento personalizzata accedere alla pagina creare una pagina di pagamento personalizzata.