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:
- tramite un pagina di pagamento standard;
- con una pagina di pagamento personalizzata secondo le proprie preferenze
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:
- l’indirizzo IP del tuo server (Axerve verificherà che le richieste di pagamento arrivino solo da quell’indirizzo)
- come gestire le transazioni (accettate e movimentate istantaneamente oppure accettate e movimentate in un secondo momento).
- A questo punto viene generato uno ShopLogin simile a GESPTAY1234 assegnato all’Ecommerce.

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:
- Ambiente di Test:
https://sandbox.gestpay.net/gestpay/GestPayWS/WsCryptDecrypt.asmx?wsdl
- Ambiente di produzione:
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:
- Axerve gestisce la sicurezza delle transazioni
- Si possono scegliere i sistemi di pagamento attivati da mostrare, come PayPal, HYPE o MyBank
- È possibile personalizzare il layout inserendo il proprio logo


Step 3: Reindirizzare il cliente su Axerve Ecommerce Solutions
Ora è possibile reindirizzare l’acquirente ad uno di questi due indirizzi:
- Ambiente di test
https://sandbox.gestpay.net/pagam/pagam.aspx?a=<ShopLogin>&b=<encrypted string>
- Ambiente di produzione
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:

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
eb
, è possibile inviare la chiamataDecrypt
(dalwebservice 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
che è loshopLogin
b
che contiene una stringa criptata con l’esito della transazione
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.

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 è:
https://ecomm.sella.it/pagam/pagam3d.aspx
(in produzione)https://sandbox.gestpay.net/pagam/pagam3d.aspx
(in ambiente di test)
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.