Gestpay becomes Axerve Ecommerce Solutions

Getting Started

Hi! This guide wants to give you a very rapid introduction about how you can integrate Axerve Ecommerce Solutions in your application.

Super Quick Start Guide

In case you still don’t know what Axerve Ecommerce Solutions is, it is the piece of software that will allow you to accept payments from your customers.

Axerve Ecommerce Solutions can be integrated on your website in two ways:

The first steps are equal, whatever payment method you prefer.

Step 0 - Signing up

First of all, you have to register on Axerve backoffice. To try it out Axerve Ecommerce Solutions I suggest you to sign in to the Test Environment (it’s free!) and then login.

Remember, it’s a test environment, you can mess it up as you like, there’s no real money involved.

To follow this tutorial, let’s pretend that your website responds to the URL yourshop.com .

Step 1 - Configure your Axerve account

Once you’re in, Axerve Ecommerce Solutions wants to know:

In case your server is in a cloud environment, you can use * to specify multiple addresses.

Step 2 - take the SOAP

Before you can actually redirect the user to Axerve Ecommerce Solutions, you must do a SOAP call to WsCryptDecrypt.Encrypt method to initiate the communication. Click on the link to see the API.

There are two endpoints available,

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

Let’s go back to your application. Everything starts with a SOAP call to the Encrypt , asking Axerve Ecommerce Solutions to process a payment with these info:

<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 will answer with:

<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> 

With the encrypted string (2C53F1B5...) and the shopLogin you can now redirect the user to the payment page.

Now you have to choose which payment page you want to use. If you want to use standard payment page, keep reading. Otherwise, jump to using your customized payment page.

Using standard Payment Page

Using standard payment page is the most straightforward way to accept payments from customers. You don’t need special coding skills and you only have to redirect your users to the page.

An example of the "choose payment" page. If only one payment method is selected, you will not see it.
A credit card payment page.

step 3: Redirecting the user to Axerve Ecommerce Solutions

At this point, you can redirect the user to one of these two addresses:

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

In our example, the user must be redirected to

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

where he will be asked for his credit card data.

step 4: After the payment

If everything has gone correctly, Axerve Ecommerce Solutions will communicate the outcome to the user and the merchant.

You can configure where Axerve must redirect with the following window:

you can find this window in Configuration -> Environment -> Response Address.


When a payment is completed without errors, Axerve Ecommerce Solutions will report the result to both the merchant and the user.

Returning the result to the Merchant

Axerve Ecommerce Solutions will communicate to the merchant’s server an encrypted string with the result of the transaction. The url of your server must be inserted in URL Server to Server (by the way, this is optional).

Since the string is encrypted, the merchant’ server must call WsCryptDecrypt.Decrypt to decrypt Axerve Ecommerce Solutions response and see the output.

At yourshop.com we have set up the page server-response.php. This page will take two parameters,a (the shopLogin) and b (the encrypted string). So Axerve Ecommerce Solutions will perform a GET request to Yourshop.com:

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

Once the server has received a and b, he can now call the Decrypt method (from the WsCryptDecrypt webservice) and know the result of the transaction, useful for updating the database, send emails, etc.

More information on this at Using standard payment page - communication of transaction result.

Returning the result to the User

When a payment is completed without errors, Axerve Ecommerce Solutions will redirect the user to the URL that is configured in URL for positive response - Similarly, if anything goes wrong, he will be redirected to the URL for negative response.

The redirection occours with two parameters:

at this point the Merchant’s Server must call WsCryptDecrypt.Decrypt again to decrypt Axerve Ecommerce Solutions response and show the appropriate message to the user.

At Yourshop.com we have set up the same response page in case of positive or negative response. Of course you can differentiate the two. The user will be redirected to

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

response.php must be a page that will:

  • Receive two arguments, a and b.
  • Decrypt b
  • Show the result to the user (receipts, email…)

That’s it ?

Yes! go and check your backoffice page - you should see payments coming in.

You can get further details at Using Standard Payment Page or continue to read what Axerve Ecommerce Solutions can do for you.

Using your customized payment page

With a customized payment page, you can customize every part of the payment process and design the credit card form exactly the way you want. This means you can avoid to redirect your customers to other pages and handle everything in one page.

A graphic rapresentation of the flow. If no 3d authentication is required, only the green path is followed: it is very straightforward. However, if Axerve requires 3d authentication for fraud prevention, then you start following the blue path. Step 1 is our starting point; step 2 has been discussed previously in this tutorial.

step 3: Import Axerve Ecommerce Solutions script & security ckecks

It’s easy as adding

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

We can already write some Javascript to perform some security checks:

// 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 will create an hidden iframe that will securely send credentials to Axerve Ecommerce Solutions.

pageLoadedCallback is a function that will be fired after the creation of the hidden iframe. Let’s see it:

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: create the HTML form

Create the html markup to show the credit card form:

<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>

As you can see, the submit action must not send data to the server. This is crucial to adhere with PCI requirements. You should never see credit card numbers, never ever.

Step 5 - Send the payment

When the user submits the form, the checkCC() function will be called. Let’s see how we could implement this:

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;
} 

Handling 3D Security

Axerve Ecommerce Solutions may ask, to reduce the risk of fraud, to authenticate the card against Verified By Visa, Mastercard SecureCode or Amex SafeKey.

To determine if this is the case, let’s analyze ErrorCode field:

ErrorCode description
0 payment completed without errors!
8006 we must handle 3DSecurity; user must validate his credit card against Visa, or Mastercard, or what else. This does not happen always, only when the system believes it is necessary.
any other value another type of error has occurred, unable to continue the payment.

Referring to the flow diagram, we are now considering step 6.

what happens when the ErrorCode is 8006? In this phase, we must redirect the user to Axerve Ecommerce Solutions 3d secure check page, which is

Redirect the user sending the shopLogin, the VBVRisp, and a url to where the user must be redirected.

In our code it would be something like this:

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
  }
}

After 3d secure happens succesfully, Axerve Ecommerce Solutions will redirect to the page you have configured. Now we have to know that we have successfully authenticated via the PARES parameter. Here is the code (Recall the code in 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);
  }
} 

if the two variables PARES and transKey are defined, we can complete the payment:


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;
  } 
} 

Now that you have the responseString, you can call the WSCryptDecrypt’s Decrypt method and verify that everything has gone good. The same outcome will be sent to your server, too.

That’s it! For further reading about customizing your payment page, go to creating your custom payment page.